# Beffroi Reporting Beffroi Reporting is the **integration workspace** for the Beffroi diagnostics and reporting toolchain. It brings the complete environment together as Git submodules: ```text id="8efkt6" beffroi-reporting ├── win-diagnostics/ ├── beffroi-reports/ └── reportist/ ``` The target layout uses `diagnostics/`, `reports/`, and `reporter/` respectively. Renaming the current submodule paths is tracked in the migration roadmap. During migration, the previous implementations are also available under `references/` so developers and agents can inspect the complete old and new workflows from one workspace. The target pipeline is: ```text id="z3j03k" Windows ↓ win-diagnostics ↓ diagnostic.json ↓ beffroi-reports ↓ report.yaml ↓ reportist ↓ PDF ``` ## Getting started Clone the complete workspace with its submodules: ```bash id="0mzx8u" git clone --recursive cd beffroi-reporting ``` For an existing checkout: ```bash id="ihk4op" git submodule update --init --recursive ``` ## Run component checks On Linux/macOS with Bash, Git, Make, and `uv` available, run: ```bash make check ``` The same runner is used by Jenkins (`bash scripts/check-components.sh`). It creates separate Python 3.11 environments under `.venv/component-checks/` and synchronizes each component's pinned requirements. On first use, uv may download Python and dependencies, requiring network access. No system packages are changed. The runner prints tool versions and component revisions and stops on any failure. Current coverage includes the diagnostic and report contract suites, adapter preservation tests, and a synthetic diagnostic-to-report generation validated by both component tools. It does not verify diagnostic analysis or PDF output. Submodules must already be initialized with the command above. ## Push component commits and the workspace together After committing changes inside each component and committing their updated submodule pins in this repository, run from the macro repository: ```bash git push --recurse-submodules=on-demand ``` Git pushes the component commits needed by the macro commits before pushing the macro repository. If a required component push fails, the macro push stops. This uses each repository's configured remote/upstream; it does not commit files or push unrelated component branches. All current component `main` branches have an `origin/main` upstream. Unchanged reference submodules need no push. To make that behavior the local default for this checkout: ```bash git config push.recurseSubmodules on-demand ``` See the [Git push documentation](https://git-scm.com/docs/git-push#Documentation/git-push.txt---recurse-submodulescheckon-demandonlyno). ## Migration status 🚧 **Architecture migration in progress** [AGENTS-TASKS.md](AGENTS-TASKS.md) tracks completed work, remaining migration passes, acceptance criteria, and the next-pass handoff. [AGENTS.md](AGENTS.md) defines repository ownership and rules for agents working across the workspace. The first executable migration check is the [synthetic legacy baseline](docs/migration-baseline.md). It records diagnostic behavior and renders example PDFs before extraction. Version-1 [diagnostic validation](win-diagnostics/docs/diagnostic-contract.md) and [report validation](reportist/docs/report-contract.md) are now available independently in their component repositories. The new end-to-end pipeline remains in progress. ## License Root-level software and orchestration code is licensed under the **MIT License**. Internal Beffroi data and content remain proprietary where applicable; see `LICENSE-DATA.md`.