PuGa/docs/roadmap.md

Roadmap

Open work only - what's already built/fixed is discoverable from CLAUDE.md's Tools list, docs/library.md, docs/decisions.md, and module docstrings, not repeated here.

Todo

• tools/arb.py: inter-CX arbitrage at real fill size (replaces prun_cxarb.py, which overstated profit 7-11x on 2/4 top hits).
• tools/haul.py: fuel cost / profit per trip (route.py has the jump graph).
• tools/portfolio.py: profit-maximizing set of 1-building opportunities under shared housing/capex/permits. Ties into backlog #2 (profit/permit ranking, needs this tool to mean anything - permits bind at the whole-base level, not per-recipe).
• Docs to fill: docs/apex.md, docs/fio.md, docs/playbook.md.

Backlog: review findings, still open (spot-checked against code)

1. scan.py payback ignores working capital (input stock/output inventory/consumables) - can rival building capex for smelting-type recipes. buy.py already computes this number.
2. No profit/permit ranking (permits bind at the base level, not per-recipe) - needs tools/portfolio.py's cross-recipe/whole-base view.
3. scan.py doesn't charge degradation (capex/180/day) like simulate.py does - small but real inconsistency between tools ranking the same thing.
4. No input-side flow cap (buying a big share of an input's flow should price-impact like selling output does) - documented as absent, not modelled.
5. persistence.py --lag 3 default is too low given docs/mechanics.md's weekly workforce distribution - real lag is 3-10 days.
6. Possible forward-fill bias if any tool reindexes daily_prices() onto a full calendar grid (it only emits trade days) - would understate volatility for sparse tickers. Not yet confirmed whether persistence.py/undervalued.py actually do this.
7. undervalued.py's backtest (+21.3%/3mo) has no control group - meaningless without the universe's unconditional return over the same window.
8. persistence.py measures past margin variance of a market we were NOT in - can't see the dominant real risk (our own entry + the next player's compressing margin).
9. undervalued.py::manufacturing_candidates() keeps the first recipe seen per output, not the cheapest (seen.setdefault).
10. scan.py hab cost ignores combined habs (HBB/HBC/HBM/HBL), which can be cheaper per head.
11. scan.py --trip-cost still defaults to the flat 9250 placeholder despite the real puga/shipping.py model existing and already used by whatif.py.
12. sell.py's s0 is the day's VWAP, not its high - --tiers touch probability is slightly pessimistic (same discretization conservatism as empirical_touch(), see docs/decisions.md).
13. empirical_touch()'s optional horizon (fixed-window right-censoring) exists but isn't wired into any tool's default call yet.

Open questions

• FIO REST and FIO API are separate services/keys (.env). FIO_REST_KEY works on rest.fnar.net; FIO_API_KEY's host is unknown; PRUNplanner's Api-Key works. doc.fnar.net/api.json has no securitySchemes.