Home

Percolation Inversion Compiler Wiki

Percolation Inversion Compiler, or PIC, is an AI agent output checker, workflow verification toolkit, and residual-ledger runtime.

In plain terms, PIC helps an agent or engineer turn a piece of text, a repository signal, a message, a feed item, or a proposed capability into a structured report:

• what is being claimed;
• what evidence is attached;
• what is still missing;
• what can be safely reused;
• what should be routed to a verifier;
• what must remain as residual work.

PIC is useful when agent output should be checked before it is reused, routed, promoted, merged, sent to another agent, or treated as completed work.

Fastest Start

Use the compact checker first. It gives a short JSON report that humans, CI jobs, and agents can read without understanding the full theory vocabulary.

python -m pip install percolation-inversion-compiler
pic agent check --compact --text "Candidate packet: route evidence and preserve residuals." --profile development
pic agent runbook --profile development

Use workflow_usable for practical routing. Use settled only for scoped finite settlement. A useful first report often has workflow_usable=true and settled=false.

Why Agent Output Is Treated As Candidate Work

An AI agent can write a confident answer before the supporting evidence has been checked. It can also mix correct details with missing context, stale facts, unsafe next steps, or claims that belong to an external domain.

PIC treats agent output as candidate work so the system can ask simple operational questions before reuse:

• What is the claim?
• What evidence supports it?
• What evidence is missing?
• Which verifier route should check it?
• What residual work must stay visible?
• Is the result safe to route, or should it remain diagnostic?

This does not make the agent slower for its own sake. It prevents unverified text from being silently promoted into reusable work.

One Sentence Description

PIC is a workflow verification and AI agent output checking toolkit for preserving evidence, proof obligations, residual ledgers, verifier routes, and safe reuse decisions.

What PIC Is

PIC is a local-first finite checking system. It emits deterministic JSON reports, residual ledgers, proof obligations, salience queues, packet-promotion decisions, identity checks, and collective-phase certificates.

The shortest mental model is:

candidate output
-> structured packet
-> evidence and obligation checks
-> residual ledger
-> next safe routing decision

PIC does not prove that an AI system is generally intelligent. It does not prove real-world truth. It does not execute unsafe actions. It makes incomplete work visible instead of hiding it.

First Pages To Read

• Getting Started: pip install, source checkout, CLI, and Python SDK.
• Quickstart: shortest command path after setup.
• Use Cases: common uses such as LLM output checking, GitHub Actions, OpenClaw, and agent messages.
• Live Intake and Agent Messages: bounded web/feed intake and local agent-to-agent message relay.
• Core Concepts: candidate, evidence, proof obligation, residual ledger, verifier route, and reusable abstraction capital.
• Concepts in Plain Language: common terms without heavy theory.
• Agent Guide: how an AI agent should read PIC output.
• What PIC Does Not Do: limits and non-claims.
• Safety and Limits: what PIC does not authorize or prove.
• Theory Map: how ECPT, BIT, TRC, SQOT, and ALT fit together.
• CLI Recipes: practical command patterns.
• Glossary: short definitions.

Common Use Cases

• Check AI-generated text before reusing it.
• Verify AI agent workflows before treating candidate work as completed work.
• Run a read-only GitHub Actions checker that uploads residual-preserving JSON.
• Use the separate OpenClaw / ClawHub skill as a pre-action checklist for external-effect actions.
• Check agent-to-agent messages before using them as packet candidates.
• Run local agent-message inbox relay checks with deterministic JSON output.
• Preserve unresolved evidence and proof obligations.
• Route missing work to a verifier.
• Keep repository, message, feed, or web intake as candidate packets.
• Separate declared metadata from checked evidence.
• Build residual-preserving reports for CI or agent loops.
• Check signed agent populations and Sybil-resistance ledgers.
• Decide whether an abstraction can become reusable capital.

Search Terms

AI agent output checker, workflow verification, LLM output validation, agent output audit, AI workflow checker, evidence routing, verifier routing, residual ledger, unresolved work ledger, safe reuse checks, packet promotion, local agent inbox, agent-to-agent messages, bounded web intake, live feed intake, schema contract, portability conformance, salience queue, finite task scheduler, abstraction liquidity, reusable work item, agent identity checks, Sybil resistance, PIC, ECPT, BIT, TRC, SQOT, ALT, pic agent check --compact, pic agent runbook.

What To Trust

Trust the structured report more than the agent text that produced it.

Read these fields first:

• accepted: the finite envelope was accepted by the checker.
• workflow_usable: the compact agent workflow can guide next safe actions.
• operationally_usable: the deeper runtime result can be used for routing under the selected profile.
• settled: all scoped finite obligations are discharged. This is often false.
• missing_obligations: work that remains unresolved.
• residual_ledger: debt or limits that must not be erased.
• agent_tasks: recommended next finite tasks.
• route_execution_requests: verifier route requests, not permission to execute arbitrary commands.

settled=false is not a command failure. It means the remaining obligations are explicit.

Main Repository

• Repository: https://github.com/kadubon/percolation-inversion-compiler
• README: https://github.com/kadubon/percolation-inversion-compiler#readme
• Agent guide: https://github.com/kadubon/percolation-inversion-compiler/blob/main/docs/for-agents.md
• CLI reference: https://github.com/kadubon/percolation-inversion-compiler/blob/main/docs/cli-reference.md
• Safety boundary: https://github.com/kadubon/percolation-inversion-compiler/blob/main/docs/11-safety-boundary.md