Architecture Drift Check

When to run

• After significant refactoring
• Before a release
• When the user asks if the implementation still follows the design
• When a new feature is added to an existing class

Before running

Read the following files in full:

1. .dev/design/ARCHITECTURE.md — design decisions and rationale
2. .dev/design/INVARIANTS.md — structural invariants

Review checklist

Report only findings — skip items with no issues.

1. Data structure

• The internal data structure matches the description in ARCHITECTURE.md
• No new internal structures have been introduced without being documented
• Complexity guarantees are still met

2. Invariants

• All invariants documented in INVARIANTS.md still hold
• Mutation methods restore invariants before returning
• No new mutation method has been added without verifying invariant preservation

3. Thread safety

• Locking strategy matches the documented design
• No operation reads shared state without appropriate synchronization
• No operation writes shared state without appropriate synchronization
• Snapshot-based iterators still copy under read lock (if applicable)

4. Public API

• Public API matches the documented design in ARCHITECTURE.md
• No public method has been added or removed without updating ARCHITECTURE.md and BACKLOG.md

5. Design decisions

For each design decision documented in ARCHITECTURE.md, verify that the implementation still honours the stated rationale. Common drift patterns:

• A method was added that bypasses a documented design constraint
• An optimization was introduced that changes documented complexity guarantees
• A workaround was added that contradicts a documented rejection rationale
• A configuration option was added without updating the architecture document

6. Documentation consistency

• ARCHITECTURE.md reflects the current implementation
• INVARIANTS.md reflects the current invariants
• Any design decision made during this session has been added to ARCHITECTURE.md

Output format

Report findings grouped by category. For each finding, state:

• The class or method concerned
• The drift detected (what the architecture says vs. what the code does)
• The recommended action (update the code, or update the documentation)

If no drift is found in a category, skip it entirely.