# 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 and obtain a coherent set of known-compatible tools and reports. A developer wanting only one component should never need this repository.