ponens 1.0.0__tar.gz

ponens-1.0.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: ponens
+Version: 1.0.0
+Summary: Author, govern, and validate reasoning traces — the open CLI for the reasoning-policies ecosystem
+Author-email: Denis Ignatovich <denis@aestheticintegration.com>
+License: MIT
+Requires-Python: >=3.11
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == "yaml"

ponens-1.0.0/ponens/adapters/__init__.py

@@ -0,0 +1,26 @@
+"""Session-transcript adapters.
+
+Each adapter maps one agent's native transcript format to the normalized event stream
+that `emit.build_trace` consumes — so the trace-building core stays agent-agnostic and a
+new agent is just a new module here. An adapter module exposes:
+
+    NAME : str
+    IMPLEMENTED : bool
+    default_transcript() -> str | None
+    read_entries(path) -> list
+    parse(entries) -> {"events", "model", "assistant", "last_reasoning"}
+"""
+from . import claude_code, codex, gemini
+
+ADAPTERS = {a.NAME: a for a in (claude_code, gemini, codex)}
+
+
+def get_adapter(name):
+    try:
+        return ADAPTERS[name]
+    except KeyError:
+        raise KeyError(name)
+
+
+def adapter_names():
+    return list(ADAPTERS)

ponens-1.0.0/ponens/adapters/claude_code.py

