docs: remove agent instructions

This commit is contained in:
Dandaedre 2026-09-16 01:27:57 +02:00
parent e1ae8bb5df
commit 537f77f092
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
2 changed files with 0 additions and 395 deletions

215
AGENT.md
View File

@ -1,215 +0,0 @@
# 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
Production collection and analysis must not require Python. Use PowerShell for
native Windows collection, shell and Typst for portable offline processing, and
Make for the public interface. Python may exist only in `tests/`, must run
through a uv-managed virtual environment, and must not be called by production.
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.

View File

@ -1,180 +0,0 @@
# Win Diagnostics migration tracker
## Pass 5 — Runtime without Python
- [x] WD5.1 Port offline normalization and rule analysis to shell and Typst with identical deterministic fixtures.
- [x] WD5.2 Port diagnostic validation and evidence verification to shell and Typst.
- [x] WD5.3 Provide Make targets for collection, analysis, validation, and uv-managed tests.
- [x] WD5.4 Remove production Python files and prove tests are the only Python consumers.
Follow [AGENT.md](AGENT.md). This repository owns collection, normalization,
generic diagnostic analysis, evidence correlation, and structured results.
Report layout, branding, historical incidents, and organisational conclusions
belong elsewhere. Do not introduce Typst, Reportist, or macro-repository dependencies.
## Tracking rules
`[x]` means completed and verified; `[ ]` means work remains. Keep task IDs
stable. After each pass, update this checklist and append a handoff recording
changes, validation commands/results, limitations, and the next task. Check off
implementation only after its acceptance criteria pass.
This roadmap must remain usable from a standalone checkout. Legacy repositories
are migration sources, not runtime dependencies. Coordinate public contracts
with consumers; keep implementation and tests in their owning repository.
## Initial planning baseline — 2026-09-15
Only instructions, README, license, ignore rules, and Jenkins scaffolding are
tracked. No collector, schema, analysis engine, or fixture tests have been migrated.
At initial planning Jenkins checked `AGENT.md` while instructions used `AGENTS.md`.
The checkout now uses `AGENT.md`; see the latest handoff for current status.
## Pass 0 — Inventory and baselines
- [x] WD0.1 Read repository instructions and inspect tracked files, README, and Jenkins scaffold.
- [x] WD0.2 Create this phased tracker and link it from the README using the actual instruction filename.
- [x] WD0.3 Inventory the legacy `WindowsMaintenanceReport.ps1` collection functions and output modes; record source revision, licenses, supported Windows/PowerShell versions, privileges, and dependencies.
- [x] WD0.4 Classify the legacy renderer's `modules/diagnostics-normalize.typ`, diagnostic rules, and watchlist entries. Assign generic normalization/analysis here; leave incident-specific interpretation and report prose to beffroi-reports.
- [x] WD0.5 Review and sanitize legacy fixtures before reuse; establish expected observations, findings, severity, confidence, and incomplete-collection behavior for a representative slice.
Exit: the selected slice has explicit ownership, source provenance, and repeatable
expected results. Existing legacy fixtures are not assumed sanitized.
## Pass 1 — Diagnostic contract
Depends on Pass 0 for the selected slice.
- [x] WD1.1 Define `schemas/diagnostic.schema.json` with explicit version, metadata, system, collection status, observations, findings, and warnings; adapt fields to actual evidence.
- [x] WD1.2 Define stable finding IDs, severity/confidence semantics, evidence references, and how raw evidence is retained. Missing, skipped, and failed checks must not imply health.
- [x] WD1.3 Document mapping from legacy capture schemas 1 and 2, including unsupported versions and information that cannot be recovered.
- [x] WD1.4 Define independent collection/offline-analysis CLI contracts: input/output paths, errors, exit codes, dependencies, and compatibility policy.
- [x] WD1.5 Add synthetic valid/invalid schema examples and validation tests; document the interface for downstream report adapters without importing their implementation.
Exit: a consumer can understand and validate diagnostic output using a documented
public contract, independently of collection internals.
## Pass 2 — Collection and normalization
Depends on Pass 1.
- [ ] WD2.1 Migrate collection incrementally, preserving Compact/Mid/Full behavior and explicit administrator-only/unavailable checks; do not silently modify the system.
- [ ] WD2.2 Separate structured evidence from console presentation; retain raw records where practical and avoid machine-specific absolute paths.
- [x] WD2.3 Implement offline normalization of stored captures without Typst, live Windows access, or sibling repositories.
- [x] WD2.4 Test supported capture versions/modes, malformed input, missing sections, partial collection, and preservation of evidence references against the baseline.
Exit: supported evidence can be collected and stored captures normalized through
the public interface, with collection limitations documented.
## Pass 3 — Generic analysis
Depends on normalized evidence and the diagnostic contract.
- [x] WD3.1 Port reusable rules and watchlist matching with traceable evidence; keep investigation-specific conclusions and organisational recommendations outside this engine.
- [x] WD3.2 Preserve and test event grouping, deduplication, correlation, unknown-event behavior, collection completeness, severity, and confidence.
- [x] WD3.3 Make time-dependent analysis repeatable using a defined reference time; document intentional differences from legacy behavior.
- [x] WD3.4 Emit schema-valid `diagnostic.json`; verify every finding's evidence reference resolves and raw observations remain available.
- [x] WD3.5 Run sanitized regression fixtures for known diagnostic situations without the original machine; record exact commands and results.
Exit: offline analysis produces deterministic, evidence-backed diagnostic output
without any rendering or report-content dependency.
## Pass 4 — Standalone validation and handoff
Depends on the working diagnostic slice.
- [x] WD4.1 Correct Jenkins' instruction-file check; enable schema, fixture, and analysis checks as they become available, with accurate coverage reporting.
- [ ] WD4.2 Validate native collection on supported Windows/PowerShell environments; clearly document anything not tested by the non-Windows Jenkins agent.
- [x] WD4.3 Document installation, collection, offline analysis, output schema, privacy, dependencies, and troubleshooting from a fresh standalone clone.
- [x] WD4.4 Verify the standalone clone needs neither Reportist, beffroi-reports, the macro repository, nor legacy sources; audit fixtures for identifying data.
- [x] WD4.5 Record a verified component revision and public commands for the integration repository's sanitized pipeline test; keep integration orchestration there.
Exit: a fresh clone collects/analyses supported Windows evidence and produces a
valid diagnostic result independently of reporting tools.
## Handoff log
### 2026-09-16 — Reliability deduplication and standalone handoff
- Completed WD3.2 and WD4.3–WD4.5. Reviewed warning/critical reliability records
supplement bounded event logs while same-second/provider/ID/message duplicates
are omitted. Every retained record keeps its raw JSON pointer.
- Documented standalone installation, analysis, validation, privacy,
troubleshooting, and native-collection limitations. Runtime requires no sibling,
macro, renderer, reports, or legacy checkout.
- Native collection remains WD2.1–WD2.2/WD4.2 and requires a supported Windows
PowerShell worker; it is not claimed from Linux fixture validation.
### 2026-09-15 — Complete event and watchlist catalog
- Completed WD3.1 and advanced WD3.2 for the selected event-analysis scope: all 53 event rules
and seven candidate watchlist entries are migrated with raw observation links.
Remediation/action text remains outside the diagnostic engine.
- Watchlist matching preserves exact case-insensitive identity, driver basename,
version, enabled-state, prerequisite, and repeated-event gates. Candidate wording
avoids inferring vulnerability exploitation, active conflict, or root cause.
- Added catalog fingerprint, six-candidate fixture, negative gate, and positive
Intel event-correlation tests. Unknown events remain grouped and unanalysed;
incomplete collection stays visible and caps candidate confidence.
- Validation: all 25 diagnostic tests and the complete integration pipeline pass.
Native collection and broader structured hardware/health rules remain open.
- Next: implement reliability-history deduplication and non-event diagnostic checks,
then validate native collection on Windows before claiming full behavior parity.
### 2026-09-15 — First event-rule migration batch
- Advanced WD3.1 with 15 reviewed rules covering bugchecks, dump generation,
storage/TPM, services, NDIS, application failures, Windows Update, MSI, shadow
copies, DCOM and unexpected shutdown. The remaining 38 rules and seven watchlist
matchers keep WD3.1 open.
- Added optional diagnostic v1 `age_days` and `relevance_weight` fields so fading
rules retain the legacy 7-to-90-day relevance curve without changing technical
confidence. Reference time remains explicit and partial captures still cap
confidence independently.
- Validation: 21 diagnostic tests pass, including an exact provider/ID/severity/
confidence catalog assertion and old-event fading. No remediation text entered
the diagnostic engine.
- Next: migrate the next event-rule batch, then implement watchlist matching and
explicit correlation coverage under WD3.2.
### 2026-09-15 — First offline analyser slice
- Completed WD1.4, WD2.3–WD2.4, WD3.3–WD3.5 and WD4.1 for the bounded first
slice. `tools/analyse.py` accepts legacy schemas 1/2, normalizes section status,
preserves raw event values/pointers, groups duplicate events and emits validated
diagnostic v1 JSON with explicit reference time and source hash.
- Migrated the reviewed Service Control Manager Event 7000 rule. Unmatched events
are retained as `unanalysed` with zero confidence; partial collection caps known
rule confidence at 50. The other 52 rules and watchlist matching remain WD3.1.
- Added nine analysis tests across all five sanitized fixtures, deterministic
output, evidence links, malformed/missing input, incomplete/unsupported states,
and outside-CWD CLI use.
- Validation: 19 component tests pass on Python 3.11.14. The integration workspace
runs raw fixture → analyser → adapter → Reportist → PDF. Native Windows collection
and full legacy-rule parity remain untested.
- Next: migrate remaining generic rules in reviewed groups and implement watchlist
matching/correlation before native collector work.
### 2026-09-15 — Planning pass
- Completed WD0.1–WD0.2; added roadmap and corrected README navigation.
- Validation: documentation links, task IDs, and whitespace checked; no diagnostic implementation tests exist or were run.
- Open: full source inventory, sanitization review, and behavioral baselines; Jenkins filename mismatch is tracked in WD4.1.
- Next: WD0.3–WD0.5, then the smallest useful WD1 contract slice.
### 2026-09-15 — Inventory and executable baseline pass
- Completed WD0.3–WD0.5 for the initial offline slice: collector/function inventory, 53 event-rule and seven watchlist ownership decisions, five reviewed synthetic fixtures, and expected legacy snapshots.
- Evidence: [migration inventory](docs/migration-inventory.md), `tests/fixtures/legacy/`, `tests/legacy-baseline.json`.
- Validation: macro command `python3 scripts/check-legacy-baseline.py --output /tmp/beffroi-baseline-verified` passed all five snapshots and semantic assertions. This runs pinned legacy analysis, not a migrated engine.
- Environment: Typst 0.15.1; PowerShell unavailable, so native Windows collection remains untested. Advisory URLs were not revalidated.
- Preserved concurrent checkout updates: instructions are now `AGENT.md`; README/tracker links now match. Jenkins file-presence checks pass locally; WD4.1 still requires future schema/analysis CI.
- Next: WD1 schema/examples, then one offline normalization slice. Full diagnostic rules and Windows validation remain open.
### 2026-09-15 — Versioned contract pass
- Completed WD1.1–WD1.3 and WD1.5: diagnostic v1 schema, synthetic artifact, standalone validator, evidence verification, version/legacy mapping, and pinned dependencies.
- Evidence: [diagnostic contract](docs/diagnostic-contract.md), `schemas/diagnostic.schema.json`, `tools/validate.py`, `examples/diagnostic.json`, `tests/test_contract.py`.
- Validation: 10 unittest cases (plus invalid-input subcases) passed on Python 3.11 in an isolated component copy with only its own requirements. Earlier core tests also passed on Python 3.14. Includes artifact checksums, JSON Pointer/value matching, dangling/duplicate IDs, invalid formats, partial coverage and path containment.
- Jenkins now runs contract tests in an isolated environment; pipeline execution itself was not performed here. This is contract validation, not a migrated analysis engine.
- Next: WD1.4 precise collection/offline-analysis commands and WD2 first normalization slice. Preserve evidence and the existing synthetic legacy snapshots. Native Windows collection remains untested.