Review Checklist

Use this checklist for both agent self-check (before proposing changes) and maintainer review (when reviewing PRs). Items are grouped by category.

Validation

• make ci passes (fmt, lint, type, test, schemas-check, example, demo)
• No new warnings introduced

Hard Rules

• No print() in library code (exempt: __main__.py)
• No business logic in __init__.py (only re-exports)

Code Quality

• Type hints on all new public functions and methods
• Google-style docstrings on all new public classes and functions
• from __future__ import annotations in any new or modified file
• Exceptions use custom types from contextweaver.exceptions
• New modules ≤ 300 lines (exempt: types.py, envelope.py, __main__.py)
• 100-character line length respected

Testing

• Tests added for new functionality in tests/test_<module>.py
• Async tests use pytest.mark.asyncio
• No mocking of internal modules — uses real in-memory implementations

Architectural Consistency

• No runtime dependencies added to core (install_requires stays empty)
• context/ code is async-first with _sync wrappers
• routing/ code is sync-only
• Store changes implement the relevant protocol from protocols.py
• Adapter changes are pure stateless converters
• No text similarity logic duplicated outside _utils.py
• to_dict() / from_dict() added to any new dataclass
• Event log mutations only via append()

Pipeline Integrity

• Context pipeline stage order preserved (8 stages — see invariants)
• Dependency closure not bypassed or weakened
• Sensitivity defaults not weakened
• Changes to context/sensitivity.py received extra security scrutiny

Documentation

• CHANGELOG.md updated under ## [Unreleased]
• Module map in AGENTS.md updated if modules were added/removed/renamed
• Agent-facing docs updated if pipeline, API, or conventions changed
• Examples/demos updated if feature is user-facing
• No contradictions introduced between AGENTS.md and supporting docs

Cross-File Consistency

• Pipeline stage count/order matches across all docs and code
• Command descriptions match Makefile
• Module map matches filesystem
• Convention changes reflected in both AGENTS.md and CONTRIBUTING.md

Invariant Spot-Checks

If the change touches any of these areas, verify the corresponding invariant:

Area touched	Verify
Pipeline stages	8-stage order preserved, dependency closure intact
sensitivity.py	Defaults not weakened, security review done
Store protocols	Protocol interface unchanged or backward-compatible
serde.py or to_dict/from_dict	Both mechanisms still in use, not consolidated
_utils.py	No similarity logic duplicated elsewhere
__init__.py files	Only re-exports, no logic
envelope.py or types.py	No I/O added to data layer

Update Triggers

Update this checklist when:

• New hard rules or invariants are established.
• New review gates are identified from recurring review feedback.
• Definition of done changes (sync with workflows.md).