Zekiog verified memory repo shortlist plan

.gitignore

@@ -5,6 +5,7 @@ CMakeLists_modified.txt
 
 build/
 *.egg-info
+.venv/
 
 lib/
 bin/

.impeccable/hook.cache.json

@@ -0,0 +1 @@
+{"version":1,"sessions":{}}

CONTRIBUTING.md

@@ -1,144 +1,144 @@
 # Contributing to QuantMind
 
-Thank you for contributing to QuantMind! This guide provides essential information for developers.
+Thank you for contributing to QuantMind.
 
-## 🚀 Quick Setup
+QuantMind is now a **domain library on top of the OpenAI Agents SDK**, not a
+self-contained agent framework. The first production flow is finance-first, but
+the architecture is intentionally useful for broader agentic knowledge work.
 
-1. **Fork and clone** the repository
-2. **Set up environment**:
-   ```bash
-   uv venv && source .venv/bin/activate
-   uv pip install -e .
-   ```
-3. **Install pre-commit hooks**:
-   ```bash
-   ./scripts/pre-commit-setup.sh
-   ```
+## 🚀 Quick setup
 
-## 🛠️ Development Setup
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+./scripts/pre-commit-setup.sh
+```
 
-### Pre-commit Hooks
+If `uv` is unavailable in your environment, a standard Python venv is an
+acceptable fallback:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
 
-We use pre-commit hooks to ensure code quality and consistency. These hooks automatically format code, run linting, and perform other quality checks before each commit.
+## ✅ Canonical verification loop
 
-**Install pre-commit hooks:**
+Run this before every push:
 
 ```bash
-# Automated setup (recommended)
-./scripts/pre-commit-setup.sh
-
-# Or manual setup
-pip install pre-commit
-pre-commit install
-pre-commit install --hook-type pre-push
+bash scripts/verify.sh
 ```
 
-**What the hooks do:**
+This is the single source of truth for branch health. It runs:
 
-- **On every commit:**
-  - Code formatting with `ruff format` (80-char line length)
-  - Linting with `ruff check --fix` (auto-fixes issues)
-  - File quality checks (trailing whitespace, EOF, YAML syntax)
-  - Safety checks (large files, merge conflicts)
+1. `ruff format --check`
+2. `ruff check`
+3. `basedpyright`
+4. `lint-imports`
+5. `pytest --cov`
 
-- **On push to remote:**
-  - Full unit test suite via `scripts/unittest.sh`
+CI runs the same script.
 
-**Manual execution:**
+## 🏗️ Current architecture
 
-```bash
-# Run formatting and linting
-./scripts/lint.sh
+The permanent module roots are:
 
-# Run all pre-commit hooks on all files
-pre-commit run --all-files
+- `quantmind/flows/` — apex orchestration layer
+- `quantmind/configs/` — typed inputs and config
+- `quantmind/knowledge/` — typed knowledge shapes and provenance
+- `quantmind/preprocess/` — fetch + format + clean
+- `quantmind/magic.py` — natural-language resolver
+- `quantmind/mind/` — upcoming memory/store work
+- `quantmind/utils/` — logger only
 
