beffroi-reporting/AGENTS.md

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.