159 lines
3.2 KiB
Markdown
159 lines
3.2 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.
|
|
|
|
---
|
|
|
|
## Implementation constraints
|
|
|
|
Production workflows use Make, POSIX-oriented shell, jq, PowerShell where
|
|
Windows collection requires it, and Typst. Python is allowed only under test
|
|
directories as a test harness or independent oracle; it must never be required
|
|
to bootstrap, analyse, adapt, validate, render, package, or publish a report.
|
|
|
|
Every Python test invocation must use an environment created by `uv venv` and
|
|
synchronized by `uv pip`. Do not invoke system Python or install packages with
|
|
`pip` directly. Keep Make targets as the public interface and shell scripts as
|
|
thin, inspectable orchestration.
|
|
|
|
## 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.
|