feat: add zuban type checker, documentation guidelines, and repository organization

[GeorgePearse]

Summary

This PR introduces comprehensive improvements to type checking, documentation organization, and project guidelines:

1. Zuban type checker integration - Fast Rust-based type checker for gradual type annotation adoption
2. Type annotation strategy - Infrastructure for incrementally adding type hints to the codebase
3. Repository organization - New scratch_files/ directory for agent-generated and operational documentation
4. Agent guidelines - Clear documentation for agents on where to write supporting materials

Key Changes

1. Zuban Type Checking Setup

• Added zuban>=0.1.0 as dev dependency
• Configured mypy in pyproject.toml with all files initially ignored
• Permissive settings: allow_untyped_defs, allow_incomplete_defs, ignore_missing_imports, allow_untyped_globals
• Ready for gradual module-by-module type annotation adoption

2. Type Annotation Documentation

• Created comprehensive guide in scratch_files/TYPE_ANNOTATIONS.md
• Strategy for incrementally typing modules
• Type annotation patterns and guidelines
• Instructions for enabling modules as they get typed
• Roadmap for increasing strictness from basic → standard → strict modes

3. Repository Organization

• Created scratch_files/ directory for non-essential documentation
• Moved agent-generated docs:
  • PUBLISHING.md → scratch_files/PUBLISHING.md
  • PYPI_SETUP.md → scratch_files/PYPI_SETUP.md
  • TYPE_ANNOTATIONS.md → scratch_files/TYPE_ANNOTATIONS.md
• Kept essential docs in root: README.md, AGENTS.md, CLAUDE.md

4. Agent Guidelines Update

• Updated AGENTS.md with "📝 Agent Documentation Guidelines"
• Clear direction: Write documentation to scratch_files/ not root
• Explains rationale and acceptable documentation types
• Encourages use of capitalized markdown filenames in scratch_files/

Usage

Install:
```bash
uv sync --extra dev
```

Run type checking:
```bash
uv run zuban check .
uv run zuban check bayesian_filters/kalman/kalman_filter.py
```

Enable a module for type checking:

1. Add type annotations to the module
2. Update `ignore_patterns` in `[tool.mypy]` section of `pyproject.toml`
3. Run zuban to verify no errors
4. Fix any issues and commit

Current Status

• ✅ All 203 tests pass
• ✅ Pre-commit hooks pass
• ✅ No type errors (all files initially ignored)
• ✅ Repository root is clean and organized
• 🚀 Ready for incremental type annotation adoption

Directory Structure

bayesian_filters/
├── README.md                           (essential docs)
├── AGENTS.md                           (essential guidelines)
├── CLAUDE.md                           (essential settings)
├── pyproject.toml                      (now with zuban + mypy config)
├── scratch_files/                      (agent docs & operational guides)
│   ├── TYPE_ANNOTATIONS.md
│   ├── PUBLISHING.md
│   └── PYPI_SETUP.md
└── ... (source code)

Next Steps

1. As type coverage improves:

   • Enable modules in ignore_patterns one at a time
   • Gradually increase mypy strictness
   • Move from basic → standard → strict mode

2. Agent documentation:

   • Write all support docs to scratch_files/
   • Keep root clean for essential project docs

Files Modified

• pyproject.toml - Added zuban dependency and mypy configuration
• AGENTS.md - Added agent documentation guidelines
• scratch_files/ - New directory with moved documentation

Files Moved

• PUBLISHING.md → scratch_files/PUBLISHING.md
• PYPI_SETUP.md → scratch_files/PYPI_SETUP.md
• TYPE_ANNOTATIONS.md → scratch_files/TYPE_ANNOTATIONS.md

Related

Complements the workflow improvements made in #125 (Testing/kalman-core)

[github-actions]

Coverage report

This PR does not seem to contain any modification to coverable code.