diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..382e27f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,210 @@ +# AGENT.md — Win Diagnostics + +## Mission + +Win Diagnostics collects and analyses Windows diagnostic information. + +Its pipeline is: + + Windows system + ↓ + collect + ↓ + normalize + ↓ + analyse + ↓ + diagnostic.json + +The structured diagnostic result is the primary output. + +This project does NOT generate corporate reports or PDFs. + +--- + +## Migration source + +The existing `WinDiagnostics` repository is the primary migration source. + +Migrate progressively rather than copying the entire repository. + +Before migrating a component, determine whether it is: + +- collection logic; +- normalization logic; +- generic diagnostic analysis; +- historical evidence; +- investigation-specific analysis; +- report-generation logic. + +Only the first three belong here. + +Historical evidence and investigation-specific material will eventually +move to `beffroi-reports`. + +--- + +## Responsibilities + +Win Diagnostics owns: + +- Windows evidence collection; +- event extraction; +- normalization; +- diagnostic rules; +- technical analysis; +- evidence correlation; +- confidence/severity classification; +- machine-readable diagnostic output. + +--- + +## Non-goals + +Win Diagnostics does NOT own: + +- PDF generation; +- Typst; +- corporate branding; +- report layout; +- historical incident management; +- executive summaries; +- organisational recommendations. + +Do not add dependencies on Reportist. + +--- + +## Diagnostic format + +Define a versioned structured diagnostic format. + +Prefer JSON for machine-generated output. + +Conceptually: + + { + "schema_version": 1, + "metadata": {}, + "system": {}, + "collection": {}, + "observations": [], + "findings": [], + "warnings": [] + } + +Findings should preferably contain: + + id + severity + confidence + title + description + evidence + +Adapt this structure where existing diagnostic data requires it. + +--- + +## Evidence + +Preserve raw evidence wherever practical. + +A diagnostic conclusion must be traceable back to observations. + +Do not replace precise machine evidence with prose summaries when the +underlying structured information can reasonably be retained. + +--- + +## Schemas + +Prefer: + + schemas/diagnostic.schema.json + +Treat the diagnostic schema as an interface consumed by other tools. + +Changes to internal collectors should not require downstream changes when +the schema remains compatible. + +--- + +## Privacy + +Example and test fixtures must be sanitized. + +Avoid committing unnecessarily identifying: + +- usernames; +- hostnames; +- serial numbers; +- account identifiers; +- network identifiers. + +Real investigation evidence belongs in the appropriate private reporting +repository rather than generic fixtures. + +--- + +## Architecture + +Prefer conceptual separation between: + + collection + normalization + analysis + schemas + +Do not force directory boundaries where they make implementation worse. + +--- + +## Testing + +Maintain sanitized fixtures representing known diagnostic situations. + +Analysis should be testable against stored fixtures without requiring +access to the original machine. + +Regression tests are particularly valuable for diagnostic rules. + +--- + +## Output + +The end of a successful diagnostic run should be a documented structured +artifact such as: + + diagnostic.json + +Human-readable console summaries are useful but are not the canonical +integration interface. + +--- + +## Development principles + +Prefer: + +- PowerShell for native Windows collection where appropriate; +- structured output; +- deterministic analysis; +- explicit evidence references; +- testable rules; +- minimal dependencies. + +Avoid: + +- parsing presentation-oriented output when structured APIs exist; +- report-specific prose; +- renderer dependencies; +- absolute machine-specific paths. + +--- + +## Definition of success + +A fresh clone can collect/analyse supported Windows diagnostic information +and produce a valid structured diagnostic result without Reportist or any +Beffroi reporting repository installed. \ No newline at end of file