paniolo stale Guide Research
Documentation that keeps up with code

paniolo stale

Your search can find the perfect page and still give you the wrong answer. paniolo stale finds documentation and code comments that a code change may have made wrong, verifies each possible problem with independent agents, and prepares a narrowly scoped repair.

Why you should care

Wrong documentation is worse than missing documentation

Code changes constantly. Explanations of that code — wiki pages, setup guides, runbooks, and comments — often do not. When prose no longer describes the current code, it is stale. Stale prose looks trustworthy, so people and coding agents confidently act on it.

That creates a quiet form of technical debt. A renamed setting breaks a setup guide. A changed API leaves an example subtly wrong. A code comment promises behavior the function no longer has. Search makes these errors easier to find; it does not make them true.

paniolo stale closes that gap. It turns a code change into a reviewable claim about specific prose, collects evidence, asks independent agents to test the claim, and keeps a permanent record of what happened. You get continuous maintenance without asking a human to review every commit or trusting one model to grade its own work.

The idea in plain language

A to-do list with evidence, not a list of model guesses

A ledger is a durable, ordered record of work and outcomes. The live ledger is the checkout's owner workspace.sqlite, outside the Git tree. A worker can publish a snapshot of that database on a staleness/ledger branch, so findings and repairs are still reviewed like any other repository change.

Each ledger item is an allegation: a precise, testable claim that a code change may have invalidated a particular passage. “The Windows setup section may still name the old command” is an allegation. “The docs are probably bad” is not precise enough.

code changes → nominate an exact passage and claim → collect immutable evidence → verify the claim → challenge the verdict → propose the smallest safe repair → challenge the repair → pass repository checks and the merge gate → merge, dismiss, or retain the unresolved work

Evidence is the exact code, prose, commit, and excerpt used to judge an allegation. Immutable means it cannot be edited after it is recorded. A verdict says whether the allegation is supported. A disposition is the resulting ledger outcome, such as confirmed, dismissed, or unresolved.

The central rule is simple: detection nominates; it never proves truth. A search score, a model response, or agreement between agents can route work, but none can silently declare documentation correct or merge a patch.

Quick start

Inspect first; automate later

Use @paniolo/cli 0.5.80 or later for the released commands in this guide, including stale flag. The source tree can run ahead of the published CLI between releases; check paniolo stale --help for what your installed version actually carries. Version 0.5.68 admits Devin as an agent adapter and includes the replay-tested Cursor auto plus Devin swe-2-high pairing. Version 0.5.65 first added parser-backed code-comment support for C#, PowerShell, shell, and Python in addition to Rust, TypeScript/TSX, and JavaScript/JSX. A CLI, or command-line interface, is a program you run from a terminal. Start with a dry run: a preview that computes results without writing to the ledger or calling agents.

npx @paniolo/cli stale scan --code my-app:. --base HEAD~1 --head HEAD --dry-run

my-app:. is a key:path address: my-app is the repository's stable name and . is its checkout path. HEAD means the current Git commit; HEAD~1 means its parent.

If the report looks useful, remove --dry-run to store findings. Inspection commands do not call agents:

npx @paniolo/cli stale list --actionable npx @paniolo/cli stale next npx @paniolo/cli stale show S-<id>

Actionable means the item still needs verification or a repair. Every command writes machine-readable JSON — JavaScript Object Notation — to standard output, which makes the result suitable for scripts and continuous integration.

What it protects

Wiki pages, ordinary docs, and code comments

A surface is one category of content that stale measures. Each surface has its own detector, scope, and metrics.

SurfaceDetectorWhat it covers
Wiki pagesdeclared-watch/1Registered wiki pages with explicit watches.
Docsdocs-declared/1Markdown files such as READMEs, guides, and runbooks with explicit watches.
Code commentscomment-assoc/1Comments attached by a language parser to Rust (.rs), TypeScript (.ts and .tsx), JavaScript (.js and .jsx), C# (.cs), PowerShell (.ps1), shell (.sh), or Python (.py) symbols. Python docstrings are included.

A detector is deterministic code that converts a change into possible allegations. Deterministic means the same input produces the same output. A symbol is a named code element, such as a function, type, or method. Parser-owned association avoids guessing which nearby symbol a comment describes. The table names each surface's declared-watch detector; the exact-reference audit described below can also nominate unwatched text. Floating comments and generated files are skipped.

