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.
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.
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 workEvidence 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.
Start simple, then go as deep as you need
- Quick start
- What stale protects
- How candidates are found
- How agents verify and repair work
- The allegation state machine
- What starts the automation
- Configuration reference
- Command reference
- Ledger and identifiers
- Safety and merge controls
- Metrics, labels, and calibration
- Current capabilities and limits
- Research map — papers and posts behind each feature
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.
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.
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.
| Surface | Detector | What it covers |
|---|---|---|
| Wiki pages | declared-watch/1 | Registered wiki pages with explicit watches. |
| Docs | docs-declared/1 | Markdown files such as READMEs, guides, and runbooks with explicit watches. |
| Code comments | comment-assoc/1 | Comments 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: flagis the only current mode.repois a configured workspace repository key and is required.pathsare repository-relative paths. A trailing slash watches a directory prefix.symbolsmatch both a bare symbol name and qualified forms such asmodule::name.sectionis 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.
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 freshA 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.
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.
| Role | What it receives | What it must do |
|---|---|---|
| Verifier | Bounded prose, code, and immutable evidence | Decide whether the allegation is relevant and whether the passage is stale or fresh, with exact citations. |
| Verdict challenger | The sealed verdict body, but not the verifier's hidden reasoning | Try to disprove the verdict. Disagreement retains the item as insufficient evidence. |
| Remediator | A confirmed allegation and its evidence | Write the smallest unified-diff patch inside the alleged file and section. |
| Patch challenger | The sealed patch and evidence | Test 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.
| Adapter | Invocation shape |
|---|---|
| Codex | codex exec in a read-only sandbox, with JSON output |
| Claude | claude -p with file, shell, notebook, and web tools disabled |
| Cursor | cursor-agent -p in ask mode, with workspace trust acknowledged and JSON output |
| Devin | devin -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 result | Challenge | Disposition |
|---|---|---|
| Relevant and stale | Upheld | confirmed-stale |
| Relevant and fresh, or irrelevant | Upheld | dismissed |
| Any verdict | Not upheld | insufficient-evidence |
| Agent error or invalid response | Not applicable | One 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.
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.
| State | Meaning |
|---|---|
pending-verification | No supported verdict exists yet. |
confirmed-stale | The verifier and verdict challenger agree that the claim is true. |
remediation-proposed | A verified, isolated prose or comment patch is ready for publication. |
resolved-updated | The repair passed required gates and landed. |
dismissed | Independent verification found the allegation false. |
insufficient-evidence | The agents disagreed or could not ground a verdict. The work is retained. |
obsolete | The 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.
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.
| Trigger | Command | Effect |
|---|---|---|
| Manual preview | scan --dry-run | Reports candidates without agents or writes. |
| Manual detection | scan | Stores allegations and retrieval-run records. |
| Agent-observed filing | flag | Stores one bounded, deduplicated observation already encountered during the agent's task; starts no repair. Requires an explicit staleness.enabled: true. |
| Pull-request advisory | scan --dry-run in CI | Publishes a non-blocking summary and artifact with scan outcome and elapsed time; coverage appears when available. |
| Manual adjudication | run | Invokes agents for pending and confirmed work. |
| Repair publication | propose | Creates remediation pull requests. |
| Merge reconciliation | merge-sync | Reads pull-request status and updates the ledger. |
| Scheduled cycle | worker | Runs the durable end-to-end cycle once, then exits. |
| Retained retry | retry or worker --retry-retained | Requeues unresolved work for a later agent run. |
| Calibration | seed, replay, or shadow-qmd | Measures 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.
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
| Field | Default | Meaning |
|---|---|---|
enabled | true | Gates scan, run, propose, and worker; source-code agent filing additionally requires an explicit effective true. |
ledgerPath | .paniolo | Repository-relative directory for the published snapshot. Required when the staleness object is present. This is not the live database. |
ledger.backend | sqlite | Opens the stale_* tables in the owner workspace.sqlite. json still parses so stale migrate can import a legacy tree; every other command rejects it. |
agentProfiles | One Codex default profile | Named adapter-and-model pairs. Required when the staleness object is present. |
roles | Every role uses default | Maps the four roles to profile names. |
limits | See below | Caps cost, duration, packet size, output, retries, and total invocations. |
retrieval | topK: 4, maxImmediate: 50 | Bounds active candidate scheduling and optionally configures non-authoritative qmd shadow measurement. |
surfaces | All repositories and paths | Include and exclude scope for wiki pages, docs, and code comments. |
autoMerge | false | Requests 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.
| Field | Default | Meaning |
|---|---|---|
enabled | false | Records qmd observations without changing the active queue. |
documentPoolSize | 20 | Maximum configured wiki or docs files retained after fusion for one changed entity. |
sectionTopK | 2 | Reranked sections marked as work that would be scheduled if the lane were admitted. |
maxEntitiesPerRun | 25 | Maximum 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.
| Limit | Default | Meaning |
|---|---|---|
maxAllegationsPerPhase | 25 | Items processed in each verifier or remediation phase. |
timeoutMs | 120000 | Maximum milliseconds for one agent invocation. |
maxOutputBytes | 262144 | Maximum normalized agent response size. |
maxRepairAttempts | 1 | Retries after an invalid role response; zero is allowed. |
maxPacketBytes | 49152 | Maximum serialized evidence packet sent to a role. |
maxInvocationsPerAllegation | 8 | Hard 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.
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
| Command | What 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. |
next | Prints the first actionable allegation in stable ID order. |
show <id> | Shows one allegation and its sealed role observations. A unique ID prefix is accepted. |
report | Builds the per-surface dogfood report, including outcomes, conflicts, canaries, false resolutions, the agent-report slice, and an auto-merge recommendation. |
status | Read-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
| Command | Important inputs | What it does |
|---|---|---|
scan | Repeatable --code key:path and --wiki key:path, plus --base, --head, --sweep, repeatable --only key[:glob[#anchor]], and optional --dry-run | Detects 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 revision | Files 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:path | Plans 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 prefix | Requeues insufficient, dismissed, or resolved work. |
resolve <id> --note <text> | A required carrying commit or pull-request note | Records that a proposed repair landed outside a stale pull request. |
prune [--apply] | --apply to write | Plans removal of resolved and obsolete allegations; applies only when requested. |
rebase [--apply] | --apply to write | Re-resolves open locations; missing targets become obsolete. |
Agents and publication
| Command | What 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
| Command | What it does |
|---|---|
seed <target> <claim> | Plants a known-answer stale or fresh canary that flows through normal adjudication. |
replay | Runs 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.
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.
| Prefix | Record |
|---|---|
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.
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.disabledfile 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
| Control | What it controls |
|---|---|
staleness.enabled | Whether scan, run, propose, and worker execute. flag requires an explicit effective true. |
--dry-run | Whether the current supported command may persist data, call agents, or touch GitHub. |
autoMerge | Whether propose may request GitHub automatic merge after the local gate passes. |
automerge.disabled | Emergency merge kill switch beside the live database; scanning and adjudication continue. |
run.lock | Prevents two workers from owning the same database. |
state.lock | Serializes 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.
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.
| Gate | Required result |
|---|---|
| Seeded-watch recall | 1.00 |
| Historical mechanical recall | At least 0.80 |
| Nomination precision | At least 0.70 |
| Verdict accuracy | At least 0.95 |
| Critical errors | Zero |
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.
What is production-ready, and what is still earning admission
@paniolo/cli0.5.80 contains the released stale commands, expanded code-comment language support, live qmd shadow measurement, and the admitted Devin adapter. Bounded filing withstale flagships as of 0.5.80.- The live ledger is the owner
workspace.sqlite.stale migrateimports a legacy JSON tree; production commands rejectledger.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, androuting-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 --helpand 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
autoand Devinswe-2-highpassed 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.
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.
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.