105 lines
7.5 KiB
Markdown
105 lines
7.5 KiB
Markdown
# Win Diagnostics migration tracker
|
||
|
||
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.
|
||
|
||
- [ ] WD1.1 Define `schemas/diagnostic.schema.json` with 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-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.
|