beffroi-reporting/AGENTS.md

146 lines
2.6 KiB
Markdown

# 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.