Add AGENTS.md
This commit is contained in:
parent
9cd921a9ee
commit
ae29dababd
|
|
@ -0,0 +1,146 @@
|
|||
# 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.
|
||||
Loading…
Reference in New Issue