xcheck

xcheck

Cross-agent audit & remediation methodology for projects too large to trust to a single agent session — codebases, book manuscripts, reference corpora, documentation sets.

Two AI agents and one human run a cycle:

audit (agent A) → triage (you) → remediate (agent B) → verify (agent A) → repeat

until the pass queue is empty and every finding reaches a terminal status. Agents communicate only through files in an audit/ directory inside the audited project; you carry the baton between sessions and make exactly one mandatory kind of decision — which findings to fix.

Repository: github.com/vsov/xcheck · License: MIT · Orchestrator: Python 3, stdlib only, zero dependencies.

---

Table of contents

1. Why not "just ask an agent to review"
2. When to use it (and when not to)
3. Concepts in five minutes
4. Repository layout
5. Installation
6. Quickstart: your first audit
7. Launchers: skills for Codex and Claude Code, commands for OpenCode
8. The orchestrator
9. Agent mapping and cross-agent discipline
10. The audit/ directory in your project
11. Class findings: fixing the disease, not the symptom
12. Configuration reference
13. Language policy
14. Troubleshooting & FAQ
15. License

---

1. Why not "just ask an agent to review"

A single long "review my project" conversation over a large body of material fails in a predictable way: the agent loses the thread, invents specifics, and hallucinates both findings and "fixes." xcheck replaces trust in agent memory with four mechanisms:

1. Narrow chartered sessions. Every session gets an exact scope ("dimension terminology, chapters 4–6, stop after 15 findings") and is obligated to stop rather than skim. A session with no charter must refuse to start.
2. The evidence standard. A finding without a character-exact quote, a locator, and a named violated norm is invalid by construction. The quote can be re-checked with grep — a hallucination does not survive.
3. Validation before fixing. The remediating agent must re-confirm every finding against the source before changing anything. Invented findings die here, marked disputed.
4. Cross-verification. The fix is judged by an agent that did not write it — a separate session with the standing instruction "your job is to prove the fix wrong, not to confirm it."

On top of that, every finding is screened for systemicity before it is fixed: a census of the whole corpus asks whether this is one instance of a repeating error. At three or more instances, the whole class is fixed — including the norm that produced it.

2. When to use it (and when not to)

Good fit: a project that does not fit into one attentive reading session — a book, a series of reference volumes, a codebase from ~10 files up, a documentation corpus — where the question is "what is systematically wrong here," not "fix this typo."

Poor fit: a point bugfix, a single-diff review, a 200-line file. There the cycle costs more than it returns — ordinary code review is enough.

3. Concepts in five minutes

Roles

Role	Who (default)	What they do
Planner	agent, 1 session	Inventories the project and its norms → AUDIT.md: dimensions, unit map, pass queue
Auditor	agent, N sessions	One pass = one dimension × a batch of units → findings + a coverage report
Triage	you	accepted / rejected / deferred in the ledger — the single mandatory human gate
Remediator	agent, N sessions	A batch of accepted findings: validate → census → plan → fix → self-check
Verifier	agent, N sessions	A verdict on every fix: closed or reopened. Never the one who fixed it

Role ≠ agent: any capable agent can play any role. Two rules are hard: the Verifier never judges its own fix, and only one writing session runs at a time.

Finding lifecycle

reported ──(triage: you)──► accepted | rejected | deferred
accepted ──(Remediator)───► validated ► planned ► fixed
                            └► disputed | obsolete | superseded-by-class
fixed ─────(Verifier)─────► closed | reopened
reopened ──(Remediator)───► planned ► fixed again (attempts += 1)

Terminal statuses: closed, rejected, withdrawn, obsolete, superseded-by-class (with a closed class finding). deferred is not terminal — it is your debt to re-triage.