Add project analysis and improvement plan, move to a supported Python and add CI

[Copilot]

Audit of InventoryOptimizer: document what the project is and what it needs, and land the fixes that could be verified without changing metric behaviour. The wider multi-repo brief could not run here (see Needs your action).

Documentation

• docs/PROJECT_ANALYSIS.md and docs/PROJECT_ANALYSIS_DETAILED.md: architecture, verified setup commands, code quality, testing, security, performance, tooling and risks, based on main at 98e48fb.
• docs/IMPROVEMENT_PLAN.md and docs/IMPROVEMENT_PLAN_DETAILED.md: IMP-01 to IMP-12 with evidence, effort, risk and acceptance criteria.
• README: Documentation section near the top, Python 3.11+ noted as a prerequisite for the local run, and metrics table rows 1 and 6 corrected to match the code.
• METRICS_DOCUMENTATION.md: a "Currently implemented" note under safety stock, store turnover and profitability, where the documented formula and the code diverge.

Fixes

• Docker base image python:3.8-slim → python:3.12-slim. On 3.8 pip resolves scikit-learn 1.3.2 (PYSEC-2024-110) and pillow 10.4.0 (17 advisories); on 3.12 pip-audit reports nothing for any project dependency.

• The test script now signals failure. Its __main__ block printed the result and fell off the end, so it exited 0 regardless, making the inventory-optimization-tests pre-commit hook a no-op:

  sys.exit(0 if result.wasSuccessful() else 1)

• CI. .github/workflows/tests.yml runs the suite on ubuntu-latest / Python 3.12 for pull requests and pushes to main, with contents: read, concurrency cancellation and a timeout.

• Dead code. Unused imports in both modules and the unused service_level in calculate_safety_stock.

Top findings not fixed here

• InventoryLevel is redrawn at random each day (inventory_optimization.py:131) with no link to sales or deliveries, so turnover, stock-out risk and days-to-stock-out describe noise - store turnover lands near 244 on a default run against the roughly 2.0 in the README. IMP-02 needs a decision on the simulation model.
• Three documented formulas differ from the code; annotated, not resolved (IMP-03).
• flake8 exits 1 with 354 findings, so the lint hook still cannot pass; fixing it means a one-off reformat (IMP-04).

Needs your action

• The brief covered 119 repositories with ~/repo-audit/ ledgers, per-repo worktrees and PRs in each repository. This session has one clone, no authenticated gh and no access to /Users/svijayakumar/Desktop/repos/personal, so only this repository was processed and everything is on one branch rather than several focused ones.
• IMP-09 (untracking the 2.3 MB of generated CSVs in data/) deletes committed files, so it is left for you.