diff --git a/AGENT.md b/AGENT.md deleted file mode 100644 index 8c320c1..0000000 --- a/AGENT.md +++ /dev/null @@ -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. diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md deleted file mode 100644 index 9f3307a..0000000 --- a/AGENTS-TASKS.md +++ /dev/null @@ -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.