ponens

Tutorials · Lesson 7 of 7

7 · Review and sign off

You'll switch to the reviewer's seat — verify the consequential claims, certify the goal, and cryptographically sign the result. You need: a finished trace.json (ideally someone else's).

Review by reading the trace, not just the diff

The trace tells you where to look and what was claimed; your job is to establish what's true. The reviewing protocol ships inside the CLI:

ponens agent --review                     # the full reviewing-agent protocol

The core moves:

  • Orient — ponens trace status and enrich: intent, outcome, the three axes, uncovered clauses.
  • Verify the positive space — re-run the consequential proofs and tests; a "verified" claim with no backing artifact is really unverified. Treat any stale/detached result as not current.
  • Work the residual surface — highest severity first; run each suggested_check.
  • Hunt the undeclared gaps — anything the change touches that is neither verified nor declared is a gap you raise (a defeater if it's counter-evidence).
ponens trace reproduce trace.json --run   # re-run recorded commands; report divergence
ponens trace check     trace.json         # re-run the attached policies

Certify — the third axis

If the work re-derives and the definition of done was the right one, certify it. Because CERTIFIED means "a non-doer confirmed the criteria," you may only certify a trace you did not produce:

ponens trace goal certify --by reviewer

Sign it — non-repudiable, tamper-evident

Record your disposition cryptographically. The signature is over the trace's content_hash, so any later edit breaks it (tampered). Pick a backend:

ponens trace sign trace.json --role auditor --disposition approved         # ssh (default)
ponens trace sign trace.json --backend gpg --signer you@org.com --disposition approved
ponens trace sign trace.json --backend sigstore --signer you@org.com --oidc-issuer <url>
ponens trace sign trace.json --role auditor --disposition approved --tsa https://freetsa.org/tsr

Add --tsa for an RFC-3161 trusted timestamp — a TSA-attested "existed by <time>". Anyone re-checks, establishing trust per backend:

ponens trace verify trace.json --allowed-signers roster        # ssh
ponens trace verify trace.json --gpg-roster fingerprints       # gpg
ponens trace verify trace.json --identity you@org.com --oidc-issuer <url>   # sigstore

Share it

ponens bind && ponens push                # bind 1:1 to the commit, publish for review
ponens trace export trace.json --to prov  # or export to W3C PROV-JSON for other tools

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

You've done the whole loop

Capture → curate → declare → goal & axes → govern → keep-honest → review & sign. That's the full ponens methodology on a real change: a curated, governed, reviewed, and signed reasoning record anyone can re-check. From here, the task guides go deeper on individual jobs, and the spec is the reference.

What you learned

  • Review is targeted verification, not trust — re-check the consequential claims.
  • Certify is a non-doer's act — never self-certify.
  • Sign over content_hash (ssh / gpg / sigstore, + trusted timestamp) makes approval non-repudiable and tamper-evident.