Getting started

ponens turns an AI coding agent's session into a higher-level reasoning record — a curated, verifiable account of what it built and why — then makes the reasoning rigorous and governs it with Computable Governance (machine-checkable best-practice policies). The CLI is terminal-first; the browser is the escalation.

Install

# from this repo
pip install "ponens @ git+https://github.com/imandra-ai/ponens.git#subdirectory=cli"

# or for local development
pip install -e ./cli

The flow: emit a draft from the session, curate the narrative, enrich it with what only the agent can declare, grade and govern it, then view and share. Every command is plain text — greppable, pipeable, --json where you script it. This is the agent / CI surface too.

1 · Emit — capture the session

An agent emits the trace from its own session transcript; you write nothing. Emission captures the actions, file lineage, decisions, and reasoning as ground truth.

ponens emit -o trace.json                            # newest session for this project
ponens emit transcript.jsonl -o trace.json --from claude-code

2 · Curate the narrative

Emission seeds each step's title from the raw directives ("yes", "ok now fix it"). Those are drafts — rewrite them into a clean account of what was built and why. The atomic actions underneath stay untouched and honest.

ponens trace meta ls trace.json                      # the steps, and how curated each is
ponens trace meta set trace.json m3 --title "Add idempotency to capture" --status completed
ponens trace meta merge trace.json m7 m8             # fold dead-ends into one step
ponens trace retitle trace.json --title "…" --outcome "…"

3 · Enrich — declare what emission can't derive

The produced artifacts (so the lineage DAG is real) and the negative space — the gaps only the agent can declare.

ponens trace artifact trace.json --type VerificationResult --name "no double-charge" --producer-action-id 12
ponens trace residual add trace.json --kind assumption --severity high \
    --statement "Assumes the gateway sends a stable idempotency key" \
    --suggested-check "confirm the retry contract"

4 · Grade it

A quality rubric — structure, rationale coverage, negative space, reproducibility, verification evidence, and lineage — plus a separate policy-compliance line. Treat the grade as a hygiene floor to clear, not a number to game.

ponens trace grade trace.json

5 · Govern — Computable Governance

Check the trace against best-practice policies — conformance checks evaluated over the record. A real, automatic gate (exit code), fully offline.

ponens registry update
ponens policies search testing
ponens policies add tests_before_commit --into trace.json
ponens trace check trace.json                        # → PASS / FAIL

6 · View it

Read the reasoning behind the commit — zoom from intent-named steps down to atomic actions, with the lineage DAG, decisions, and the residual surface.

ponens trace view trace.json                         # self-contained page; opens in a browser
ponens trace view trace.json --out trace.html        # write the HTML (e.g. a CI artifact)

Headless (SSH/CI)? It prints the file path instead. See it live in the Viewer.

ponens bind && ponens push                           # bind 1:1 to the commit, publish for review

Or post it on the pull request — the grade, the declared gaps, and a one-click interactive viewer — with the pr-trace GitHub Action.

Concepts

Trace — the curated, verifiable record of an agent's work session, in two layers: faithful atomic actions (ground truth) and a curated meta-action narrative (spec).
Residual surface — what the trace did not establish: assumptions, unverified claims, out-of-scope items, limitations, open questions. It tells a reviewer where to look.
Computable Governance — best-practice policies as machine-checkable rules over the trace. Browse the gallery, or write your own.
Review handoff — how a reviewing agent consumes a trace: verify the consequential claims, triage the declared gaps, hunt the undeclared ones.