Declared watches

A declared watch is an explicit dependency from prose to code. It uses YAML frontmatter: structured metadata between --- lines at the beginning of a Markdown file.

--- staleness: mode: flag watches: - repo: ranch-hand paths: ["crates/auth-api/src/routes.rs"] symbols: ["unread_count"] section: "setup/windows" ---
  • mode: flag is the only current mode.
  • repo is a configured workspace repository key and is required.
  • paths are repository-relative paths. A trailing slash watches a directory prefix.
  • symbols match both a bare symbol name and qualified forms such as module::name.
  • section is an optional slash-separated heading anchor. Omit it to watch the whole file.

More than four watches per page, or more than eight paths or symbols in one watch, produces a breadth warning. Invalid repository names, empty scopes, escaping paths, invalid symbols, invalid sections, and unknown modes are rejected. If the target prose file is deleted, its open allegations become obsolete.

Historical passages and versioned claims

A Markdown passage bounded by exact <!-- paniolo:historical:start --> and <!-- paniolo:historical:end --> lines is exempt from the deleted-reference audit. The markers must pair and cannot nest; the rest of the page remains eligible.

A watched section can also state the version and date its claim covers: <!-- paniolo:claim-scope version=paniolo-0.4.x as-of=2026-06 -->. This section-local marker prevents agents from judging an explicitly historical claim against today's code alone. If the named version resolves to a Git revision, the evidence packet includes a bounded excerpt from that revision. Otherwise agents retain uncertainty rather than inventing a confident verdict. These marker features ship in 0.5.80.

Detection and retrieval

Precise watches plus measured fuzzy discovery

The released production path uses declared watches. A Git diff — the exact changes between two commits — is matched against watched paths and symbols. Matching prose becomes a candidate for verification.

unwatched-ref/1 also checks wiki pages, docs, and parser-attached comments for exact references to deleted or renamed code paths and symbols. It can nominate an unwatched passage, but suppresses a location already covered by a declared watch. This is exact-reference matching, not a claim that all semantic drift can be detected. Each detector lane can be deferred or switched off per repo; a lane files normally unless its configured mode says otherwise.

A separate volatile-claim audit looks for versions, dates, counts, and other moving phrases. Its capped suggestions are measurements, not allegations. Promotion requires a declared watch and evidence that the same literal changed from an old to a new value at the named source revision. Routine scans do not yet extract those old and new literals, so automatic promotion remains off.

qmd is Paniolo's search layer. It combines keyword search, semantic search, and a reranker: a model that reorders already retrieved passages by likely relevance. Its current shadow role in stale is to find related passages that have no declared watch. You can run that path alongside ordinary scans as a non-authoritative measurement lane.

changed code entity → retrieval builds a candidate pool of possibly related documents → reranking orders the candidate sections → the top K sections are scheduled for verification → lower-ranked sections are deferred, not declared fresh

A candidate pool is the bounded set of possible matches. Top K means the first K results after ranking. Active declared detection defaults to four candidates per changed entity and 50 immediately processed allegations per scan. Shadow qmd measurement uses a separate 20-document pool and records the top two reranked sections as the work it would schedule.

qmd retrieval and reranking are currently a shadow lane: an experimental path that is measured but cannot affect production outcomes. It must pass a fresh evaluation on a hidden test set before admission. Even after admission, qmd will only nominate and prioritize passages. Its scores will never set a verdict, confirm freshness, or increase merge confidence.

When enabled, each live scan stores three separate views: qmd-fusion records retrieved documents, qmd-section-pool records every section inside those documents, and qmd-rerank records the reordered sections and scores. The record also fingerprints the normalized query, query recipe, and exact embedding and reranking models. It stores identifiers, ranks, and scores rather than copying source text.

The reranker sees only sections from the retrieved document pool. That matters because reranking cannot recover a document retrieval missed. A qmd failure appears in the command's qmd_shadow report, but the deterministic scan continues. A dry run writes no shadow records.

