git:20260714.0e25722 to git:20260727.833c06a
26 added, 0 removed. Audit A to A.
# Reporting Package
## Purpose
Reporting converts pipeline, test, validation, evidence, and release-readiness
facts into human and machine-readable artifacts. Reports should summarize real
local evidence; they must not present missing, stale, or optional network state
as verified success.
## Map
| Area | Files | Role |
| --- | --- | --- |
| Pipeline reports | `pipeline_report_model.py`, `pipeline_io.py`, `pipeline_markdown.py`, `pipeline_html.py` | Structured per-run stage reports; validation JSON and Markdown share one `SOURCE_DATE_EPOCH`-aware timestamp. |
| Multi-project summaries | `multi_project_reporter.py`, `multi_project_report.py` | Terminal and last-run multi-project summaries. |
| Executive reports | `executive_reporter.py`, `_executive_*`, `_dashboard_*`, `_csv_*` | Dashboard, CSV, HTML, image, and markdown report generation. |
| Evidence/release | `evidence_graph.py`, `release_readiness.py` | Local evidence graph and no-network release-readiness dashboard. `evidence_graph.py` graphs this repo's own `pipeline.yaml` stage DAG (producer/consumer/validator/artifact/claim) — a structurally-similar-but-different-domain analog to `projects/templates/template_literature_meta_analysis/src/reproducibility/`'s paper-content workflow graphs; cross-reference only, the two are not merged. |
| Error/test helpers | `error_aggregator.py`, `suite_runner.py`, `pipeline_test_runner.py`, `pytest_output_parser.py` | Test orchestration and failure aggregation. |
| Coverage parsing | `coverage_json_parser.py` | `parse_coverage_json` reads pytest-cov `coverage.json` into per-file and overall coverage stats. |
| Coverage analysis | `coverage_analysis.py` | `format_coverage_status`, `analyze_coverage_gaps`, and `format_failure_suggestions` render coverage against thresholds and derive gap and failure hints. |
| Coverage facade | `coverage_reporter.py` | Backwards-compatible re-export of `parse_coverage_json`, `parse_pytest_output`, `generate_test_report`, `save_test_report_to_files`, and the coverage-analysis helpers. |
| Test summary builder | `report_builder.py` | `discover_active_projects` and `generate_summary_report` aggregate infrastructure and project suite results into one weighted summary structure. |
| Test result loaders | `result_loaders.py` | `load_test_results` and `load_infrastructure_results` read runner JSON into the `InfraResults` shape. |
| Stage 01 reporting | `pipeline_test_reporting.py` | `report_results` and `report_infra_only_results` log the Stage 01 test-execution summary in human-readable form. |
| Executive output layout | `executive_outputs.py` | `organize_executive_summary` and `ExecutiveOutputOptions` sort `output/executive_summary` files by type via `OutputOrganizer`. |
| HTML templates | `html_templates.py` | `shared_css`, `get_base_html_template`, `render_summary_cards`, and `render_table` supply the shared design-token/dark-mode CSS and reusable report HTML. |
| Log summaries | `log_analysis.py` | `generate_log_summary` tallies log-level counts and error/warning samples into a human-readable log report. |
| Run lessons | `run_lessons.py` | `collect_run_lessons` and `write_run_lessons` capture per-run pipeline lessons (`RunLesson`) to JSONL, Markdown, and next-run context files. |
+ | Interactive dashboards | `interactive_dashboard.py`, `_interactive_models.py`, `_interactive_html.py` | `InteractiveDashboard` builder API, the `Panel`/`Control`/`Invariant` data types, and page assembly for self-contained Plotly dashboards. See [Interactive simulation dashboard](#interactive-simulation-dashboard-interactive_dashboardpy). |
| Output organization | `output_organizer.py`, `output_statistics.py`, `page_grid.py`, `page_rendering.py` | Final report file layout and page grids. |
+
+ ## Interactive simulation dashboard (`interactive_dashboard.py`)
+
+ Project-agnostic builder for a single self-contained HTML page with Plotly
+ panels, live controls, invariants, and reproducibility metadata. The package is
+ split three ways: `_interactive_models.py` holds the `Panel`, `Control`, and
+ `Invariant` dataclasses; `_interactive_html.py` assembles the page
+ (`render_interactive_dashboard_html`, `PLOTLY_CDN`); `interactive_dashboard.py`
+ exposes the `InteractiveDashboard` builder API.
+
+ - Construct with `InteractiveDashboard(title, subtitle, project_name, repo_root)`.
+ - Feed data with `set_payload`, `set_hyperparameters`, `set_meta`, `add_table`,
+ `add_note`; the chained setters return `self`.
+ - Add views with `add_panel(Panel(...))` and controls with `add_slider`,
+ `add_dropdown`, `add_toggle`, or the generic `add_control`.
+ - Declare checks with `add_invariant(Invariant(name, actual, expected, tol))`;
+ `evaluate_invariants()` scores them and `render_invariants_text()` /
+ `render_summary_text()` render the plaintext companions.
+ - `write(html_path, json_path=None, txt_path=None, invariants_path=None)`
+ writes the artefacts and returns a dict of artefact name → resolved `Path`.
+
+ Boundaries: the builder does not run a simulation — callers pass in already
+ computed payloads. Invariant results are recorded as evaluated, never forced to
+ pass. The page embeds its own payload plus git revision and dirty state, so the
+ HTML stays self-contained and the run is traceable.
## Boundaries
- Reports consume existing artifacts; they do not run project analysis.
- Local readiness is not publication readiness. Network deposits, DOI state, and
public endpoints need explicit publishing checks.
- Avoid hard-coded project rosters; use public scope helpers or generated docs.
- Keep charts deterministic and compact. Put metric definitions in source data
or report prose, not hidden code comments.
- When a report quotes counts or coverage, cite generated facts or fresh command
output.
## Public Commands
```bash
uv run python -m infrastructure.reporting.evidence_graph build templates/template_code_project --json /tmp/evidence_graph.json
uv run python -m infrastructure.reporting.release_readiness --repo-root . --out output/release_readiness.md
uv run python scripts/runner/execute_multi_project.py --public-projects
```
## Tests
```bash
uv run pytest tests/infra_tests/reporting -q
```
For changes that touch project test execution, also run the relevant
`scripts/pipeline/stage_01_test.py` mode because `pipeline_test_runner.py` controls the
project output lock used by pipeline stages.
## Change Checklist
- Add tests for JSON/Markdown/HTML shape when public report schema changes.
- Keep release-readiness aggregation offline unless a command explicitly says it
performs network validation.
- Regenerate downstream report fixtures only through their producer commands.
- Run `git diff --check`; report markdown tables are easy to break with trailing
whitespace.
## See Also
- [`README.md`](README.md)
- [`../core/pipeline/AGENTS.md`](../core/pipeline/AGENTS.md)
- [`../validation/AGENTS.md`](../validation/AGENTS.md)