beffroi-reporting/AGENTS.md

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


Implementation constraints

Production workflows use Make, POSIX-oriented shell, Typst, Rust for the publication helper, and PowerShell where Windows collection requires it. 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.