13 KiB
Win Diagnostics migration tracker
Pass 5 — Runtime without Python
- WD5.1 Port offline normalization and rule analysis to shell and jq with identical deterministic fixtures.
- WD5.2 Port diagnostic validation and evidence verification to shell and jq.
- WD5.3 Provide Make targets for collection, analysis, validation, and uv-managed tests.
- WD5.4 Remove production Python files and prove tests are the only Python consumers.
Follow 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
- WD0.1 Read repository instructions and inspect tracked files, README, and Jenkins scaffold.
- WD0.2 Create this phased tracker and link it from the README using the actual instruction filename.
- WD0.3 Inventory the legacy
WindowsMaintenanceReport.ps1collection functions and output modes; record source revision, licenses, supported Windows/PowerShell versions, privileges, and dependencies. - 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. - 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.
- WD1.1 Define
schemas/diagnostic.schema.jsonwith explicit version, metadata, system, collection status, observations, findings, and warnings; adapt fields to actual evidence. - 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.
- WD1.3 Document mapping from legacy capture schemas 1 and 2, including unsupported versions and information that cannot be recovered.
- WD1.4 Define independent collection/offline-analysis CLI contracts: input/output paths, errors, exit codes, dependencies, and compatibility policy.
- 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.
- WD2.3 Implement offline normalization of stored captures without Typst, live Windows access, or sibling repositories.
- 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.
- WD3.1 Port reusable rules and watchlist matching with traceable evidence; keep investigation-specific conclusions and organisational recommendations outside this engine.
- WD3.2 Preserve and test event grouping, deduplication, correlation, unknown-event behavior, collection completeness, severity, and confidence.
- WD3.3 Make time-dependent analysis repeatable using a defined reference time; document intentional differences from legacy behavior.
- WD3.4 Emit schema-valid
diagnostic.json; verify every finding's evidence reference resolves and raw observations remain available. - 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.
- 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.
- WD4.3 Document installation, collection, offline analysis, output schema, privacy, dependencies, and troubleshooting from a fresh standalone clone.
- WD4.4 Verify the standalone clone needs neither Reportist, beffroi-reports, the macro repository, nor legacy sources; audit fixtures for identifying data.
- 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_daysandrelevance_weightfields 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.pyaccepts 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
unanalysedwith 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,
tests/fixtures/legacy/,tests/legacy-baseline.json. - Validation: macro command
python3 scripts/check-legacy-baseline.py --output /tmp/beffroi-baseline-verifiedpassed 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,
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.