immutable-design-guard

What problem does it solve?

This Skill helps engineers and reviewers verify that changes to Knowledge Home do not violate the immutable data model and Alt canonical contract by detecting patterns that undermine append-only event modeling, reprojectability, and projection versioning.

Core Features & Use Cases

• Append-first validation: Detects updates or deletes against event tables and checks for missing idempotency keys.
• Resource vs Event separation checks: Flags attempts to conflate resource rows with time-based events or to hide events behind updated_at fields.
• Event timestamp and projector checks: Ensures events carry a single business time and projectors rely on event times rather than runtime Now.
• Reproject-safe and disposable projection audits: Looks for reads of latest-state in projectors, direct projection mutations, and projection_version misuse.
• Versioning and why semantics: Verifies summary/tag version append semantics, permissioned why codes, and merge-safe upserts for summary_state and dismissed_at.
• Actionable reporting: Produces short Immutable Design Findings with severity, violated principle names, why it's dangerous, and event-first alternatives.

Quick Start

Run the immutable-design-guard to audit proposed changes touching knowledge_events, projector logic, or projection tables and produce an Immutable Design Findings report.