@@ -0,0 +1,176 @@
+"""Claude Code transcript adapter.
+
+Maps a Claude Code session transcript (a JSONL of messages, each with content blocks
+— text / thinking / tool_use / tool_result) into the **normalized event stream** that
+`emit.build_trace` consumes. Everything Claude-specific lives here: the tool-name
+vocabulary, the message/content-block shape, and the todo (TaskCreate/TaskUpdate) signal.
+
+To support another agent, add a sibling module exposing the same surface:
+    NAME, IMPLEMENTED, default_transcript(), read_entries(path), parse(entries)
+`parse` returns {"events": [...], "model": str, "assistant": str, "last_reasoning": str|None},
+where each event is one of:
+    {"t": "directive", "text": str}                         # a user instruction
+    {"t": "todo_create", "subject": str|None}               # the agent's plan
+    {"t": "todo_update", "task_id": str, "status": str}
+    {"t": "action", "type": ..., "category": ..., "rationale": ..., "file": ...,
+     "is_edit": bool, "command": ..., "query": ..., "description": ..., "result": ...,
+     "error": bool, "decision": {...}|None, "fallback_label": ...}
+"""
+import glob
+import json
+import os
+
+NAME = "claude-code"
+IMPLEMENTED = True
+
+# Claude Code tool name -> canonical trace action type
+TOOL_MAP = {
+    "Read": "ReadFile",
+    "Edit": "EditFile",
+    "MultiEdit": "EditFile",
+    "Write": "CreateFile",
+    "NotebookEdit": "EditFile",
+    "Grep": "SearchCode",
+    "Glob": "ExploreDirectory",
+    "WebSearch": "SearchWeb",
+    "WebFetch": "ReadDocumentation",
+    "AskUserQuestion": "AskUser",
+}
+# Meta/bookkeeping tools that aren't part of the engineering record.
+# (TaskCreate/TaskUpdate are NOT skipped — they're the agent's plan, surfaced as todo
+#  events so the core can derive PlanDeclared meta-actions; never emitted as actions.)
+SKIP_TOOLS = {"TaskList", "TaskGet", "TaskOutput", "TaskStop",
+              "ToolSearch", "ExitPlanMode", "EnterPlanMode", "Skill"}
+FILE_TOOLS = {"Read", "Edit", "MultiEdit", "Write", "NotebookEdit"}
+EDIT_TOOLS = {"Edit", "MultiEdit", "Write", "NotebookEdit"}
+
+
+def _bash_action(cmd):
+    c = (cmd or "").lower()
+    if "git commit" in c:
+        return "GitCommit"
+    if "git diff" in c:
+        return "GitDiff"
+    if "git status" in c:
+        return "GitStatus"
+    if any(t in c for t in ("pytest", "npm test", "go test", "cargo test", "unittest")):
+        return "RunTests"
+    return "RunCommand"
+
+
+def _action_type(tool, inp):
+    if tool == "Bash":
+        return _bash_action(inp.get("command", ""))
+    return TOOL_MAP.get(tool, "RunCommand")
+
+
+def _reasoning(content):
+    """The agent's reasoning before its tool calls — the motivation. Prefers the
+    human-facing text; falls back to the model's thinking blocks."""
+    texts, thinks = [], []
+    for b in content:
+        if not isinstance(b, dict):
+            continue
+        if b.get("type") == "tool_use":
+            break
+        if b.get("type") == "text" and b.get("text"):
+            texts.append(b["text"].strip())
+        elif b.get("type") == "thinking" and (b.get("thinking") or b.get("text")):
+            thinks.append((b.get("thinking") or b.get("text")).strip())
+    return " ".join(texts).strip() or " ".join(thinks).strip()
+
+
+def default_transcript():
+    """The newest Claude Code session transcript for the current project, if any."""
+    proj = "-" + os.path.abspath(os.getcwd()).strip("/").replace("/", "-")
+    d = os.path.join(os.path.expanduser("~"), ".claude", "projects", proj)
+    js = sorted(glob.glob(os.path.join(d, "*.jsonl")), key=os.path.getmtime)
+    return js[-1] if js else None
+
+
+def read_entries(path):
+    entries = []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def parse(entries):
+    # 1. collect tool results by tool_use_id
+    results = {}
+    for e in entries:
+        if e.get("type") != "user":
+            continue
+        content = (e.get("message") or {}).get("content")
+        if isinstance(content, list):
+            for b in content:
+                if isinstance(b, dict) and b.get("type") == "tool_result":
+                    body = b.get("content")
+                    if isinstance(body, list):
+                        body = " ".join(x.get("text", "") for x in body if isinstance(x, dict))
+                    results[b.get("tool_use_id")] = {"text": body or "", "error": bool(b.get("is_error"))}
+
+    # 2. walk in order -> normalized events
+    events, model, last_reasoning = [], "unknown", None
+    for e in entries:
+        et = e.get("type")
+        if et == "user":
+            c = (e.get("message") or {}).get("content")
+            if isinstance(c, str) and c.strip():
+                events.append({"t": "directive", "text": c.strip()})
+            continue
+        if et != "assistant":
+            continue
+        msg = e.get("message") or {}
+        if model == "unknown":
+            model = msg.get("model", "unknown")
+        content = msg.get("content") or []
+        reasoning = _reasoning(content)
+        if reasoning:
+            last_reasoning = reasoning
+        for b in content:
+            if not isinstance(b, dict) or b.get("type") != "tool_use":
+                continue
+            tool, inp = b.get("name"), (b.get("input") or {})
+            if tool == "TaskCreate":
+                events.append({"t": "todo_create", "subject": inp.get("subject") or inp.get("description")})
+                continue
+            if tool == "TaskUpdate":
+                events.append({"t": "todo_update", "task_id": str(inp.get("taskId") or ""),
+                               "status": inp.get("status")})
+                continue
+            if tool in SKIP_TOOLS:
+                continue
+            res = results.get(b.get("id"))
+            rationale = reasoning or last_reasoning      # carryover; the core truncates
+            if tool == "AskUserQuestion":
+                q = (inp.get("questions") or [{}])[0]
+                events.append({
+                    "t": "action", "type": "ExclusiveDecision", "category": "gateway",
+                    "rationale": rationale,
+                    "decision": {"question": q.get("question") or q.get("header") or "decision"},
+                    "result": res["text"] if res else None, "error": bool(res and res["error"])})
+                continue
+            events.append({
+                "t": "action",
+                "type": _action_type(tool, inp),
+                "category": "reasoning" if tool in ("Grep", "Glob") else "activity",
+                "rationale": rationale,
+                "description": inp.get("description"),
+                "file": inp.get("file_path") if tool in FILE_TOOLS else None,
+                "is_edit": tool in EDIT_TOOLS,
+                "command": inp.get("command") if tool == "Bash" else None,
+                "query": inp.get("pattern") or inp.get("query"),
+                "result": res["text"] if res else None,
+                "error": bool(res and res["error"]),
+                "fallback_label": tool,
+            })
+
+    return {"events": events, "model": model, "assistant": "ponens",
+            "last_reasoning": last_reasoning}

ponens-1.0.0/ponens/adapters/codex.py

@@ -0,0 +1,22 @@
+"""Codex CLI transcript adapter — stub.
+
+Not yet implemented. To add support, mirror `claude_code.py`: read Codex's session
+transcript and emit the normalized event stream (directives, todos, and `action` events
+with canonical types). Set IMPLEMENTED = True when `parse` is real.
+"""
+NAME = "codex"
+IMPLEMENTED = False
+
+_MSG = "the Codex adapter is not implemented yet — only 'claude-code' is supported today"
+
+
+def default_transcript():
+    return None
+
+
+def read_entries(path):
+    raise NotImplementedError(_MSG)
+
+
+def parse(entries):
+    raise NotImplementedError(_MSG)

ponens-1.0.0/ponens/adapters/gemini.py

