Compass Integrity Check

Overview

Compass writes a Merkle hash chain over project memory and a per-session drift signal. Both can be silently broken — a chain mismatch means a memory file was edited outside the writer; a drift-red session means the past assistant output diverged from intent. A recall hit on tampered or red-drift memory is worse than no recall.

This skill runs the integrity checks before the user commits to acting on memory.

When to invoke

Trigger conditions (any one):

1. User says "do we remember", "did we discuss", "based on past sessions" — they're about to lean on memory.
2. User points at a specific memory file or session ID — verify the chain covers it cleanly.
3. Drift incident already suspected ("why did the assistant flip on X?", "this looks like a regression") — pull recent drift history.
4. Session start in a project with memory/, before any recall fires — preflight.
5. After a crash, conflict resolution, or merge — chain may have been broken by a non-writer edit.

Skip when:

• The work is purely procedural (no memory dependency).
• The user explicitly said "ignore memory" / "don't use prior context".

How it works

The skill is a one-pass orchestrator over four already-shipped CLIs in this plugin:

The fastest path is the /compass-status slash command, which bundles all four. Use that as the primary entry; only call the individual CLIs if you need finer control (e.g. /compass-drift 30 for a longer window after a yellow signal).

Decision rules

Run the bundle, then apply this triage:

Two failure modes can stack (daemon down AND red drift). Surface both, don't pick one.

Examples

Greenlight path

User: "Did we already pick a logging format?"
Assistant: [runs /compass-status]
  daemon  : ✓ pong
  chain   : ✓ C--Users-chunx-Projects-foo
  drift   : G:91% Y:8% R:1% (7d)
  memory  : foo · 23 entries
[runs /compass-recall "logging format"]
"Yes — 2 hits. Decision in feedback_logging.md from 2026-04-22: structured JSON + level filtering ..."

Tampered path

User: "What were our deploy criteria?"
Assistant: [runs /compass-status]
  chain   : ✗ TAMPERED · 1 file (deploy_criteria.md)
"Memory chain mismatch on deploy_criteria.md — it was edited outside the writer. I won't recall from it
until we audit. `git log --diff-filter=M deploy_criteria.md` should show what changed; want me to run that?"

Daemon-down path

User: "Search prior sessions for the Postgres pool size we settled on."
Assistant: [runs /compass-status]
  daemon  : DOWN (timed out)
  chain   : ✓
  drift   : G:84% Y:13% R:2% (7d)
"BGE daemon is down — falling back to keyword search. Hits will miss paraphrases. Start it with
`bash ~/.claude/plugins/nautilus-compass/daemon_start.sh`. Want me to keyword-search now or wait?"

Anti-patterns

• ❌ Recalling silently on a tampered chain. The user should see the tamper alert before any hit lands in the response.
• ❌ Treating yellow drift as failure. Yellow = "small drift, recovered" — historically benign.
• ❌ Reading every memory file to "verify" — the chain is the verification. Don't reinvent it by content-diffing.
• ❌ Auto-regenerating the chain on tamper detection. Always ask the user — regenerating without auditing buries the evidence.

Failure & escalation

If /compass-status itself errors (e.g. ImportError, missing CLI):

1. Note the failure in plain text.
2. Fall back to letting the user proceed without memory (don't pretend to verify).
3. Open a follow-up to fix the broken check — never "best-effort silent skip".