-# Run specific tests
-./scripts/unittest.sh tests/quantmind/sources/
-./scripts/unittest.sh all  # Run all tests
-```
+Do **not** re-introduce the deleted transitional/runtime packages such as
+`quantmind.flow`, `quantmind.config`, `quantmind.llm`, or `quantmind.models`.
+
+## 🧭 Design rules
 
-**Troubleshooting:**
+- Prefer **pure functions** over framework classes.
+- Use the **OpenAI Agents SDK directly**; do not build a new runtime wrapper.
+- Keep **Pydantic models at boundaries** and small internal value types simple.
+- Use **absolute imports** across module boundaries.
+- Keep **comments and docstrings in English** with Google-style formatting.
+- Preserve architectural boundaries enforced by `import-linter`.
 
-- If hooks fail, fix the issues and commit again
-- To skip hooks temporarily (not recommended): `git commit --no-verify`
-- Update hooks: `pre-commit autoupdate`
+## 🧪 Testing expectations
 
-## 📝 Development Standards
+- Add or update tests under `tests/` when behavior changes.
+- New feature work should cover both success and failure paths.
+- Mock external services and network calls.
+- Keep coverage above the configured floor.
 
-### Code Requirements
-- **Location**: All new code in `quantmind/` module
-- **Style**: Google-style docstrings, 80-char line length
-- **Architecture**: Abstract base classes + dependency injection
-- **Type Safety**: Pydantic models + comprehensive type hints
+For implementation work, add a simple example when it helps demonstrate the new
+behavior clearly.
 
-### Testing
-- **Unit tests**: Required in `tests/quantmind/` (mirror module structure)
-- **Coverage**: Test success and error cases
-- **Mocking**: Mock external APIs and file systems
+## 🧩 Common contribution paths
 
-### Documentation
-- **Examples**: Add to `examples/quantmind/` for new features
-- **Docstrings**: Google-style format for all public methods
+### New knowledge type
 
-## 🏗️ Contribution Types
+- Add a schema under `quantmind/knowledge/`
+- Choose the right base shape (`FlattenKnowledge`, `TreeKnowledge`, or future
+  `GraphKnowledge`)
+- Implement `embedding_text()`
+- Add tests under `tests/knowledge/`
 
-### New Sources
-- Extend `BaseSource[ContentType]` in `quantmind/sources/`
-- Add config in `quantmind/config/sources.py`
-- Include tests and usage example
+### New flow
 
-### New Parsers
-- Extend `BaseParser` in `quantmind/parsers/`
-- Handle multiple content formats with error handling
+- Add a typed input/config module under `quantmind/configs/`
+- Add a pure `async def ..._flow(...)` under `quantmind/flows/`
+- Use `preprocess/` helpers instead of duplicating fetch/format logic
+- Return a typed knowledge object
+- Add tests under `tests/flows/`
 
-### New Taggers
-- Extend `BaseTagger` in `quantmind/tagger/`
-- Support rule-based and ML approaches
+### New source or format support
 
-### Storage Backends
-- Extend `BaseStorage` in `quantmind/storage/`
-- Implement indexing, querying, and concurrent access
+- Add leaf functionality under `quantmind/preprocess/`
+- Keep `preprocess/` independent of `configs/`, `knowledge/`, and `flows/`
+- Add focused tests under `tests/preprocess/`
 
-## 🔄 Pull Request Process
+### New domain extension
 
-1. **Create feature branch** from `master`
-2. **Follow conventional commits**: `type(scope): description`
-3. **Pre-commit hooks** run automatically on commit/push
-4. **Before submitting**:
-   ```bash
-   pre-commit run --all-files
-   ./scripts/unittest.sh all
-   ```
-5. **Submit PR** using our template
+If you are adapting QuantMind beyond finance, read
+`docs/ARCHITECTURE_FOR_NEW_DOMAINS.md` first and keep the extension aligned with
+the existing layering.
 
-### PR Checklist
-- [ ] Code in `quantmind/` following architecture patterns
-- [ ] Unit tests with comprehensive coverage
-- [ ] Usage example (for new features)
-- [ ] All pre-commit hooks pass
-- [ ] Conventional commit format
+## 🔄 Pull request expectations
 
-## 💡 Development Tips
+Before submitting a PR:
 
 ```bash
-# Run specific tests
-pytest tests/quantmind/sources/
-pytest tests/quantmind/models/
+pre-commit run --all-files
+bash scripts/verify.sh
+```
 
-# Test CLI functionality
-quantmind extract "test query" --max-papers 5
-quantmind config show
+Also make sure:
 
-# Check code quality
-./scripts/lint.sh
-```
+- commits use conventional-commit style (`feat:`, `fix:`, `docs:`, `refactor:`)
+- PR titles and descriptions are written in English
+- docs are updated when behavior or extension points change
+
+## 🤖 Agent-facing documentation
+
+QuantMind is increasingly consumed by AI agents as well as humans. Treat the
+following files as product surfaces:
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `docs/ARCHITECTURE_FOR_NEW_DOMAINS.md`
+
+If you change architecture, memory semantics, or extension paths, update the
+relevant documentation in the same PR. During active iteration, these agent-
+facing docs should be reviewed regularly so agent workflows do not drift away
+from the real codebase.
 
-## ❓ Questions?
+## ❓Questions?
 
 - Check existing [issues](https://github.com/LLMQuant/quant-mind/issues)
-- Review architecture patterns in existing code
-- Look at `examples/` for usage patterns
-- See `CLAUDE.md` for detailed architecture
+- Review `CLAUDE.md` for the detailed architecture context
+- Read `docs/ARCHITECTURE_FOR_NEW_DOMAINS.md` for extension guidance
 
-Thank you for contributing! 🚀
+Thank you for contributing.