beffroi-reporting/README.md

95 lines
2.8 KiB
Markdown

# 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 <repository-url>
cd beffroi-reporting
```
For an existing checkout:
```bash id="ihk4op"
git submodule update --init --recursive
```
## 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`.