Development

Local verification gate (run all before opening a PR):

python -m ruff check .
python -m ruff format --check .
python -m pytest
sphinx-build -b html docs _build/html -W
python -m build
twine check dist/*

Testing

  • All tests use synthetic/public-safe fixtures (fresh_fuchs.instance.synthetic and tests/conftest.py); no private bundle data, commercial GIS, desktop applications, credentials, or Gurobi licences are required in CI.

  • The orchestration tests (tests/test_orchestration.py) need the freshforge package (the orchestration/dev extra) and guard with pytest.importorskip so the core suite stays green without it.

  • Deterministic anchors (managed land base, even-flow mean harvest, NPV-max parity) are regression-gated in the tests and recorded in planning/validation-report.md.

ws3 version compatibility

The suite runs against both PyPI ws3 1.0.5 (what CI installs) and the editable 1.1.0a4 source checkout. Two compatibility rules matter:

  • Never write dt.operability[acode][period] = None — 1.0.5 crashes; use an empty age window (0, -1) to close a period.

  • Rotation floor/ceiling policies are applied as operability age windows (floor, ceiling), which works on both versions.

Layout

  • src/fresh_fuchs/instance — bundle -> extended ws3 model + synthetic instance (Phase 1).

  • src/fresh_fuchs/economy — NPV surface and cash flows (Phase 2).

  • src/fresh_fuchs/scenario — full-MC scenario engine (Phase 3).

  • src/fresh_fuchs/outer — policy grid + risk + ranking (Phase 4).

  • src/fresh_fuchs/orchestration — freshforge workflows/matrices + evidence (Phase 5).

  • src/fresh_fuchs/cli.py — thin CLI wrappers over the Python APIs.

Governance, the strict development workflow (one phase = one parent issue = one feature branch), issue-quality standards, and the reuse boundary are documented in AGENTS.md and CONTRIBUTING.md.