forge-proof 0.1.0a5__tar.gz

forge_proof-0.1.0a5/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: forge-proof
+Version: 0.1.0a5
+Summary: Forge reference proof tooling: forge proof check/derive/replay/bundle — a Proof-Standard evidence bundle from events.log alone. Stdlib-only core; optional matplotlib+networkx for graph.png.
+Author-email: Sanjay Davis <psanjuknl@gmail.com>
+License-Expression: MIT
+Keywords: forge,proof,evidence,sdk,autonomous-software
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# forge-proof
+
+Reference proof evidence tooling for [Forge](https://github.com/SanjayDavis/Forge):
+a stdlib-only, kernel-free CLI that turns a raw `events.log` into a complete
+[Proof Standard](https://github.com/SanjayDavis/Forge/blob/master/proofs/PROOF_SPEC.md)
+artifact bundle — no manual steps, no LLM in the loop.
+
+```
+forge proof check   <dir>   validate a bundle against the §6 checklist
+forge proof derive  <dir>   derive graph.json/metrics.json/replay facts from events.log (§5)
+forge proof replay  <dir>   render replay.md (Goal/Outcome/Timeline/Turning points)
+forge proof bundle  <dir>   emit the full bundle + validate (net-new artifacts only;
+                            curated README/replay.md/media are never clobbered,
+                            derived artifacts are verified byte-identical)
+```
+
+Installing this package registers the `forge proof` command through the
+`forge.commands` entry-point group — same mechanism as `forge plan` from
+forge-planner.
+
+Design constraints (Proof Standard §7 / repo plan):
+- **stdlib-only**: no runtime dependencies; `graph.png` rendering uses
+  matplotlib+networkx when present in the invoking python, otherwise a
+  clear hint instead of a crash.
+- **kernel-free**: never imports `forge`; the event log is read as raw
+  JSON lines, so the proof pipeline cannot disturb project state.
+- **reproducible**: derived artifacts are a pure function of `events.log`
+  — byte-identical across runs and byte-identical to the canonical
+  `tools/proof-derive.py` (pinned by tests).

forge_proof-0.1.0a5/README.md

@@ -0,0 +1,29 @@
+# forge-proof
+
+Reference proof evidence tooling for [Forge](https://github.com/SanjayDavis/Forge):
+a stdlib-only, kernel-free CLI that turns a raw `events.log` into a complete
+[Proof Standard](https://github.com/SanjayDavis/Forge/blob/master/proofs/PROOF_SPEC.md)
+artifact bundle — no manual steps, no LLM in the loop.
+
+```
+forge proof check   <dir>   validate a bundle against the §6 checklist
+forge proof derive  <dir>   derive graph.json/metrics.json/replay facts from events.log (§5)
+forge proof replay  <dir>   render replay.md (Goal/Outcome/Timeline/Turning points)
+forge proof bundle  <dir>   emit the full bundle + validate (net-new artifacts only;
+                            curated README/replay.md/media are never clobbered,
+                            derived artifacts are verified byte-identical)
+```
+
+Installing this package registers the `forge proof` command through the
+`forge.commands` entry-point group — same mechanism as `forge plan` from
+forge-planner.
+
+Design constraints (Proof Standard §7 / repo plan):
+- **stdlib-only**: no runtime dependencies; `graph.png` rendering uses
+  matplotlib+networkx when present in the invoking python, otherwise a
+  clear hint instead of a crash.
+- **kernel-free**: never imports `forge`; the event log is read as raw
+  JSON lines, so the proof pipeline cannot disturb project state.
+- **reproducible**: derived artifacts are a pure function of `events.log`
+  — byte-identical across runs and byte-identical to the canonical
+  `tools/proof-derive.py` (pinned by tests).

forge_proof-0.1.0a5/forge_proof/__init__.py

@@ -0,0 +1,12 @@
+"""forge-proof — the reference proof evidence pipeline.
+
+`forge proof check/derive/replay/bundle` over a Proof-Standard bundle
+(proofs/PROOF_SPEC.md): derive machine-readable artifacts from
+events.log alone (§5), render replay.md and graph.png, scaffold README,
+and validate the full §6 conformance checklist. Stdlib-only; the kernel
+stays out of scope — this package is a client of the artifacts, never
+of the event API.
+"""
+__version__ = "0.1.0a5"
+
+__all__ = ["__version__", "check", "derive", "replay", "bundle"]

forge_proof-0.1.0a5/forge_proof/bundle.py

@@ -0,0 +1,259 @@
+"""`forge proof bundle` — emit a complete Proof-Standard artifact bundle.
+
+On a live project dir (events.log present, nothing else): derives
+graph.json/metrics.json/demo/_replay_facts.md, renders replay.md and
+graph.png, scaffolds README.md, then runs the full §6 conformance
+checklist. Run-captured media that a machine cannot synthesize
+(screenshots/, demo.mp4 without a transcript, run.py) are reported as
+gaps, not fabricated.
+
+On an existing proof dir (examples/swarm): NEVER clobbers. The derived
+artifacts are re-derived in a temp copy and verified byte-identical (the
+§5 reproducibility rule); the curated README/replay.md/demo.mp4 are left
+untouched; the bundle ends with the conformance verdict.
+
+Deps: core derivation is stdlib-only; graph.png rendering additionally
+needs matplotlib+networkx (optional — bundle still succeeds without
+them, graph.png is reported as a gap).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from . import check as proof_check
+from . import derive as proof_derive
+from . import replay as proof_replay
+
+_TOOLS = Path(__file__).resolve().parents[3] / "tools"
+
+
+# ------------------------------------------------------------------ graph.png
+def _render_graph(root: Path) -> bool:
+    """Render graph.png from graph.json (in-process, optional matplotlib)."""
+    try:
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+        import networkx as nx
+        from matplotlib.patches import FancyBboxPatch
+    except Exception as e:
+        print(f"  hint: graph.png not rendered — install matplotlib+networkx ({e})")
+        return False
+    try:
+        data = json.loads((root / "graph.json").read_text(encoding="utf-8"))
+        G = nx.DiGraph()
+        for t in data["tasks"]:
+            G.add_node(t["id"], status=t["status"],
+                       subsystem=t.get("subsystem", "other"), title=t["title"])
+        for e in data["dependencies"]:
+            G.add_edge(e["depends_on"], e["task"])
+        rank = {}
+        for n in G.nodes:
+            rank[n] = 0
+        changed = True
+        while changed:
+            changed = False
+            for u, v in G.edges:
+                if rank[v] < rank[u] + 1:
+                    rank[v] = rank[u] + 1
+                    changed = True
+        levels = {}
+        for n, r in rank.items():
+            levels.setdefault(r, []).append(n)
+        pos = {}
+        for r, nodes in levels.items():
+            for i, n in enumerate(sorted(nodes)):
+                pos[n] = (i - (len(nodes) - 1) / 2, -r)
+        depth = max(rank.values(), default=0)
+        fig, ax = plt.subplots(figsize=(11, 6 + 1.1 * depth))
+        ax.set_axis_off()
+        ax.set_title(f"{data['proof']} — final dependency graph\n"
+                     f"{data.get('forge_version', '')} · "
+                     f"{len(data['tasks'])} tasks · {len(data['dependencies'])} edges",
+                     fontsize=13)
+        nx.draw_networkx_edges(G, pos, ax=ax, arrows=True, arrowstyle="-|>",
+                               arrowsize=13, edge_color="#888888",
+                               connectionstyle="arc3,rad=0.08")
+        colors = {"done": "#2e7d32", "in_progress": "#f9a825",
+                  "needs_revision": "#c62828", "todo": "#9e9e9e",
+                  "other": "#37474f"}
+        for n, d in G.nodes(data=True):
+            fill = colors.get(d["status"], "#9e9e9e")
+            x, y = pos[n]
+            w = max(len(n), len(d["title"][:26])) * 0.075 + 0.3
+            h = 0.78
+            ax.add_patch(FancyBboxPatch((x - w / 2, y - h / 2), w, h,
+                                        boxstyle="round,pad=0.02,rounding_size=0.08",
+                                        fc=fill, ec="#37474f", lw=2.2))
+            ax.annotate(n, (x, y + 0.14), ha="center", va="center", fontsize=9,
+                        color="white", fontweight="bold")
+            ax.annotate(d["title"][:26], (x, y - 0.3), ha="center", va="center",
+                        fontsize=6.4, color="#222222")
+        handles = [plt.Line2D([0], [0], marker="s", ls="", markersize=11,
+                              markerfacecolor=c, markeredgecolor="#000",
+                              label=str(s)) for s, c in colors.items()]
+        ax.legend(handles=handles, loc="upper left", bbox_to_anchor=(1.0, 1.0),
+                  frameon=True, fontsize=8, title="status")
+        fig.tight_layout()
+        fig.savefig(root / "graph.png", dpi=150, bbox_inches="tight",
+                    facecolor="white")
+        plt.close(fig)
+        return True
+    except Exception as e:
+        print(f"  hint: graph.png render failed: {e}")
+        return False
+
+
+# ------------------------------------------------------------------- README.md
+_README_SECTIONS = [
+    ("What was built", "_(write one paragraph — what ran and what it produced)_"),
+    ("Why this proof exists", "_(the claim this proof answers; list Claim IDs — see proposal.json)_"),
+    ("Final architecture", "_(subsystem breakdown with dependency arrows — see graph.png)_"),
+    ("Commands", "- `forge proof bundle .` (this bundle was assembled by it)\n- build/test commands used during the run"),
+    ("Reproduce", "_(seed prompt, planner/executor/verifier used, Forge version)_"),
+    ("Artifact index", "- `events.log` — raw Forge history (single source of truth)\n- `graph.json` / `graph.png` — final dependency graph\n- `replay.md` — seq-cited timeline\n- `metrics.json` — comparable numbers\n- `screenshots/` — at least 2 captures\n- `demo.mp4` — <= 2 min of the run"),
+    ("Behavior notes", "_(anything non-obvious discovered during the run)_"),
+    ("Lessons learned", "_(insights about the project, Forge, or the domain)_"),
+]
+
+
+def _scaffold_readme(root: Path, metrics: dict) -> None:
+    claims = metrics.get("claims") or []
+    why = ("Proof answers claim" + ("s" if len(claims) != 1 else "") +
+           f": {', '.join(claims)}."
+           if claims else "_(list Claim IDs — see proposal.json)_")
+    body = [f"# {root.name} — proof bundle",
+            "",
+            f"Automatically scaffolded by `forge proof bundle` "
+            f"(Forge {metrics.get('forge_version', 'unknown')}). "
+            "Fill the placeholders, keep the section names.",
+            ""]
+    for title, filler in _README_SECTIONS:
+        body += [f"## {title}", "", filler, ""]
+    body.append("---\n")
+    body.append("*Reported numbers are log-derived (see metrics.json).*")
+    (root / "README.md").write_text("\n".join(body) + "\n", encoding="utf-8")
+
+
+# ------------------------------------------------------------------ demo.mp4
+def _render_demo(root: Path) -> bool:
+    transcript = root / "demo" / "transcript.txt"
+    script = _TOOLS / "proof-render-demo.py"
+    if not transcript.exists() or not script.exists():
+        return False
+    try:
+        subprocess.run([sys.executable, str(script), str(root), str(transcript)],
+                       check=True, capture_output=True, text=True, timeout=300)
+        return True
+    except Exception as e:
+        print(f"  hint: demo.mp4 render failed: {e}")
+        return False
+
+
+# ------------------------------------------------------------------ bundle
+def _sha(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _verify_derived_byte_identical(root: Path, forge_version: str) -> bool:
+    """Re-derive in a temp dir NAMED after the proof (the 'proof' field of
+    graph.json is the directory name) and compare bytes — the §5
+    reproducibility rule, same inputs as check_invariants S7."""
+    # Pin the derive stamp to the version the shipped artifacts claim —
+    # otherwise a repo version bump (or a caller passing today's version)
+    # reports byte-drift against artifacts stamped at their own
+    # derivation version. Same rule as check_invariants S7.
+    claimed = (root / "graph.json").exists() and json.loads(
+        (root / "graph.json").read_text(encoding="utf-8")).get("forge_version")
+    if claimed:
+        forge_version = claimed
+    if not (root / "graph.json").exists() or not (root / "metrics.json").exists():
+        return True
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td) / root.name
+        tmp.mkdir()
+        for fname in ("events.log", "proposal.json"):
+            src = root / fname
+            if src.exists():
+                (tmp / fname).write_bytes(src.read_bytes())
+        proof_derive.derive_dir(str(tmp), forge_version=forge_version)
+        if (tmp / "graph.json").exists() and (root / "graph.json").exists():
+            same_g = _sha(tmp / "graph.json") == _sha(root / "graph.json")
+            same_m = _sha(tmp / "metrics.json") == _sha(root / "metrics.json")
+            return same_g and same_m
+        return True if not (root / "graph.json").exists() else True
+
+
+def bundle_dir(proof_dir, forge_version="unknown"):
+    root = Path(proof_dir)
+    emitted: list[str] = []
+    verified: list[str] = []
+    skipped: list[str] = []
+
+    if not (root / "events.log").exists():
+        print(f"error: {root} has no events.log — bundle needs a Forge project "
+              "or proof dir with a raw event log", file=sys.stderr)
+        return 1
+
+    # 1. derived artifacts: write when missing, verify byte-identity when present
+    if not (root / "graph.json").exists() or not (root / "metrics.json").exists():
+        proof_derive.derive_dir(str(root), forge_version=forge_version)
+        emitted += ["graph.json", "metrics.json", "demo/_replay_facts.md"]
+    elif _verify_derived_byte_identical(root, forge_version):
+        verified += ["graph.json + metrics.json byte-identical after re-derive"]
+    else:
+        print("  problem: re-derived graph.json/metrics.json differ from the "
+              "shipped files — the log was edited or derive drifted",
+              file=sys.stderr)
+
+    # 2. replay.md (rendered, never clobbered)
+    if not (root / "replay.md").exists():
+        proof_replay.render_dir(str(root))
+        emitted.append("replay.md")
+    else:
+        skipped.append("replay.md (curated — left untouched)")
+
+    # 3. graph.png
+    if not (root / "graph.png").exists():
+        if _render_graph(root):
+            emitted.append("graph.png")
+    else:
+        skipped.append("graph.png (existing — left untouched)")
+
+    # 4. README.md scaffold
+    if not (root / "README.md").exists():
+        metrics = json.loads((root / "metrics.json").read_text(encoding="utf-8"))
+        _scaffold_readme(root, metrics)
+        emitted.append("README.md (scaffold — fill the placeholders)")
+    else:
+        skipped.append("README.md (curated — left untouched)")
+
+    # 5. demo.mp4 from a captured transcript (never clobbered)
+    if not (root / "demo.mp4").exists():
+        if _render_demo(root):
+            emitted.append("demo.mp4 (rendered from demo/transcript.txt)")
+    else:
+        skipped.append("demo.mp4 (existing — left untouched)")
+
+    for s in skipped:
+        print(f"  kept: {s}")
+    if emitted:
+        print(f"  emitted: {', '.join(emitted)}")
+    if verified:
+        print(f"  verified: {', '.join(verified)}")
+    if not emitted and not verified:
+        print(f"  no changes: all nine artifacts already present")
+
+    probs = proof_check.problems(root)
+    if probs:
+        print("  note: the gaps below are run-captured (record them, re-run "
+              "bundle):" if all("screenshots" in p or "demo.mp4" in p or "run.py" in p
+                                for p in probs) else
+              "  note: conformance gaps:")
+    return proof_check.verdict(root, probs)

forge_proof-0.1.0a5/forge_proof/check.py

@@ -0,0 +1,152 @@
+"""Vendored proof conformance check (port of tools/proof-check.py).
+
+Implements the Proof Standard §6 conformance checklist exactly as the
+canonical tools/ script does — same constants, same problems —
+so `forge proof check` and `tools/proof-check.py` agree on any bundle.
+Stdlib only; ffprobe is invoked only when demo.mp4 exists.
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from collections import Counter
+from pathlib import Path
+
+REQUIRED_FILES = ["README.md", "events.log", "graph.json", "graph.png",
+                  "replay.md", "metrics.json", "demo.mp4"]
+REQUIRED_METRICS = ["proof", "status", "language", "tasks", "events",
+                    "verification_passes", "verification_failures", "retries",
+                    "duration_minutes", "llm", "forge_version", "conforms_to",
+                    "claims"]
+README_SECTIONS = ["What was built", "Why this proof exists", "Final architecture",
+                   "Commands", "Reproduce", "Artifact index", "Behavior notes",
+                   "Lessons learned"]
+
+
+def problems(root: Path):
+    """Full §6 checklist. Returns a list of problem strings ([] = conforming)."""
+    out = []
+
+    readme = root / "README.md"
+    if not readme.exists():
+        out.append("missing README.md")
+    else:
+        text = readme.read_text(encoding="utf-8")
+        for sec in README_SECTIONS:
+            if not re.search(r"^#{1,3}\s+.*" + re.escape(sec), text, re.M):
+                out.append(f"README missing section: {sec}")
+
+    ev_file = root / "events.log"
+    events = []
+    if not ev_file.exists():
+        out.append("missing events.log")
+    else:
+        for i, line in enumerate(ev_file.read_text(encoding="utf-8").splitlines(), 1):
+            if not line.strip():
+                continue
+            try:
+                ev = json.loads(line)
+            except json.JSONDecodeError:
+                out.append(f"events.log line {i} is not valid JSON")
+                continue
+            events.append(ev)
+        if events:
+            seqs = [e["seq"] for e in events if "seq" in e]
+            if seqs != list(range(1, len(seqs) + 1)):
+                out.append("events.log seq not contiguous from 1")
+            counts = Counter(e["op"] for e in events)
+            if not any(op.startswith("task_created") for op in counts):
+                out.append("events.log has no task_created events")
+
+    gf = root / "graph.json"
+    if not gf.exists():
+        out.append("missing graph.json")
+    else:
+        g = json.loads(gf.read_text(encoding="utf-8"))
+        for t in g.get("tasks", []):
+            for k in ("id", "title", "status", "priority"):
+                if k not in t:
+                    out.append(f"graph.json task {t.get('id')} missing '{k}'")
+        if events:
+            created = {e["id"] for e in events if e["op"] == "task_created"}
+            gids = {t["id"] for t in g.get("tasks", [])}
+            if gids != created:
+                out.append("graph.json task ids differ from events.log")
+            deps = {(e["depends_on"], e["task"]) for e in events
+                    if e["op"] == "dependency_added"}
+            gdeps = {(d["depends_on"], d["task"]) for d in g.get("dependencies", [])}
+            if gdeps != deps:
+                out.append("graph.json dependencies differ from events.log")
+
+    for f in ("graph.png", "replay.md"):
+        p = root / f
+        if not p.exists():
+            out.append(f"missing {f}")
+    if (root / "replay.md").exists():
+        rt = (root / "replay.md").read_text(encoding="utf-8")
+        for kw in ("Goal", "Outcome", "Timeline", "Turning points"):
+            if kw not in rt:
+                out.append(f"replay.md missing '{kw}'")
+
+    mf = root / "metrics.json"
+    if not mf.exists():
+        out.append("missing metrics.json")
+    else:
+        m = json.loads(mf.read_text(encoding="utf-8"))
+        for k in REQUIRED_METRICS:
+            if k not in m:
+                out.append(f"metrics.json missing field '{k}'")
+        if events and "tasks" in m and "events" in m:
+            if m["tasks"] != len({e["id"] for e in events if e["op"] == "task_created"}):
+                out.append("metrics.json 'tasks' != log task count")
+            if m["events"] != len(events):
+                out.append("metrics.json 'events' != log line count")
+            counts = Counter(e["op"] for e in events)
+            pairs = [("verification_passes", "verification_passed"),
+                     ("verification_failures", "verification_failed"),
+                     ("retries", "task_retried")]
+            for key, op in pairs:
+                if key in m and m[key] != counts.get(op, 0):
+                    out.append(f"metrics.json '{key}' != log count ({m[key]} vs {counts.get(op, 0)})")
+
+    shots = sorted((root / "screenshots").glob("*.png")) if (root / "screenshots").exists() else []
+    if len(shots) < 2:
+        out.append(f"screenshots/ has {len(shots)} PNGs (need >= 2)")
+
+    demo = root / "demo.mp4"
+    if demo.exists():
+        try:
+            r = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0",
+                                "-show_entries", "stream=width,height",
+                                "-show_entries", "format=duration",
+                                "-of", "json", str(demo)], capture_output=True, text=True)
+            info = json.loads(r.stdout)
+            dur = float(info["format"]["duration"])
+            w, h = info["streams"][0]["width"], info["streams"][0]["height"]
+            if dur > 120:
+                out.append(f"demo.mp4 too long: {dur:.0f}s (> 120s)")
+            if w > 1280 or h > 720:
+                out.append(f"demo.mp4 too large: {w}x{h} (> 720p)")
+        except Exception as e:
+            out.append(f"demo.mp4 unreadable: {e}")
+
+    if not (root / "run.py").exists():
+        out.append("no run.py entrypoint (README commands not checkable)")
+
+    idx = root.parent.parent / "proofs" / "INDEX.md"
+    if idx.exists() and root.name not in idx.read_text(encoding="utf-8"):
+        out.append(f"no INDEX.md entry for {root.name}")
+
+    return out
+
+
+def verdict(proof_dir, problems_list):
+    root = Path(proof_dir)
+    if problems_list:
+        print(f"NON-CONFORMING: {root.name}")
+        for p in problems_list:
+            print(f"  - {p}")
+        return 1
+    print(f"CONFORMING: {root.name} — all checks pass")
+    return 0

forge_proof-0.1.0a5/forge_proof/cli.py

@@ -0,0 +1,83 @@
+"""CLI registration for forge-proof (the `proof` command).
+
+Follows the forge.commands entry-point contract (see forge/plugins.py):
+``register(subparsers)`` adds the `proof` subparser with its own
+argument shape and returns the handler map. The handler never receives
+a Kernel (main() dispatches proof outside the project gate) — proof
+tooling is stdlib-only and kernel-free by design.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import check as proof_check
+from . import derive as proof_derive
+from . import replay as proof_replay
+from .bundle import bundle_dir
+
+
+def register(subparsers: argparse._SubParsersAction) -> dict:
+    """Entry point for ``forge.commands``: add `proof` and return its handler."""
+    c = subparsers.add_parser(
+        "proof", help="proof evidence pipeline: check / derive / replay / "
+                     "bundle (provided by forge-proof)")
+    sub = c.add_subparsers(dest="proof_cmd", required=True, metavar="SUB",
+                           title="proof subcommands")
+    pc = sub.add_parser("check", help="validate a proof bundle against the "
+                         "Proof Standard §6 conformance checklist")
+    pc.add_argument("dir")
+    pd = sub.add_parser("derive", help="derive graph.json/metrics.json/replay "
+                         "facts from events.log (§5 derivation rule)")
+    pd.add_argument("dir")
+    pd.add_argument("--forge-version", default="unknown")
+    pd.add_argument("--snapshot", default=None,
+                    help="also copy graph.json to demo/snapshots/<name>.graph.json")
+    pr = sub.add_parser("replay", help="render replay.md from the derived facts "
+                         "(Goal/Outcome/Timeline/Turning points, seq citations)")
+    pr.add_argument("dir")
+    pb = sub.add_parser("bundle", help="emit the full artifact bundle "
+                         "(README/events.log/graph.json/graph.png/replay.md/"
+                         "metrics.json/screenshots/demo.mp4) and validate it")
+    pb.add_argument("dir")
+    pb.add_argument("--forge-version", default="unknown")
+    return {"proof": cmd_proof}
+
+
+def _req_dir(path: str) -> Path | None:
+    root = Path(path)
+    if not root.is_dir():
+        print(f"error: {path} is not a directory", file=sys.stderr)
+        return None
+    return root
+
+
+def cmd_proof(args, k=None) -> int:
+    """Handler for all proof subcommands (k is always None — proof never
+    needs a project Kernel; main() bypasses the project gate for it)."""
+    root = _req_dir(args.dir)
+    if root is None:
+        return 1
+    if args.proof_cmd == "check":
+        return proof_check.verdict(root, proof_check.problems(root))
+    if args.proof_cmd == "derive":
+        try:
+            proof_derive.derive_dir(str(root), forge_version=args.forge_version,
+                                    snapshot=args.snapshot)
+            return 0
+        except FileNotFoundError:
+            print(f"error: {root / 'events.log'} not found — nothing to derive",
+                  file=sys.stderr)
+            return 1
+    if args.proof_cmd == "replay":
+        try:
+            proof_replay.render_dir(str(root))
+            return 0
+        except FileNotFoundError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+    if args.proof_cmd == "bundle":
+        return bundle_dir(str(root), forge_version=args.forge_version)
+    print(f"error: unknown proof subcommand {args.proof_cmd!r}", file=sys.stderr)
+    return 1

forge_proof-0.1.0a5/forge_proof/derive.py

@@ -0,0 +1,227 @@
+"""Vendored proof derivation (byte-faithful port of tools/proof-derive.py).
+
+Reproduces graph.json and metrics.json solely from events.log, per the
+Forge Proof Standard derivation rule (proofs/PROOF_SPEC.md §5), plus
+demo/_replay_facts.md. The port keeps the canonical tools/ script's exact
+logic and JSON serialization so both produce byte-identical artifacts —
+that parity is pinned by tests/test_proof_core.py. Stdlib only.
+"""
+from __future__ import annotations
+
+import json
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+
+FIELD_DEFAULTS = {
+    "forge_version": "unknown",
+    "conforms_to": "proof-spec-0.1",
+    "language": "python",
+}
+
+_LANGUAGE_HINTS = [
+    ("rs", "Rust"),
+    ("cpp", "C++"), ("cc", "C++"), ("cxx", "C++"),
+    ("hpp", "C++"), ("hxx", "C++"),
+    ("py", "python"), ("pyw", "python"),
+]
+
+
+def _subsystem_of(e):
+    for note in e.get("notes") or []:
+        if str(note).strip().startswith("subsystem:"):
+            return str(note).split(":", 1)[1].strip()
+    return None
+
+
+def _infer_language(events):
+    """Primary implementation language, inferred from file references in the
+    log (task descriptions, evidence records). Pure function of events.log."""
+    import re as _re
+    hits = Counter()
+    stack = list(events)
+    while stack:
+        v = stack.pop()
+        if isinstance(v, dict):
+            stack.extend(v.values())
+        elif isinstance(v, list):
+            stack.extend(v)
+        elif isinstance(v, str):
+            for ext, lang in _LANGUAGE_HINTS:
+                if _re.search(r"\.%s\b" % ext, v):
+                    hits[lang] += 1
+    if not hits:
+        return FIELD_DEFAULTS["language"]
+    return max(hits, key=lambda lang: (hits[lang], -("C++|Rust|python".split("|").index(lang))))
+
+
+def _infer_claims(events, root):
+    claims = [c for e in events if e["op"] == "claims_claimed"
+              for c in e.get("claims", [])]
+    if not claims:
+        prop = root / "proposal.json"
+        if prop.exists():
+            claims = json.loads(prop.read_text(encoding="utf-8")).get("claims", [])
+    return claims
+
+
+def replay(events):
+    """Reconstruct final task state and edge list from the event log."""
+    status = {}
+    priority = {}
+    title = {}
+    subsystem = {}
+    edges = []
+    milestones = []
+    meta = {
+        "op_counts": Counter(e["op"] for e in events),
+        "first_ts": min(e.get("ts") for e in events if e.get("ts")),
+        "last_ts": max(e.get("ts") for e in events if e.get("ts")),
+        "proposal_id": next((e["id"] for e in events if e["op"] == "proposal_committed"), None),
+    }
+    for e in events:
+        op, seq = e["op"], e["seq"]
+        if op == "task_created":
+            status[e["id"]] = "todo"
+            priority[e["id"]] = e.get("priority", "medium")
+            title[e["id"]] = e.get("title", e["id"])
+            subsystem[e["id"]] = _subsystem_of(e)
+            milestones.append((seq, "task_created", e["id"], "planned"))
+        elif op == "task_started":
+            status[e["id"]] = "in_progress"
+        elif op == "verification_failed":
+            status[e["id"]] = "needs_revision"
+            milestones.append((seq, "verification_failed", e["id"], e.get("reason", "")))
+        elif op == "verification_passed":
+            status[e["id"]] = "done"
+            milestones.append((seq, "verification_passed", e["id"], ""))
+        elif op == "task_reopened":
+            status[e["id"]] = "todo"
+            milestones.append((seq, "task_reopened", e["id"], ""))
+        elif op == "task_retried":
+            status[e["id"]] = "in_progress"
+            milestones.append((seq, "task_retried", e["id"], ""))
+        elif op == "dependency_added":
+            edges.append((e["depends_on"], e["task"]))
+    deps = {}
+    for e in events:
+        if e["op"] == "dependency_added":
+            deps.setdefault(e["task"], set()).add(e["depends_on"])
+    frontier = {}
+    peak, peak_seq, peak_ev = 0, None, ("", "")
+
+    def ready_count():
+        return sum(1 for t, s in frontier.items()
+                   if s == "pending" and all(frontier.get(d) == "done"
+                                             for d in deps.get(t, ())))
+
+    for e in events:
+        op, seq = e["op"], e["seq"]
+        if op == "task_created":
+            frontier[e["id"]] = "pending"
+        elif op == "task_started":
+            frontier[e["id"]] = "running"
+        elif op == "verification_passed":
+            frontier[e["id"]] = "done"
+        elif op == "verification_failed":
+            frontier[e["id"]] = "pending"
+        elif op == "task_reopened":
+            frontier[e["id"]] = "pending"
+        elif op == "task_retried":
+            frontier[e["id"]] = "running"
+        elif op == "task_cancelled":
+            frontier[e["id"]] = "cancelled"
+        rc = ready_count()
+        if rc > peak:
+            peak, peak_seq, peak_ev = rc, seq, (op, e.get("id", ""))
+    meta["max_ready_queue"] = peak
+    meta["max_ready_queue_at"] = {"seq": peak_seq, "event": peak_ev[0], "id": peak_ev[1]}
+    return {
+        "tasks": {tid: {"id": tid, "title": title[tid], "status": status[tid],
+                        "priority": priority[tid], "subsystem": subsystem.get(tid)}
+                  for tid in status},
+        "edges": edges, "status": status, "meta": meta,
+        "milestones": milestones,
+    }
+
+
+def derive_dir(example_dir, forge_version="unknown", snapshot=None):
+    """Derive graph.json / metrics.json / demo/_replay_facts.md into
+    example_dir from its events.log. Byte-parity with
+    tools/proof-derive.py main(). Returns a summary dict."""
+    root = Path(example_dir)
+    events = [json.loads(l) for l in
+              (root / "events.log").read_text(encoding="utf-8").splitlines() if l.strip()]
+    r = replay(events)
+    counts = r["meta"]["op_counts"]
+
+    tasks = []
+    for tid in sorted(r["tasks"], key=lambda t: min(e["seq"] for e in events
+                                                    if e["op"] == "task_created" and e["id"] == t)):
+        t = r["tasks"][tid]
+        tasks.append({"id": t["id"], "title": t["title"], "status": t["status"],
+                      "priority": t["priority"], "subsystem": t.get("subsystem")})
+
+    graph = {
+        "proof": root.name,
+        "forge_version": forge_version,
+        "derived_from": "events.log",
+        "log_tail_ts": r["meta"]["last_ts"],
+        "tasks": tasks,
+        "dependencies": [{"task": t, "depends_on": d} for d, t in r["edges"]],
+    }
+
+    t0 = datetime.fromisoformat(r["meta"]["first_ts"].replace("Z", "+00:00"))
+    t1 = datetime.fromisoformat(r["meta"]["last_ts"].replace("Z", "+00:00"))
+    minutes = round((t1 - t0).total_seconds() / 60)
+
+    passes = counts.get("verification_passed", 0)
+    failures = counts.get("verification_failed", 0)
+    metrics = {
+        "proof": root.name,
+        "status": "completed" if all(t["status"] == "done" for t in tasks) else "partial",
+        "language": _infer_language(events),
+        "tasks": len(tasks),
+        "events": len(events),
+        "verification_passes": passes,
+        "verification_failures": failures,
+        "retries": counts.get("task_retried", 0),
+        "max_ready_queue": r["meta"]["max_ready_queue"],
+        "max_ready_queue_at": r["meta"]["max_ready_queue_at"],
+        "duration_minutes": minutes,
+        "llm": "not recorded",
+        "forge_version": forge_version,
+        "conforms_to": FIELD_DEFAULTS["conforms_to"],
+        "claims": _infer_claims(events, root),
+    }
+
+    (root / "graph.json").write_text(json.dumps(graph, indent=2) + "\n", encoding="utf-8")
+    (root / "metrics.json").write_text(json.dumps(metrics, indent=2) + "\n", encoding="utf-8")
+
+    if snapshot:
+        snap_dir = root / "demo" / "snapshots"
+        snap_dir.mkdir(parents=True, exist_ok=True)
+        (snap_dir / f"{snapshot}.graph.json").write_text(
+            json.dumps(graph, indent=2) + "\n", encoding="utf-8")
+
+    by_task = {}
+    for m in r["milestones"]:
+        by_task.setdefault(m[2], []).append(m)
+    lines = ["# Replay facts (derived from events.log)\n",
+             f"- tasks: {len(tasks)} · events: {len(events)} · "
+             f"passes: {passes} · failures: {failures} · retries: {metrics['retries']} · "
+             f"duration: {minutes} min\n"]
+    for seq, op, tid, note in sorted(r["milestones"]):
+        note = f" — {note}" if note else ""
+        lines.append(f"- seq {seq}  {op:<22} {tid}{note}")
+    (root / "demo").mkdir(exist_ok=True)
+    (root / "demo" / "_replay_facts.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    print(f"derived {root.name}: {len(tasks)} tasks, {len(events)} events, "
+          f"{passes} passes, {failures} failures, {minutes} min, "
+          f"max_ready_queue={r['meta']['max_ready_queue']}")
+    print(f"  -> {root/'graph.json'}, {root/'metrics.json'}, "
+          f"{root/'demo'/'_replay_facts.md'}")
+    return {"tasks": len(tasks), "events": len(events), "passes": passes,
+            "failures": failures, "minutes": minutes, "status": metrics["status"],
+            "max_ready_queue": r["meta"]["max_ready_queue"]}

forge_proof-0.1.0a5/forge_proof/replay.py

@@ -0,0 +1,87 @@
+"""replay.md renderer for `forge proof replay`.
+
+Builds a human-readable timeline with the Proof Standard's required
+structure (Goal / Outcome / Timeline / Turning points, with `seq`
+citations) purely from machine-derived inputs: demo/_replay_facts.md and
+metrics.json. When proposal.json carries a `reason`, it becomes the Goal;
+otherwise the Goal points at the README.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+TURNING_OPS = ("verification_failed", "task_retried", "task_reopened")
+
+
+def render_replay(name: str, facts: str, metrics: dict,
+                  goal: str | None = None) -> str:
+    lines = facts.splitlines()
+    timeline = [ln for ln in lines if ln.strip().startswith("- seq ")]
+    turning = [ln for ln in timeline
+               if any(op in ln for op in TURNING_OPS)]
+    m = metrics
+    goal_txt = goal or ("(see README.md — 'What was built' and 'Why this proof exists')")
+
+    head = [
+        f"# {name} — replay",
+        "",
+        "Automatically derived from `events.log` (via `demo/_replay_facts.md` + "
+        "`metrics.json`); every milestone cites `seq` numbers for "
+        "cross-checking.",
+        "",
+        "## Goal",
+        "",
+        goal_txt,
+        "",
+        "## Outcome",
+        "",
+        f"- tasks: **{m.get('tasks', '?')}** · events: **{m.get('events', '?')}** · "
+        f"passes: **{m.get('verification_passes', '?')}** · "
+        f"failures: **{m.get('verification_failures', '?')}** · "
+        f"retries: **{m.get('retries', '?')}**",
+        f"- duration: **{m.get('duration_minutes', '?')} min** · "
+        f"status: **{m.get('status', '?')}** · "
+        f"max_ready_queue: **{m.get('max_ready_queue', '?')}** "
+        f"(peaked at seq {m.get('max_ready_queue_at', {}).get('seq', '?')})",
+        "- numbers match `metrics.json`, which is derived from `events.log` alone.",
+        "",
+        "## Timeline",
+        "",
+        *[f"{ln}" for ln in timeline],
+    ]
+    if turning:
+        head += [
+            "",
+            "## Turning points",
+            "",
+            *[f"{ln}" for ln in turning],
+        ]
+    else:
+        head += ["", "## Turning points", "", "None — no failures, retries, or reopens."]
+    head += ["", f"*rendered by forge proof replay from {len(timeline)} seq-cited milestones*"]
+    return "\n".join(head) + "\n"
+
+
+def render_dir(proof_dir) -> None:
+    """Render replay.md into proof_dir (facts + metrics must exist)."""
+    root = Path(proof_dir)
+    facts_path = root / "demo" / "_replay_facts.md"
+    if not facts_path.exists():
+        raise FileNotFoundError(
+            f"no derived facts at {facts_path} — run 'forge proof derive {root.name}' first")
+    metrics = json.loads((root / "metrics.json").read_text(encoding="utf-8"))
+    goal = None
+    prop = root / "proposal.json"
+    if prop.exists():
+        try:
+            goal = json.loads(prop.read_text(encoding="utf-8")).get("reason")
+        except json.JSONDecodeError:
+            goal = None
+    md = render_replay(root.name, facts_path.read_text(encoding="utf-8"),
+                       metrics, goal)
+    (root / "replay.md").write_text(md, encoding="utf-8")
+    print(f"wrote {root / 'replay.md'} "
+          f"({metrics.get('tasks', '?')} tasks, "
+          f"{metrics.get('events', '?')} events)")
+    return md

forge_proof-0.1.0a5/forge_proof.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: forge-proof
+Version: 0.1.0a5
+Summary: Forge reference proof tooling: forge proof check/derive/replay/bundle — a Proof-Standard evidence bundle from events.log alone. Stdlib-only core; optional matplotlib+networkx for graph.png.
+Author-email: Sanjay Davis <psanjuknl@gmail.com>
+License-Expression: MIT
+Keywords: forge,proof,evidence,sdk,autonomous-software
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# forge-proof
+
+Reference proof evidence tooling for [Forge](https://github.com/SanjayDavis/Forge):
+a stdlib-only, kernel-free CLI that turns a raw `events.log` into a complete
+[Proof Standard](https://github.com/SanjayDavis/Forge/blob/master/proofs/PROOF_SPEC.md)
+artifact bundle — no manual steps, no LLM in the loop.
+
+```
+forge proof check   <dir>   validate a bundle against the §6 checklist
+forge proof derive  <dir>   derive graph.json/metrics.json/replay facts from events.log (§5)
+forge proof replay  <dir>   render replay.md (Goal/Outcome/Timeline/Turning points)
+forge proof bundle  <dir>   emit the full bundle + validate (net-new artifacts only;
+                            curated README/replay.md/media are never clobbered,
+                            derived artifacts are verified byte-identical)
+```
+
+Installing this package registers the `forge proof` command through the
+`forge.commands` entry-point group — same mechanism as `forge plan` from
+forge-planner.
+
+Design constraints (Proof Standard §7 / repo plan):
+- **stdlib-only**: no runtime dependencies; `graph.png` rendering uses
+  matplotlib+networkx when present in the invoking python, otherwise a
+  clear hint instead of a crash.
+- **kernel-free**: never imports `forge`; the event log is read as raw
+  JSON lines, so the proof pipeline cannot disturb project state.
+- **reproducible**: derived artifacts are a pure function of `events.log`
+  — byte-identical across runs and byte-identical to the canonical
+  `tools/proof-derive.py` (pinned by tests).

forge_proof-0.1.0a5/forge_proof.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+forge_proof/__init__.py
+forge_proof/bundle.py
+forge_proof/check.py
+forge_proof/cli.py
+forge_proof/derive.py
+forge_proof/replay.py
+forge_proof.egg-info/PKG-INFO
+forge_proof.egg-info/SOURCES.txt
+forge_proof.egg-info/dependency_links.txt
+forge_proof.egg-info/entry_points.txt
+forge_proof.egg-info/top_level.txt

forge_proof-0.1.0a5/forge_proof.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forge_proof-0.1.0a5/forge_proof.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[forge.commands]
+proof = forge_proof.cli:register

forge_proof-0.1.0a5/forge_proof.egg-info/top_level.txt

@@ -0,0 +1 @@
+forge_proof

forge_proof-0.1.0a5/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forge-proof"
+version = "0.1.0a5"
+description = "Forge reference proof tooling: forge proof check/derive/replay/bundle — a Proof-Standard evidence bundle from events.log alone. Stdlib-only core; optional matplotlib+networkx for graph.png."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Sanjay Davis", email = "psanjuknl@gmail.com" }]
+keywords = ["forge", "proof", "evidence", "sdk", "autonomous-software"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+# Stdlib-only by design (Proof Standard §7: reference tooling stays
+# dependency-free). graph.png rendering needs matplotlib+networkx present
+# in the invoking python; demo.mp4 rendering shells out to the repo's
+# tools/proof-render-demo.py when a transcript exists.
+dependencies = []
+
+[project.entry-points."forge.commands"]
+proof = "forge_proof.cli:register"
+
+[tool.setuptools]
+packages = ["forge_proof"]

forge_proof-0.1.0a5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+