@@ -0,0 +1,22 @@
+"""Gemini CLI transcript adapter — stub.
+
+Not yet implemented. To add support, mirror `claude_code.py`: read Gemini's session
+transcript and emit the normalized event stream (directives, todos, and `action` events
+with canonical types). Set IMPLEMENTED = True when `parse` is real.
+"""
+NAME = "gemini"
+IMPLEMENTED = False
+
+_MSG = "the Gemini adapter is not implemented yet — only 'claude-code' is supported today"
+
+
+def default_transcript():
+    return None
+
+
+def read_entries(path):
+    raise NotImplementedError(_MSG)
+
+
+def parse(entries):
+    raise NotImplementedError(_MSG)

ponens-1.0.0/ponens/agent.py

@@ -0,0 +1,84 @@
+"""`ponens agent` — print the agent workflow guide.
+
+The guide is embedded here (not a repo file) so an agent with only the CLI installed can
+self-onboard: `ponens agent` prints how to produce a good trace, `ponens agent --review`
+prints the reviewing-agent protocol. The fuller canonical versions live in AGENT_PROMPT.md
+and REVIEW_AGENT_PROMPT.md at the repo root.
+"""
+
+GUIDE = """\
+ponens — agent guide
+
+You produce a reasoning trace: a curated, verifiable record of WHAT you built and WHY —
+not a transcript replay. It has two layers, treated differently:
+  - Atomic actions          ground-truth evidence (files, commands, results). NEVER rewrite them.
+  - Meta-action narrative   the curated story. Seeded from raw directives ("yes", "ok fix it") —
+                            YOU rewrite it into clean intent.
+
+Make the reasoning RIGOROUS: separate what you ESTABLISHED (proved / tested / verified, backed by
+an artifact) from what you merely ASSERTED (prose). Declare what you did not check, and flag where
+formal methods or other verification belong — an unverified, load-bearing claim on a high-stakes
+path is exactly such a place.
+
+Workflow — after you finish the work:
+
+  1. EMIT     ponens emit -o trace.json
+  2. CURATE   ponens trace meta ls trace.json
+              ponens trace meta set trace.json <id> --title "<clean intent>" [--status completed]
+              ponens trace meta merge trace.json <into> <id...>     # fold dead-ends / false starts
+              ponens trace retitle trace.json --title "..." --outcome "..."
+  3. ENRICH   ponens trace artifact trace.json --type <SourceCode|VerificationResult|...> \\
+                --name "..." --producer-action-id <n>               # declare artifacts -> lineage
+              ponens trace residual add trace.json \\
+                --kind <assumption|unverified|out_of_scope|limitation|open_question> \\
+                --severity <info|low|medium|high|critical> --statement "..." \\
+                [--suggested-check "how a reviewer could close it"]  # declare your gaps
+  4. GRADE    ponens trace grade trace.json        # a hygiene floor to CLEAR, not a score to game
+  5. GOVERN   ponens registry update
+              ponens policies add tests_before_commit --into trace.json   # best-practice policies
+              ponens trace check trace.json        # a real gate (exit code)
+  6. SHARE    ponens trace view trace.json         # read the reasoning (zoomable)
+              ponens bind && ponens push           # bind 1:1 to the commit, publish for review
+
+A trace with NO declared residuals is suspicious, not clean. The value to a reviewer is that you
+disclosed what you did NOT establish.
+
+Reviewing a trace instead of producing one?   ponens agent --review
+"""
+
+REVIEW_GUIDE = """\
+ponens — reviewing-agent guide
+
+Review a change by reading its reasoning TRACE, not just its diff. Targeted verification, not trust.
+
+  ponens trace status    <file>          # orient: intent, outcome, grade
+  ponens trace grade     <file>          # where the trace is thin (incl. lineage)
+  ponens trace residuals <file>          # the declared gaps, by severity — your work-list
+  ponens trace reproduce <file> --run    # re-run the recorded commands; report divergence
+  ponens trace check     <file>          # run the attached policies
+
+Procedure:
+  1. Orient — intent, outcome, changed files, lineage. No artifacts/lineage is itself a
+     reviewability gap.
+  2. Verify the positive space proportionally — re-check the consequential proofs/tests; downgrade
+     any unbacked "verified" claim to an undeclared `unverified` residual.
+  3. Work the residual surface, highest severity first — run each suggested_check if cheap.
+  4. Hunt the UNDECLARED gaps — anything the change touches that is neither verified nor declared.
+  5. Verdict — approve only if no open blocking residual remains and every consequential claim was
+     re-verified; else request-changes (list the residual_ids to close) or escalate-to-human.
+
+Never treat prose as evidence. Never auto-resolve an open_question. Traces are immutable — gaps
+close in a SUCCESSOR trace, not by editing this one.
+"""
+
+
+def cmd_agent(args):
+    print(REVIEW_GUIDE if getattr(args, "review", False) else GUIDE)
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser("agent",
+                              help="Print the agent workflow guide (how to produce or review a trace)")
+    p.add_argument("--review", action="store_true", help="Print the reviewing-agent guide instead")
+    p.set_defaults(func=cmd_agent)