Source-code shadow scoring now requires an index-integrity manifest: a run-specific inventory of source revisions, content hashes, indexed documents and chunks, and model fingerprints. A missing, stale, duplicate, unembedded, or mixed-model index fails shadow scoring; it is not counted as a retrieval miss. Index lag, document-pool misses, and section-reranking misses are measured separately. This safeguard also ships in 0.5.80.

Agent adjudication

Four independent jobs, each with a narrow contract

An agent is a coding model invoked through a local CLI. Adjudication is the process of judging an allegation and its proposed repair. Each role starts in a fresh process with no shared chat or resume state.

RoleWhat it receivesWhat it must do
VerifierBounded prose, code, and immutable evidenceDecide whether the allegation is relevant and whether the passage is stale or fresh, with exact citations.
Verdict challengerThe sealed verdict body, but not the verifier's hidden reasoningTry to disprove the verdict. Disagreement retains the item as insufficient evidence.
RemediatorA confirmed allegation and its evidenceWrite the smallest unified-diff patch inside the alleged file and section.
Patch challengerThe sealed patch and evidenceTest whether the patch is correct, complete, and confined to the allowed span.

A unified diff is the standard line-by-line patch format used by Git. A sealed result is written as immutable evidence before the next role sees it. This prevents one agent from quietly changing its answer after a challenge.

Adapters

An adapter is compiled integration code that invokes one supported agent CLI with fixed safety settings and normalizes its response. The admitted adapters are codex, claude, cursor, and devin.

AdapterInvocation shape
Codexcodex exec in a read-only sandbox, with JSON output
Claudeclaude -p with file, shell, notebook, and web tools disabled
Cursorcursor-agent -p in ask mode, with workspace trust acknowledged and JSON output
Devindevin -p with a prompt file, automatic permission policy, and JSON output

Agent subprocesses receive a scrubbed environment, inherit no secrets, have capped output, and are terminated at the configured timeout. They authenticate through their own signed-in CLI configuration.

How a verdict becomes a disposition

Verifier resultChallengeDisposition
Relevant and staleUpheldconfirmed-stale
Relevant and fresh, or irrelevantUphelddismissed
Any verdictNot upheldinsufficient-evidence
Agent error or invalid responseNot applicableOne bounded repair retry, then insufficient-evidence

A stale or fresh verdict must cite stored excerpt identifiers whose content hashes match the evidence packet. A content hash is a compact fingerprint of bytes; if the content changes, the fingerprint changes. Search scores, expected answers, dataset labels, and split names are forbidden from agent packets so judges cannot see the answer key.

State machine

Every outcome is explicit and reversible when evidence changes

A state machine is a fixed set of states and allowed transitions between them. Stale rejects any transition outside this table.

StateMeaning
pending-verificationNo supported verdict exists yet.
confirmed-staleThe verifier and verdict challenger agree that the claim is true.
remediation-proposedA verified, isolated prose or comment patch is ready for publication.
resolved-updatedThe repair passed required gates and landed.
dismissedIndependent verification found the allegation false.
insufficient-evidenceThe agents disagreed or could not ground a verdict. The work is retained.
obsoleteThe target prose location no longer exists.

The open queue contains pending, confirmed, proposed, and insufficient-evidence items. New evidence or an edit at the target location reopens both open and previously resolved work as pending-verification. An edit never counts as proof that the problem was fixed.

Each mutable allegation has a revision number. A writer must name the revision it read; if another process changed the item first, the stale writer fails instead of overwriting newer evidence. This is called optimistic concurrency control.

Triggers

The CLI does not schedule itself

A trigger is the event and policy boundary that starts part of the loop. An operator, continuous-integration workflow, or external scheduler must invoke a stale command.

TriggerCommandEffect
Manual previewscan --dry-runReports candidates without agents or writes.
Manual detectionscanStores allegations and retrieval-run records.
Agent-observed filingflagStores one bounded, deduplicated observation already encountered during the agent's task; starts no repair. Requires an explicit staleness.enabled: true.
Pull-request advisoryscan --dry-run in CIPublishes a non-blocking summary and artifact with scan outcome and elapsed time; coverage appears when available.
Manual adjudicationrunInvokes agents for pending and confirmed work.
Repair publicationproposeCreates remediation pull requests.
Merge reconciliationmerge-syncReads pull-request status and updates the ledger.
Scheduled cycleworkerRuns the durable end-to-end cycle once, then exits.
Retained retryretry or worker --retry-retainedRequeues unresolved work for a later agent run.
Calibrationseed, replay, or shadow-qmdMeasures the system against known answers.

