Agent Audit System

.md-based audit trail for ALL agent interventions (Hermes, Claude Code, subagents). Snapshots for rollback. No database required.

Architecture

central/                        # ← Root: NOT audit-log/ standalone anymore
├── INDEX.md                   # Automatically regenerated 7h20 daily
├── audit/                     # ← Audit trail (was audit-log/)
│   ├── INDEX.md               # Chronological index (reverse order)
│   ├── YYYY/
│   │   ├── MM/
│   │   │   ├── YYYY-MM-DD.md # One entry per intervention
│   │   │   └── …
│   │   └── …
│   ├── snapshots/             # For rollback
│   │   ├── YYYY-MM-DD-HHMM/  # Timestamped snapshot
│   │   │   ├── manifest.md   # What was snapshotted
│   │   │   └── data/         # Copied files
│   │   └── …
│   └── scripts/              # Migrated from audit-log/
│       ├── audit-log.sh
│       ├── audit-search.sh
│       ├── audit-snapshot.sh
│       └── audit-rollback.sh
├── documents/                 # Guides, manuels
│   ├── guides/
│   └── manuels/
├── rapports/                  # Veille RF, system, quotidien
├── logs/quotidien/            # Copy of second-brain/05-Log/
├── signaux/                   # Cron output logs
├── snapshots/configs/         # Claude/Hermes config backups
├── configs/                   # Active config snapshots
└── scripts/
    ├── sync-drive.sh          # Daily Drive sync (cron 7h15)
    └── index-update.sh        # Auto-regenerate INDEX.md (cron 7h20)

Entry Format

# Audit — 2026-05-29 06:00

## Intervention #042 — Title
- **Agent:** Hermes | Claude Code | subagent
- **Duration:** X min | **Model:** claude-sonnet-4-6
- **Tokens:** ~XK input / ~XK output

### Actions
1. Action 1
2. Action 2

### Files modified
- path/file (created|modified, X chars)

### Result
✅ Done. Summary.

### Rollback
```bash
bash /home/bf/central/audit/scripts/audit-rollback.sh YYYY-MM-DD-HHMM

Snapshot

• ID: YYYY-MM-DD-HHMM
• Path: /home/bf/central/audit/snapshots/YYYY-MM-DD-HHMM/

## Scripts

See `references/scripts.md` for full bash scripts: audit-log.sh, audit-search.sh, audit-snapshot.sh, audit-rollback.sh.

### audit-log.sh
```bash
# Usage: audit-log.sh --agent TYPE --title "Title" [--desc "Description"]
# Creates entry in central/audit/YYYY/MM/YYYY-MM-DD.md
# Updates central/audit/INDEX.md with reverse-chronological entry

audit-search.sh

# Usage: audit-search.sh "search term"
# Greps across all central/audit/*.md files
# Returns: date, intervention#, title, agent, summary

audit-snapshot.sh

# Usage: audit-snapshot.sh "Snapshot description"
# Archives: ~/.claude/,~/.hermes/config.yaml,~/_claude/CLAUDE.md,
#           ~/.hermes/skills/, second-brain/05-Log/
# Creates: snapshots/YYYY-MM-DD-HHMM/

audit-rollback.sh

# Usage: audit-rollback.sh SNAPSHOT_ID [files...]
# Shows diff before restoring
# Restores from snapshots/YYYY-MM-DD-HHMM/data/
# Without [files], lists all available files and asks

Multi-Channel Logging (Advanced)

For critical sync operations (Vikunja ↔ Calendar, deploys, data transformations), use 3 channels instead of 1:

┌──────────────────────────────────────────────┐
│  1. Fichier .md (central/audit/)             │
│     → Section dédiée, datée, action+status    │
│     → Path: /home/bf/central/audit/YYYY/MM/  │
├──────────────────────────────────────────────┤
│  2. Google Sheets                             │
│     → Feuille "Log" dédiée par opération      │
│     → Colonnes: Date, Heure, Action, Détail,  │
│       Statut, Rollback                        │
│     → Spreadsheet: 1U-GaOz6qmQaBP8NRwwRl... │
├──────────────────────────────────────────────┤
│  3. Vikunja (tâche de log)                   │
│     → Dans le projet concerné                │
│     → Label "Sync" ou "Log"                  │
│     → Description = détail de l'action       │
└──────────────────────────────────────────────┘

Quand utiliser 3 canaux :

• Sync bidirectionnelle entre services (Vikunja ↔ Calendar, etc.)
• Opérations avec rollback (modifications système)
• Actions qui impactent plusieurs services simultanément

Quand 1 canal suffit :

• Actions simples (création fichier, lecture API)
• Modifications non-critiques

Integration

• Claude Code PostToolUse hook: auto-log every Write/Bash command
• Hermes: call audit-log.sh after every major action (>3 tool calls)
• Cron: daily INDEX.md health check script (now regenerated by central/scripts/index-update.sh at 7h20)
• Drive sync: central/scripts/sync-drive.sh at 7h15 daily — pushes central/ archive to Google Drive VPS_Backups/central/

Migration History

Originally audit-log/ was standalone under /home/bf/. On 2026-05-29 it was migrated into /home/bf/central/audit/ as part of the unified central directory initiative. The old audit-log/ was preserved as central/.audit-log-backup-20260529-1246/ for rollback.

Scripts path update: If copying audit scripts from this skill, ALL paths use /home/bf/central/audit/ (not audit-log/).

Pitfalls

• Snapshots grow fast → auto-prune (>30 days old) via cron
• INDEX.md is append-only → use tac for reverse chronological (legacy); central/ now uses auto-index via index-update.sh
• Rollback = file restore, not git revert → always check diff first
• Never snapshot secrets (.env, credentials/) → add to .gitignore-style skip list