erp-report-engine: Instructions file for Codex

AGENTS.md — working on this repo with an AI coding agent

Context for coding agents (and fast-moving humans) contributing here.

What this is

A read-only autonomous reporting engine that runs SQL against the database behind an ERP and renders a weekly HTML report. The two things that must survive any change: the read-only guarantee and the report's honesty features (audit trail, reconciliation, data-quality gate, explicit definitions).

Hard invariants — never weaken these

1. connect.safe_read is the only path to the database. Do not add a second one; route new queries through it.
2. assert_read_only must keep rejecting: multiple statements, comments (--, /*), non-SELECT/WITH heads, and the forbidden keyword list (including INTO, EXEC, CALL). If you touch it, extend tests/test_engine.py::test_guard_blocks_writes_and_tricks first.
3. Profile {placeholders} accept identifier-safe values only (^[A-Za-z0-9_]{1,16}$). All runtime values (dates, thresholds) travel as bound parameters (:since), never string-formatted into SQL.
4. Secrets never land in files or code. The config loader's embedded-password refusal stays.
5. The report keeps its audit trail, source reconciliation, data-quality section and definitions footer. Features that hide information don't merge.
6. Trends plot completed ISO weeks only — never the current partial week.

Layout

erp_report_engine/
  errors.py          # exception taxonomy with stable exit codes (2/3/4/5)
  config.py          # YAML config; refuses embedded credentials (make_url parse)
  guard.py           # THE security layer: 4-layer read-only guard (standalone: re + sqlglot only)
  connect.py         # engine, safe_read (the only DB path), read-only session, Auditor, retries
  semantic.py        # profile contracts (canonical entities, REQUIRED_COLUMNS); bundled resolver
  week_calendar.py   # ISO-week anchor + continuous axis (shared by report and Power BI)
  extract.py         # extraction + quality gate (dedup once) + COUNT(*) reconciliation
  kpi.py             # calendar-anchored ISO-week KPIs vs 8-week baseline
  insights.py        # deterministic findings + driver attribution
  state.py           # SQLite run memory (decline streaks, ordered by week)
  render.py          # self-contained HTML via Jinja2 autoescape (inline SVG)
  runner.py          # orchestration facade (validate / build_report / guarded_query)
  export_powerbi.py  # star-schema CSV export for the PBIP layer
  mcp_server.py      # guarded MCP server (FastMCP tools over the same read-only path)
  logsetup.py        # stderr + JSON-lines logging, run id
  cli.py             # validate / run / export-powerbi / mcp / init-demo
  demo_builder.py    # bundled synthetic demo DB builder (seeded, deliberately dirty)
  profiles/          # bundled package-data profiles: generic (canonical), logo_tiger (MSSQL)
powerbi/             # PBIP project authored as code (TMDL model + PBIR report)
  tools/generate_report_pages.py  # PBIR pages are GENERATED - edit specs, rerun, never hand-edit visual.json
demo/                # thin shim -> erp_report_engine.demo_builder (kept for docs)
tests/               # guard, contracts, calendar props, render/XSS, honesty, CLI, MCP, PBIP
pyproject.toml       # packaging (hatchling), console script, extras, ruff config