The worker is durable orchestration, not a continuously running daemon. A daemon is a background process that stays alive. One worker invocation reconciles merges, scans from saved scan checkpoints, adjudicates, proposes fixes, publishes the ledger as a pull request, and exits. Schedule the next invocation outside Paniolo.

Turning automation on or off

staleness.enabled: false disables scan, run, propose, and worker for the selected configuration. Each exits successfully with "status":"disabled" before opening the ledger. That means “not run,” not “ran and found nothing.”

Inspection, explicit queue maintenance, merge reconciliation, and calibration remain available. A workflow that passes a differently named configuration has independent policy, so disabling the root config does not silently disable that workflow.

flag has a stricter rule: the selected effective config must explicitly contain staleness.enabled: true. A missing section or implicit default does not permit filing. The working agent only files evidence it already encountered, then resumes its original task; dedicated ledger agents do the investigation and repair.

Configuration reference

Deployment policy lives in paniolo.config.json

The staleness object controls where the ledger lives, which agents fill each role, work budgets, candidate limits, content scope, and automatic merge policy. Safety invariants — immutable evidence, valid state transitions, and the merge gate — stay in compiled code and cannot be configured away.

{ "staleness": { "enabled": false, "ledgerPath": ".paniolo", "ledger": { "backend": "sqlite" }, "autoMerge": false, "agentProfiles": { "cursor-auto": { "adapter": "cursor", "model": "auto" }, "devin-swe-2-high": { "adapter": "devin", "model": "swe-2-high" } }, "roles": { "verifier": "cursor-auto", "verdictChallenger": "devin-swe-2-high", "remediator": "cursor-auto", "patchChallenger": "devin-swe-2-high" }, "limits": { "maxAllegationsPerPhase": 25, "timeoutMs": 120000, "maxOutputBytes": 262144, "maxRepairAttempts": 1, "maxPacketBytes": 49152, "maxInvocationsPerAllegation": 8 }, "retrieval": { "topK": 4, "maxImmediate": 50, "shadow": { "enabled": true, "documentPoolSize": 20, "sectionTopK": 2, "maxEntitiesPerRun": 25 } }, "surfaces": { "wikiPages": { "repositories": ["my-wiki"], "include": ["wiki/**/*.md"] }, "docs": { "repositories": ["my-app"], "exclude": ["vendor/**", "generated/**"] }, "codeComments": { "repositories": ["my-app"], "include": ["**/*.rs", "**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.cs", "**/*.ps1", "**/*.sh", "**/*.py"] } } } }

Top-level staleness fields

FieldDefaultMeaning
enabledtrueGates scan, run, propose, and worker; source-code agent filing additionally requires an explicit effective true.
ledgerPath.panioloRepository-relative directory for the published snapshot. Required when the staleness object is present. This is not the live database.
ledger.backendsqliteOpens the stale_* tables in the owner workspace.sqlite. json still parses so stale migrate can import a legacy tree; every other command rejects it.
agentProfilesOne Codex default profileNamed adapter-and-model pairs. Required when the staleness object is present.
rolesEvery role uses defaultMaps the four roles to profile names.
limitsSee belowCaps cost, duration, packet size, output, retries, and total invocations.
retrievaltopK: 4, maxImmediate: 50Bounds active candidate scheduling and optionally configures non-authoritative qmd shadow measurement.
surfacesAll repositories and pathsInclude and exclude scope for wiki pages, docs, and code comments.
autoMergefalseRequests GitHub automatic merge only after the exact proposed commit passes the local merge gate.

Live qmd shadow measurement

retrieval.shadow.enabled defaults to false. Set it to true to collect qmd funnels during live scan and worker runs. This does not enable fuzzy allegations or agent work.

FieldDefaultMeaning
enabledfalseRecords qmd observations without changing the active queue.
documentPoolSize20Maximum configured wiki or docs files retained after fusion for one changed entity.
sectionTopK2Reranked sections marked as work that would be scheduled if the lane were admitted.
maxEntitiesPerRun25Maximum changed entities measured in one scan, bounding model work and ledger growth.

