2.6 KiB
AGENT.md — Beffroi Reporting
Mission
Beffroi Reporting is an integration and orchestration repository.
It provides a convenient reproducible workspace combining:
win-diagnostics
beffroi-reports
reportist
It does NOT own their implementation.
Intended structure
diagnostics/ → win-diagnostics submodule
reports/ → beffroi-reports submodule
reporter/ → reportist submodule
scripts/
Makefile
README.md
.gitmodules
Dependency direction
This repository depends on the component repositories.
Component repositories MUST NOT depend on this repository.
Never introduce circular dependencies.
Submodules
Use Git submodules to pin known-compatible revisions.
Do not automatically follow remote branch HEAD.
A checkout of a historical integration commit should identify the exact versions of the tooling used at that point.
Bootstrap
Provide a simple bootstrap process.
For example:
git clone --recursive ...
./bootstrap.sh
Bootstrap should:
- initialize submodules;
- check dependencies;
- explain missing requirements;
- prepare the workspace where appropriate.
Do not silently make invasive system modifications.
Workflow
Aim for simple high-level operations.
Examples:
make collect
make analyse
make report INCIDENT=...
make render INCIDENT=...
make all INCIDENT=...
The exact interface should follow actual workflows rather than these examples mechanically.
Reproducibility
A pinned integration revision should provide enough information to recreate a historical report, subject to documented external/system dependencies.
When updating a submodule, commit the version change intentionally.
Scope
This repository may contain:
- orchestration;
- bootstrap scripts;
- dependency checks;
- Makefiles;
- integration tests;
- documentation.
It should NOT accumulate:
- diagnostic rules;
- Typst templates;
- historical reports;
- duplicated component code.
When substantial implementation appears here, determine which component actually owns it.
Testing
Provide at least one integration test using sanitized fixture data:
diagnostic fixture
↓
analysis
↓
report data
↓
Reportist
↓
PDF
This test verifies compatibility between pinned components.
Definition of success
A developer wanting the complete Beffroi reporting environment can run:
git clone --recursive <repository>
and obtain a coherent set of known-compatible tools and reports.
A developer wanting only one component should never need this repository.