belief-audit

name	belief-audit
description	Use when a long session has compacted or handed off, before any Edit, to confirm Claude's belief about file contents still matches disk. Diffs current sha256 signatures against the last-recorded snapshot in `.claude/state/belief.jsonl` for the N most-recently-edited files (default 5).
when_to_use	Reach for this after session compaction, after a handoff from another agent, or manually when returning to a file after a long absence. Also fires automatically on PostCompact. Do NOT use for runtime behavior verification — use `/verify` instead.
disable-model-invocation	true
allowed-tools	["Read","Bash"]
scheduling	invoke after compaction, after agent handoff, or before re-editing files touched more than one session ago
structural	["Read .claude/state/belief.jsonl for the N most-recent unique paths","Re-compute sha256 for each path on disk now","Compare recorded signature vs current signature per path","Emit drift report (drifted paths + both hashes) and exit 1 if any drift found"]
logical	drift report emitted; exit 0 when all signatures match, exit 1 when any path has drifted

/belief-audit — Belief-State Drift Detection

After compaction, Claude's internal model of what's in a file can differ from disk reality (arXiv:2605.18747 §4.3 formalizes this as |Bk − Sk| — the gap between the agent's belief Bk and the actual system state Sk). Every Edit/Write is snapshotted automatically; this skill compares the stored signatures against current disk to surface divergence before it causes bugs.

Execution Checklist

• Run bash scripts/audit.sh [N] (default N=5) — reads .claude/state/belief.jsonl, takes the latest entry per unique path, limits to N most-recent unique paths
• Script re-computes sha256 of each path on disk
• Script emits drift report: drifted paths with recorded vs current hash; summary count for unchanged paths
• Check exit code: 0 = no drift, 1 = drift detected — if 1, re-read the flagged files before any further edits

Input / Output Examples

Example 1 — No drift

Input:

.claude/state/belief.jsonl (last 5 unique paths):
{"ts":"2026-05-20T10:00:00Z","path":"plugins/context-engine/hooks/track-edits.sh","sha256":"abc123...","agent":"main","op":"post","session_id":"s-1"}
{"ts":"2026-05-20T10:01:00Z","path":"README.md","sha256":"def456...","agent":"main","op":"post","session_id":"s-1"}

Output:

## Belief-State Audit (2 files checked)

All 2 files match recorded signatures.
Exit: 0 (no drift)

Example 2 — Drift detected

Input:

.claude/state/belief.jsonl (last 5 unique paths):
{"ts":"2026-05-20T09:00:00Z","path":"plugins/context-engine/hooks/track-edits.sh","sha256":"abc123...","agent":"main","op":"post","session_id":"s-1"}

(file was edited externally between sessions)

Output:

## Belief-State Audit (1 file checked)

DRIFT DETECTED — 1 file(s) have changed since last snapshot:

| Path | Recorded sha256 | Current sha256 |
|------|-----------------|----------------|
| plugins/context-engine/hooks/track-edits.sh | abc123... | xyz789... |

Re-read these files before editing. Run /belief-audit again to confirm.
Exit: 1 (drift found)

Known Failure Modes

• File deleted between snapshot and audit: script reports the path as missing and exits 1. Re-read or remove the stale entry.
• sha256sum unavailable: script exits 0 with a warning — do not interpret silence as no drift; install coreutils.
• belief.jsonl absent (first run): script exits 0 with "No snapshots recorded yet." — no entries to check.
• Race on belief.jsonl: two concurrent agents appending simultaneously may interleave lines. Best-effort append; worst case is a duplicate entry for the same path, which the audit deduplicates by taking the latest timestamp.