Every shadow budget must be greater than zero. Fuzzy-only candidates stay unknown until independent evidence labels them. A missing allegation is not evidence that a candidate was irrelevant or fresh.

Paniolo keeps these observations in the same ledger, not a second fuzzy ledger. For each changed entity it records a lexical-only document list and a hybrid lexical-plus-vector document list for the same query. The report compares them by document ID, showing overlap, documents found only by hybrid search, and documents found only by lexical search. It separately counts the sections the reranker ordered and the top sections it would have scheduled. These differences show what each retrieval method did; they do not prove relevance until a known-answer case or independent agent verdict supplies a label.

The dogfood report exposes these measurements under retrieval_shadow as lexical_documents, hybrid_documents, overlap, hybrid_only, lexical_only, reranked_sections, and would_schedule_sections. The two exclusive lists retain the retrieval-run ID, changed entity, and canonical document ID so later labels can measure which lane found useful work.

Limits

A budget is an operational ceiling that prevents runaway work or cost. Budgets never weaken a safety gate.

LimitDefaultMeaning
maxAllegationsPerPhase25Items processed in each verifier or remediation phase.
timeoutMs120000Maximum milliseconds for one agent invocation.
maxOutputBytes262144Maximum normalized agent response size.
maxRepairAttempts1Retries after an invalid role response; zero is allowed.
maxPacketBytes49152Maximum serialized evidence packet sent to a role.
maxInvocationsPerAllegation8Hard ceiling across all four roles and their repair retries.

Positive-only limits and retrieval values must be greater than zero. The four roles require (maxRepairAttempts + 1) × 4 ≤ maxInvocationsPerAllegation. Invalid configuration aborts the command instead of falling back silently.

Surface filters

Each surface accepts repositories, include, and exclude. All three fields are optional. An omitted or empty include admits every eligible path; exclude still removes matching paths. Include and exclude values are repository-relative glob patterns: wildcard path expressions such as docs/**/*.md. Absolute paths, parent traversal, drive prefixes, and invalid globs are rejected.

Machine-local override

A gitignored paniolo.config.local.json beside the tracked config can override local policy. Objects merge recursively; arrays replace rather than append. This lets one owner enable automation locally while the shared config keeps it off:

{ "staleness": { "enabled": true } }

The overlay applies only when the selected file is canonically named paniolo.config.json. A differently named --config, such as a CI advisory config, is independent and does not inherit the root config or local overlay.

One-run overrides

Role flags on run and worker override configuration for that invocation and are recorded in evidence. They do not rewrite the config. These include --adapter, --model, per-challenger and remediator variants, --max, --timeout-ms, and --max-output-bytes.

Command reference

Inspect, detect, adjudicate, publish, and measure

All subcommands accept --root <path>, which selects the repository root, and --config <path>, which selects a Paniolo config. A relative config path resolves under the root.

Read-only inspection

