truth-mirror 0.4.0

Truthfulness gate and adversarial reviewer harness for AI coding agents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

# truth-mirror

`truth-mirror` is a Rust CLI that makes coding-agent claims falsifiable. It puts a
deterministic gate before commits, runs adversarial review by a *different* model
after commits, writes verdicts to a machine-readable ledger, blocks pushes with
unresolved rejections, and reinjects unresolved findings into Claude / Codex / Pi
prompt surfaces.

The whole point: a coding agent grading its own work over-rates it. `truth-mirror`
puts an opposed reviewer model on the critical path to falsify the agent's claims
without slowing its commit cadence.

## Install

```bash
cargo install truth-mirror
```

## Quickstart

```bash
# Install the shared git hooks + per-agent reinjection surfaces (any subset).
truth-mirror install-hooks --claude --codex --pi

# Review a commit with an opposed reviewer model (harness != model is enforced).
truth-mirror review <sha> \
  --watched-agent codex --watched-model gpt-5.4 \
  --reviewer-harness claude --reviewer-model claude-opus-4-1

# Drain the async post-commit review queue.
truth-mirror watch --once

# Sic the adversarial reviewer in a loop until N lies / N fuckups.
truth-mirror review <sha> --strict-goal --stop-after-lies 1 --max-passes 5

# Inspect the ledger.
truth-mirror ledger list
truth-mirror ledger stats
```

## Architecture

Three layers keep the expensive review off the agent's critical path while the
cheap deterministic gates sit on the frequency-controllable actions:

1. **Pre-commit (commit-msg) gate** — blocks mechanical lies (completion wording
   without evidence, configured fake markers) with no LLM, in milliseconds.
2. **Async post-commit review** — a different reviewer model falsifies the
   commit's machine-parseable `CLAIM:` and records `PASS`/`REJECT` to the ledger.
   Optional strict two-pass and strict goal loop.
3. **Pre-push gate + reinjection** — a fast ledger read blocks pushes with
   unresolved rejections, and per-agent adapters surface findings into the next
   agent turn.

See the repository for the full threat model, the honest "what this does NOT
catch" section, `BRIEF.md` (source contract), and the OpenSpec requirements.

## License

MIT