Merge branch 'main' into docs/contributing-guide

docs: add CONTRIBUTING.md (#1525)

CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# CONTRIBUTING.md
+
+How to contribute to Timmy Time Mission Control.
+
+## Philosophy
+
+Read SOUL.md first. Timmy is a sovereignty project — every contribution should
+strengthen the user's control over their own AI, never weaken it.
+
+Key values:
+- Useful first, philosophical second
+- Honesty over confidence
+- Sovereignty over convenience
+- Lines of code are a liability — delete as much as you create
+
+## Getting Started
+
+1. Fork the repo
+2. Clone your fork
+3. Set up the dev environment:
+
+```bash
+make install              # creates .venv + installs deps
+source .venv/bin/activate
+```
+
+See INSTALLATION.md for full prerequisites.
+
+## Development Workflow
+
+### Branch Naming
+
+```
+fix/<description>      — bug fixes
+feat/<description>     — new features
+refactor/<description> — refactors
+docs/<description>     — documentation
+```
+
+### Running Tests
+
+```bash
+tox -e unit       # fast unit tests (~17s)
+tox -e lint       # code quality gate
+tox -e format     # auto-format code
+tox -e pre-push   # full CI mirror before pushing
+```
+
+See TESTING.md for the full test matrix.
+
+### Code Style
+
+- Python 3.11+
+- Formatting: ruff (auto-enforced via tox -e format)
+- No inline CSS in HTML templates
+- Type hints encouraged but not required
+- Docstrings for public functions
+
+### Commit Messages
+
+Use conventional commits:
+
+```
+fix: correct dashboard loading state (#123)
+feat: add crisis detection module (#456)
+refactor: simplify memory store queries (#789)
+docs: update installation guide (#101)
+test: add unit tests for sovereignty module (#102)
+chore: update dependencies
+```
+
+Always reference the issue number when applicable.
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Run `tox -e pre-push` — must pass before you push
+4. Push your branch and open a PR
+5. PR title: tag with description and issue number
+6. Wait for CI to pass
+7. Squash merge only — no merge commits
+
+**Never:**
+- Push directly to main
+- Use `--no-verify` on git commands
+- Merge without CI passing
+- Include credentials or secrets in code
+
+## Reporting Bugs
+
+1. Check existing issues first
+2. File a new issue with:
+   - Clear title
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment info (OS, Python version)
+   - Relevant logs or screenshots
+
+Label with `[bug]`.
+
+## Proposing Features
+
+1. Check existing issues and SOUL.md
+2. File an issue with:
+   - Problem statement
+   - Proposed solution
+   - How it aligns with SOUL.md values
+   - Acceptance criteria
+
+Label with `[feature]` or `[timmy-capability]`.
+
+## AI Agent Contributions
+
+This repo includes multi-agent development (see AGENTS.md):
+
+- Human contributors: follow this guide
+- AI agents (Claude, Kimi, etc.): follow AGENTS.md
+- All code must pass the same test gate regardless of author
+
+## Questions?
+
+- Read SOUL.md for philosophy
+- Read IMPLEMENTATION.md for architecture
+- Read AGENTS.md for AI agent standards
+- File an issue for anything unclear
+
+## License
+
+By contributing, you agree your contributions will be licensed under the
+same license as the project (see LICENSE).