CommandWhat it does
list [--actionable] [--only key[:glob[#anchor]]]Lists allegation IDs, states, sections, claims, and revisions. --actionable keeps pending verification, confirmed stale, and remediation proposed. Repeatable --only unions location selectors.
summary [--only key[:glob[#anchor]]]Allegation totals per file, open and closed, with the open subset called out.
nextPrints the first actionable allegation in stable ID order.
show <id>Shows one allegation and its sealed role observations. A unique ID prefix is accepted.
reportBuilds the per-surface dogfood report, including outcomes, conflicts, canaries, false resolutions, the agent-report slice, and an auto-merge recommendation.
statusRead-only growth and latency view of the shared database: file sizes, row counts, free pages, and bounded p50/p95 operation latency.
score-shadow <file>Validates and scores a complete qmd shadow result without agents or ledger writes. Requires a valid index-integrity manifest. A missing, stale, duplicate, unembedded, or mixed-model index fails scoring; it is not counted as a retrieval miss.

Detection and queue maintenance

CommandImportant inputsWhat it does
scanRepeatable --code key:path and --wiki key:path, plus --base, --head, --sweep, repeatable --only key[:glob[#anchor]], and optional --dry-runDetects allegations over a commit range — or, under --sweep, over every in-scope comment and document. --only bounds which locations file.
flag--target repo:path#anchor --claim text --observation file, optionally --source-revision revisionFiles a bounded observation the working agent already encountered. The observation is a UTF-8 file; this command does not verify or repair the claim.
migrate [--apply]--apply to write; optional repeatable --repo key:pathPlans a JSON-tree import into the owner workspace.sqlite. --apply imports under the run lock and sets ledger.backend to sqlite.
retry <id>Allegation ID or unique prefixRequeues insufficient, dismissed, or resolved work.
resolve <id> --note <text>A required carrying commit or pull-request noteRecords that a proposed repair landed outside a stale pull request.
prune [--apply]--apply to writePlans removal of resolved and obsolete allegations; applies only when requested.
rebase [--apply]--apply to writeRe-resolves open locations; missing targets become obsolete.

Agents and publication

CommandWhat it does
run --repo key:path [--only key[:glob[#anchor]]]Runs verifier and challenger on pending work, then remediator and patch challenger on confirmed work. --only restricts both phases to matching allegation locations.
propose --repo key:path [--only key[:glob[#anchor]]] [--dry-run]Creates one remediation pull request per remote on a staleness/rem-* branch and records the proposal; out-of-scope allegations stay pending.
merge-sync --repo key:path [--only key[:glob[#anchor]]] [--dry-run]Reads GitHub pull-request state. Merged heads run the merge gate; closed pull requests clear the proposal for requeue. --only reconciles a proposal only when every record it carries is in scope.
worker --ledger-repo key:path --repo key:path [--only key[:glob[#anchor]]]Runs one durable cycle: merge-sync, checkpoint-gated scan, adjudication, proposal, and ledger publication. One selector set bounds filing, adjudication, remediation, and proposal.

propose, merge-sync, and worker require Git and an authenticated GitHub CLI, gh. On first contact, use worker --bootstrap to save each repository's current commit without scanning its entire history. Use --retry-retained to requeue all insufficient-evidence work before adjudication.

Repeatable --only key[:glob[#anchor]] selectors bound which locations an invocation may file, verify, remediate, or propose — --only paniolo.ai:docs/stale.html scopes a worker cycle to this page alone. A bare key selects the whole repository; * matches direct children, ** any depth, and repeated selectors union. An empty match is zero work, never a repository-wide fallback, and scan checkpoints still advance for every --repo — the selector bounds work, not coverage bookkeeping.

Calibration

CommandWhat it does
seed <target> <claim>Plants a known-answer stale or fresh canary that flows through normal adjudication.
replayRuns built-in known-answer cases through real adapters and evaluates frozen gates. It writes records; use a disposable root.
shadow-qmd <output.json>Builds an isolated qmd index, retrieves and reranks the docs holdout, and writes input for a full replay.
routing-fit <file>Fits a frozen cross-lane routing policy on calibration-split shadow observations and emits the fingerprinted policy JSON.
routing-eval <input> --policy <file>Evaluates a frozen routing policy against holdout shadow observations. A lane that fails any gate stays shadow-only.

index projects each allegation into the reserved stale-ledger qmd collection. Scoped queries can opt in; unscoped search and prompt hooks never return ledger rows. packet prints the bounded remediation packet for one allegation. verify checks queued verify jobs against a checkout. eval replays a frozen gold-labeled case file against that projection and reports recall without changing ranking.

On success, commands exit with status code zero. A held worker lock is an expected no-op: the second worker prints {"stopped":"run lock held"} and exits zero. Failed agent preflight also leaves the queue unchanged and reports which role could not start.

Ledger internals

The live ledger is workspace.sqlite

Production commands open the stale_* tables in the checkout's owner workspace.sqlite. That file is outside the Git tree. On Windows it is %LOCALAPPDATA%\paniolo-harness\state\<slug>\workspace.sqlite. On Linux and WSL it is ${XDG_STATE_HOME:-~/.local/state}/paniolo-harness/state/<slug>/workspace.sqlite. The slug hashes the owner checkout path, so Windows and WSL keep separate files, and a linked worktree uses the owner checkout's database. If that state directory is not writable, the file falls back to <checkout>/.cache/paniolo-harness/state/<slug>/workspace.sqlite.

A missing database fails closed. Commands do not create an empty file and call that a finished cutover. stale migrate imports a legacy JSON tree — the old .paniolo/staleness/ record directories — and without --apply it only prints the plan. ledger.backend: json and PANIOLO_STALE_JSON are rejected. PANIOLO_STALE_DB points a disposable run at a scratch database; production commands use the owner file.

state.lock, run.lock, and the automerge.disabled kill switch sit beside that database. ledgerPath is the repository-relative directory of the published snapshot, default .paniolo. The worker commits a ledger.sqlite export there on staleness/ledger so the change can be reviewed. The live store stays in the state directory.

Record identifiers

Most records are content-addressed: their ID is derived from their content. Repeating the same scan produces the same ID instead of a duplicate.

PrefixRecord
S-Allegation
E-Evidence
X-Cited excerpt
C-Detected change
L-Evaluation label
R-Retrieval run
A-Agent-filed observation
O-Sealed agent observation
B-Remediation bundle

IDs use a truncated SHA-256 hash, a standard cryptographic fingerprint. Allegations are mutable only through revision-checked state transitions; evidence, labels, observations, and bundles are immutable. A label correction creates a new record that names the old record it supersedes.

An agent-filed A- record is not an allegation, verdict, or repair request. Filing the same target, claim, and observation again returns duplicate rather than inflating the ledger.

Scan checkpoints, worktrees, and branches

A scan checkpoint is the last source commit whose detection results were successfully saved in a merged ledger. On each cycle, the worker scans checkpoint..HEAD: everything after that saved commit through the repository's current commit. This term is unrelated to the Cursor AI agent, which is one optional agent adapter.

Scan checkpoints and pending scan heads are documents in the database. New heads stay pending until the ledger pull request merges, so a failed cycle cannot skip a range. They are not separate scan-checkpoints.json or pending-scans.json files.

A Git worktree is a second checkout connected to the same repository. Stale creates isolated .stale-rem-* worktrees for repair branches and a reusable .stale-ledger-* worktree for the ledger branch. The main checkout stays untouched. Repair branches use staleness/rem-*; ledger publication uses staleness/ledger.

Safety model

Autonomous does not mean unconstrained

The system can run without routine human verdicts because uncertainty is a first-class outcome and each authority is narrow. Search nominates. Agents produce evidence. Compiled code validates records and transitions. GitHub branch protection and repository checks remain in force.

The merge gate

A merge gate is deterministic code that authorizes the exact proposed commit only when every required fact is present:

  • The automerge.disabled file beside the live database is absent.
  • The allegation is remediation-proposed.
  • The recorded proposal commit exactly matches the merge candidate.
  • The remediation bundle belongs to the current cycle and revision.
  • All four sealed observations exist, both challengers upheld their targets, parent links match, and the patch hash matches.

Grouped repairs are all-or-nothing. A changed target hash or patch context requeues the allegation instead of force-applying stale work.

Independent controls

ControlWhat it controls
staleness.enabledWhether scan, run, propose, and worker execute. flag requires an explicit effective true.
--dry-runWhether the current supported command may persist data, call agents, or touch GitHub.
autoMergeWhether propose may request GitHub automatic merge after the local gate passes.
automerge.disabledEmergency merge kill switch beside the live database; scanning and adjudication continue.
run.lockPrevents two workers from owning the same database.
state.lockSerializes mutable read-modify-write transactions on that database.

No one switch replaces the others. Turning off automatic merge does not stop proposals. Turning off the root config does not stop a workflow with an explicit independent config.

Measurement and learning

The system earns trust with known answers

Calibration means measuring the system against examples whose correct outcomes are already known. The committed corpus contains more than 100 cases split into a tuning set and a holdout: cases hidden from tuning and used only for final evaluation.

Labels

A label is an immutable evaluation fact. It records the content surface, expected verdict, and where that expectation came from.

  • Gold labels have deterministic provenance: a seeded mutation, constructed pair, or deterministic contradiction created the known answer.
  • Silver labels come from weaker evidence such as mined repository history. They are useful for learning but cannot stand in for known truth.
  • Outcome labels record operational results such as a merged repair or a later reopening.

Agent agreement and retrieval scores cannot create gold labels. Unlabeled examples are unknown, not negative; they are excluded from metric denominators instead of being counted as fresh. Labels can improve future query templates, reranker selection, top-K scheduling, and tail exploration while remaining separate from the live judge's evidence.

Frozen gates

A gate is a threshold that must pass before a feature is admitted. Frozen means the threshold is not moved after seeing a disappointing result.

GateRequired result
Seeded-watch recall1.00
Historical mechanical recallAt least 0.80
Nomination precisionAt least 0.70
Verdict accuracyAt least 0.95
Critical errorsZero

Recall is the share of known relevant items the system finds. Precision is the share of nominated items that are truly relevant. Accuracy is the share of evaluated verdicts that are correct.

The fuzzy qmd lane has additional admission gates: at least 0.10 incremental recall, a 20–50 item pool, 0.95 pool recall, 0.90 recall within the top two reranked results, and at least 0.50 passage reduction. A gate result is go, revise, or stop.

Calibration separates nomination volume, independently labeled precision, incremental recall, and a fixed sample below the top-K cutoff. Unlabeled items in that tail remain unknown. Routing weights are fitted on the tuning set, then frozen with a fingerprint and per-case budget before holdout replay. A zero-weight lane cannot hide a relevant passage it dropped. Agent-filed reports are a separate measurement slice: only an exact claim-and-location match to an independently verified stale or fresh outcome enters its precision calculation. Repeated filings and agent agreement do not become gold labels.

Canaries and the dogfood report

A canary is a planted known-answer allegation that travels through the real production path. The report counts whether stale canaries are caught and fresh canaries are correctly dismissed. Its false-resolution budget is zero: one known false resolution recommends keeping automatic merge off.

The deterministic dogfood report breaks results down by surface and includes outcomes, sealed observations by role, conflicts, a ten-percent tail sample, canary hits and misses, false resolutions, the lexical-versus-hybrid retrieval comparison, reranker scheduling counts, and automerge_recommended. Scan reports include watch coverage and volatile-claim suggestions. Shadow scoring records index lag separately from retrieval misses. stale report includes the agent-report slice. A failed scan is never shown as zero candidates.

Current status

What is production-ready, and what is still earning admission

  • @paniolo/cli 0.5.80 contains the released stale commands, expanded code-comment language support, live qmd shadow measurement, and the admitted Devin adapter. Bounded filing with stale flag ships as of 0.5.80.
  • The live ledger is the owner workspace.sqlite. stale migrate imports a legacy JSON tree; production commands reject ledger.backend: json.
  • Declared watches and the exact deleted-or-renamed reference audit for unwatched prose (unwatched-ref/1) are both released detection paths. Each detector lane can be deferred or switched off per repo, so a lane files normally unless its configured mode says otherwise.
  • Parser-backed code-comment detection and safe comment-only remediation support Rust, TypeScript/TSX, JavaScript/JSX, C#, PowerShell, shell, and Python. Python module, class, and function docstrings count as documentation comments.
  • Version 0.5.80 can collect live qmd shadow results for configured wiki pages and docs without creating allegations, and score them with score-shadow, routing-fit, and routing-eval. A fresh complete holdout replay must still pass every fuzzy-lane gate before a fuzzy lane is admitted to production.
  • The source tree can run ahead of the published CLI between releases. Check paniolo stale --help and the relevant subcommand's help for what your installed version carries before relying on a newer flag or report slice.
  • Codex, Claude, Cursor, and Devin adapters are admitted. Cursor auto and Devin swe-2-high passed the nine-case synthetic verdict replay together.
  • The durable worker runs one cycle and exits. You provide the scheduler and authorized local or self-hosted compute.
  • The pull-request advisory is read-only, has no agent credentials, and cannot block a merge.
For coding agents

Install the operator guidance with the command

A skill is a packaged set of instructions and references that teaches a coding agent how to use a tool safely. The read-mostly paniolo-stale skill covers scanning, inspection, triage, reports, and bounded filing when the installed CLI supports it and staleness is explicitly enabled. The paniolo-stale-remediate skill covers agent runs, repair pull requests, the worker, replay, and calibration.

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

For the rest of the catalog, see Paniolo skills. To build the knowledge base that stale protects, see LLM Wiki. For the papers and practitioner posts behind each feature, see Stale research. For workspace configuration beyond the staleness block, see paniolo.config.json.