[Moshbbab]

Summary

This PR performs a safe repository maintenance pass for valuation-core-engine after inspecting the codebase structure, tests, packaging metadata, documentation, generated files, and missing automation.

Changes are intentionally reversible and avoid core valuation architecture changes.

What changed

• Replaced the README with an accurate description of the current implementation and supported workflow.
• Added CONTRIBUTING.md with local setup, review expectations, and a PR checklist.
• Added docs/maintenance-audit.md documenting technical debt, stale/risky files, missing automation, and deferred work.
• Added a GitHub Actions CI workflow for Python 3.11 and 3.12.
• Added the missing openpyxl runtime dependency used by the Excel I/O path.
• Corrected the package metadata so the console script points to the existing app.cli:main entry point.
• Updated .gitignore so sample data can remain tracked while local/private data and generated outputs are excluded.

Reasoning

The repository has a clear engineering purpose: a real estate valuation kernel with a tested Valuation Intelligence Kernel and CLI pipeline. The largest risk found was not valuation logic itself, but drift between documentation, packaging, and the actual implemented code. This PR tightens those edges without changing core formulas or architecture.

Technical debt identified

• src/core/valuation_engine.py imports modules that do not exist yet, so it should be treated as planned or experimental architecture until completed.
• README_TOOL.md and several source docstrings contain encoding artifacts.
• Runtime and developer dependencies are currently mixed in requirements.txt.
• outputs/valuation_results.json is a generated result snapshot and should not be treated as canonical source.
• A CLI smoke test would improve confidence around sample data and output shape.

Validation

• uv run --python 3.11 --with pytest --with numpy --with pandas --with scipy --with openpyxl --with python-dateutil --with pydantic --with jsonschema --with pyyaml --with python-dotenv --with structlog --with python-json-logger python -m pytest
• Result: 118 passed.
• Setup metadata was checked with Python 3.11 and returned package name valuation-core-engine and version 1.0.0.

Residual risk

The installed console-command smoke test timed out through the heavier editable-install path in the local environment. The underlying test suite passes, and the package entry point now points to the existing CLI module, but a dedicated CLI smoke test is recommended as a follow-up.

Follow-up work

1. Decide whether src/core/valuation_engine.py should become the public API or be removed/marked experimental until its dependencies exist.
2. Split dependency groups into runtime, dev, docs, API, and database extras.
3. Fix remaining encoding artifacts in docs and Python comments/docstrings.
4. Move generated output examples into explicit fixtures if tests require them.
5. Add a CI smoke test for python app/cli.py using sample data.