ponens

Agent-first by design

ponens is built for the agent to drive. A coding agent produces its own reasoning trace as part of finishing the work — emitting it from the session, curating the narrative, declaring its gaps, and clearing the governance gate. You don't hand-write traces; the agent does.

Self-onboarding — one command

The whole workflow ships inside the CLI. An agent with only pip install ponens can learn it with no repo access:

ponens agent            # how to produce a trace
ponens agent --review   # how to review one

It prints the two-layer model (faithful atomic actions + a curated narrative), the rigor principle (separate what was established from what was merely asserted, and flag where formal methods belong), and the exact commands for each step.

Wire it into your agent

Drop the guide into your agent's instructions so it runs the workflow every time:

# add it to your project's agent memory
ponens agent >> AGENTS.md        # or CLAUDE.md, a system prompt, etc.

After the agent finishes a task, it runs the pipeline itself — no human in the capture loop.

The workflow

  1. Emit — derive a faithful draft from the session.
  2. Curate — rewrite the raw directives into a clean narrative.
  3. Enrich — declare produced artifacts (lineage) and the gaps (residuals).
  4. Grade — clear the quality floor.
  5. Govern — check against best-practice policies.
  6. Share — view it, bind it to the commit, post it on the PR.

Full commands in the docs.

Agent-to-agent review

A reviewing agent reads the trace, not just the diff — verifying the consequential claims, triaging the declared gaps, and hunting the undeclared ones. The protocol is one command away (ponens agent --review), and because a trace declares its own negative space, the reviewer knows where to look instead of re-deriving the change.

In CI / on the pull request

The pr-trace GitHub Action posts the grade, the declared gaps, and a one-click interactive viewer on the pull request — where reviewers (human or agent) already are.

Machine-friendly

Every command is plain text — greppable, pipeable, with --json where you script it. Clear exit codes make ponens trace check a real gate in any pipeline.