CLI guide

paniolo stale

Search makes a knowledge base findable; nothing keeps it true. paniolo stale is the missing half — a durable, git-native ledger that turns every commit into falsifiable allegations about the prose it may have invalidated, then lets independent agents verify and repair them under deterministic gates.

Availability

In the CLI source tree

The command family is implemented behind the stale cargo feature in release-core, but the published @paniolo/cli 0.5.63 package does not include it yet. The examples below apply when a release containing paniolo stale is available.

How it works

Detection nominates; it never proves

A diff produces a bounded, falsifiable allegation — an exact location and claim — never a verdict. Immutable evidence is sealed, an independent verifier judges it, a challenger attacks the sealed verdict, and only then does a remediator propose a minimal patch that a fourth agent independently tests. Every state change is a checked transition on revisioned records; disagreement retains the work instead of inventing resolution.

declared watch or admitted retrieval
  → allegation + immutable evidence
  → verifier verdict
  → independent verdict challenger
  → minimal remediation patch
  → independent patch challenger
  → repository gates / merge gate
  → automatic merge or durable insufficient-evidence

Nothing a model says can mint truth — no retrieval score, agent agreement, or validator result sets a disposition. Open work lives in the repository beside the prose it covers, in a JSON ledger of content-addressed records under .paniolo/staleness/.

What it watches

Three surfaces, declared watches

The engine measures three content surfaces independently: registered wiki pages, ordinary Markdown docs carrying a staleness: frontmatter block, and parser-owned code comments associated with symbols. A page declares what it depends on:

staleness:
  mode: flag
  watches:
    - repo: ranch-hand
      paths: ["crates/auth-api/src/routes.rs"]
      symbols: ["unread_count"]
      section: "setup/windows"

When a watched path or symbol changes, the dependent section becomes a candidate allegation. Fuzzy retrieval lanes can nominate too, but they stay in shadow until a measured replay against frozen gates admits them.

Command reference

Scan, adjudicate, propose, repeat

Action	Command	Result
Scan a range	`stale scan --code KEY:PATH --base SHA --head SHA --dry-run`	Detects allegations over the range; `--dry-run` writes nothing.
Inspect queue	`stale list --actionable` · `stale next` · `stale show ID`	Reads the ledger; `show` prints the allegation and sealed observations.
Adjudicate	`stale run --repo KEY:PATH`	Runs verifier and challenger on pending work, then remediator and patch challenger on confirmed-stale work.
Publish fixes	`stale propose --repo KEY:PATH`	Pushes remediation PRs on `staleness/rem-*` branches and records pending proposals.
Reconcile merges	`stale merge-sync --repo KEY:PATH`	Merged heads run the merge gate and resolve; closed PRs clear the proposal for re-queue.
Run continuously	`stale worker --ledger-repo KEY:PATH --repo KEY:PATH`	Merge-sync → cursor-gated scan → adjudicate → propose → publish the ledger as a PR.
Triage	`stale retry ID` · `stale resolve ID --note NOTE` · `stale prune` · `stale rebase`	Queue bookkeeping; `prune` and `rebase` print a plan without `--apply`.
Measure	`stale report` · `stale seed TARGET CLAIM` · `stale replay`	Dogfood report, known-answer canaries, and live replay through real adapters.

Every subcommand prints JSON to stdout. A held worker lock is not an error — a second worker reports {"stopped": "run lock held"} and exits zero.

Configuration

Deployment policy, not semantics

The staleness section of paniolo.config.json owns the fleet: named agent profiles, role assignments, per-phase limits, retrieval bounds, and content scopes. Safety invariants — the merge gate, evidence sealing, the state machine — stay in code and cannot be configured away.

"staleness": {
  "ledgerPath": ".paniolo/staleness",
  "agentProfiles": {
    "codex-gpt-5-5": { "adapter": "codex", "model": "gpt-5.5" }
  },
  "roles": {
    "verifier": "codex-gpt-5-5",
    "verdictChallenger": "codex-gpt-5-5",
    "remediator": "cursor-swe-2-high",
    "patchChallenger": "codex-gpt-5-5"
  }
}

Roles take adapter-and-model profiles so a verifier family can be paired with a different remediator family — the challengers audit across vendors rather than agreeing with themselves.

For coding agents

Give your agent the stale skills

Two skills ship in the catalog. The paniolo-stale skill covers the read-mostly surface — scanning a range, inspecting and triaging allegations, reading the dogfood report. The paniolo-stale-remediate skill drives the mutating pipeline — adjudication runs, remediation PRs, merge-sync, the durable worker, and calibration with replay and canaries:

npx skills add paniolo-ai/skills --skill paniolo-stale

npx skills add paniolo-ai/skills --skill paniolo-stale-remediate

Both bundle the full staleness reference set — the loop, the command surface, the config schema, the ledger contract, adjudication, and calibration — so the agent carries the model, not just the flags. For the rest of the catalog, see Paniolo skills; for the wiki these allegations protect, see LLM Wiki.