Quickstart

Quickstart

This page gives the shortest safe paths to useful output.

Path A: Check Agent Output

Use this when you have an answer or report from an AI agent and want a compact, machine-readable check.

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

Read these fields first:

• accepted: the report envelope passed finite checks.
• workflow_usable: the output can be used for routing or review.
• settled: all scoped obligations are discharged.
• unresolved_obligations: checks that still need work.
• residual_summary: unresolved work grouped by kind.
• next_safe_actions: suggested checks or inspections, not permission to execute.

Path B: Ask For A Phase Plan

Use this when the next question is "what should be checked or repaired next?"

pic phase plan --compact --text "Candidate packet: route evidence and preserve residuals." --profile development
pic agent accelerate --compact --text "Candidate packet: route evidence and preserve residuals." --profile development

The planner ranks gaps, bottlenecks, residuals, and safe next inspections. It does not execute commands.

Path C: Run The Packaged Demo

Use this when you want to confirm that the pip package works without a source checkout.

pic demo installed-smoke --profile development
pic demo bootstrap --output-dir pic-demo
pic runtime step --state pic-demo/runtime_state.json --input pic-demo/runtime_step_input.json --profile development

Path D: Run Phase Ecology Lab

Use this when you want to inspect a small window of reports and see packet flow, graph structure, closure candidates, execution-available paths, and certificate candidates.

pic phase lab init --output-dir pic-demo/phase-lab
pic phase lab ingest --store pic-demo/phase-lab --report pic-demo/phase_lab_runtime_report.json
pic phase lab observe --store pic-demo/phase-lab --window latest
pic phase lab graph --store pic-demo/phase-lab
pic phase lab closure --store pic-demo/phase-lab
pic phase lab executable-paths --store pic-demo/phase-lab
pic phase lab certify --store pic-demo/phase-lab --threshold pic-demo/phase_lab_threshold.json

Path E: Emit CCR Tasks And Residuals

Use this when PIC should hand candidate work to Collective Capability Runtime, or another scheduler, as data.

pic phase plan --compact --emit ccr-tasks --output tasks.jsonl
pic phase gap --compact --emit ccr-residuals --output residuals.jsonl

Read these fields first in each JSONL record:

• schema_version: ccr.task.v0.1 or ccr.residual.v0.1.
• candidate_only_until_checked: the downstream runtime must still verify it.
• constraints.allowed_commands: empty for PIC-emitted tasks.
• residual_policy: instructions for preserving unresolved work.
• pic_interop: provenance and recommended PIC command hints.

The output is a handoff record, not a tool execution request.

Path F: Check A TRC Operation Candidate

Use this when a trace should be normalized and checked before any provider or real-world handoff is considered. The example input path below is available in a source checkout.

pic trc trace-normalize --input examples/asi_proxy_benchmark_bundle/trc_agent_trace.json --output trace_nf.json
pic trc trace-check --trace trace_nf.json --output trace_check.json
pic trc trace-to-packet --trace trace_nf.json --output trace_packet.json

real_world_operation_gate.operation_ready=true means the trace has explicit authority, resources, rollback or escrow data, witnesses, schedule, and tolerance fields for the scoped candidate. It still does not mean the action was executed or that the physical result is true.

Path G: Source Checkout

Use this when you want full examples and development checks.

git clone https://github.com/kadubon/percolation-inversion-compiler.git
cd percolation-inversion-compiler
uv sync --all-extras --dev
uv run pic agent check --compact --text "Candidate packet: preserve residuals." --profile development
uv run pytest

Important Rule

Raw packet volume is not progress. A report with many candidates is not better unless the evidence, verifier routes, residuals, and safety boundary are clear.

settled=false is often the correct result. It means the remaining obligations were not hidden.