SEP-025: Structured event logging — audit trail for gate decisions

[samudzi]

SEP-025: Structured event logging — audit trail for gate decisions

Status: Open
Created: 2026-03-17
Project: .claude
Dependency: None (foundational)
Blocked by: —
Blocks: SEP-026, SEP-027, SEP-028

Summary

log_event() is defined in common.sh and the events table exists in SQLite, but almost nothing calls it. Gate denials, plan approvals, scope violations, TDD blocks — none of these write to the events table.

The validation_log state key is append-only but only captures test runs. There is no persistent audit trail of what happened in a session, making post-mortem analysis after a failure nearly impossible. You cannot answer "why is the model confused" because there's no record of what the gates saw.

Motivation

Without structured event logging:

• Debugging workflow failures requires reconstructing state from scattered markers
• There's no way to audit what gates fired, what they decided, or why
• The events table exists but is effectively dead infrastructure
• Session post-mortems are guesswork

Proposed Change

Call log_event() at every significant gate decision point:

• Plan approved / rejected
• Edit blocked (no approval, out of scope, TDD gate)
• Scope violation detected
• TDD gate triggered (tests not yet failed)
• Investigation mode triggered
• Validation pass/fail
• State marker changes (dirty set/cleared, objective verified)

Each event should include: timestamp, hook name, decision, relevant context (file path, plan hash, etc.).

Acceptance Criteria

• Every gate decision in the hook system writes a structured event to the SQLite events table
• Events include sufficient context to reconstruct the decision chain for a session
• validation_log append-only behavior is preserved but supplemented by the events table
• A query against the events table for a session produces a readable timeline of all gate decisions