23 KiB
Reporting migration tracker
How to use this tracker
This is the cross-repository handoff for a migration in several passes. Follow
AGENTS.md and the instructions in each component before editing it.
[x] means completed and verified; [ ] means work remains. Keep task IDs stable.
At the end of each pass, update the checkboxes and append a handoff with changed
files/revisions, validation results, remaining limitations, and the next task.
Do not mark implementation complete based on documentation or CI scaffolding.
Component implementation belongs in its own repository. Commit component changes there, then intentionally update the integration repository's gitlinks once the combination has been verified. Do not follow remote HEAD automatically.
Initial baseline — 2026-09-15
Component task details and handoffs are maintained in:
Keep cross-repository milestones here consistent with those component checklists.
- The three destination components contain instructions, READMEs, and Jenkins scaffolding; the new pipeline is not implemented yet.
- Current submodule paths are
win-diagnostics/,beffroi-reports/, andreportist/. The integration instructions targetdiagnostics/,reports/, andreporter/; the path migration remains a separate task. - Legacy sources are pinned under
references/WinDiagnostics/andreferences/typist_reporter/(the latter spelling is the actual local path). - Root CI initializes pinned submodules and checks workspace files. Component validation, integration rendering, packaging, and publication remain TODOs.
- The legacy renderer combines normalization, diagnostic rules, report content, organisation branding, and PDF layout. Extraction needs behavior checks, not just file moves. Existing fixtures still require a sanitization review.
Ownership map
| Source or responsibility | Destination | Treatment |
|---|---|---|
references/WinDiagnostics/WindowsMaintenanceReport.ps1 |
win-diagnostics | Extract collection, normalization, and generic analysis progressively. |
Legacy modules/diagnostics-normalize.typ |
win-diagnostics / beffroi-reports | Move generic evidence interpretation to diagnostics; move report assembly and incident interpretation to reports. Remove the runtime Typst dependency from diagnostics. |
Legacy config/diagnostics-rules.yaml and config/diagnostics-watchlist.yaml |
win-diagnostics / beffroi-reports | Classify individual rules: reusable technical rules versus investigation-specific policy and recommendations. |
Legacy report.typ, modules/model.typ, modules/diagnostics-model.typ, rendering scripts |
reportist / beffroi-reports | Extract generic layout and rendering into Reportist; supply domain labels and report content as input. |
Legacy themes and assets/ |
reportist / beffroi-reports | Keep generic presentation defaults in Reportist; move Beffroi identity and assets to reports. |
Legacy reports/, diagnostics/, investigation notes |
beffroi-reports | Preserve private evidence, chronology, human analysis, and provenance. |
| Legacy fixtures and checks | Relevant component tests / integration tests | Review sanitization; assign tests by behavior and retain a complete pipeline fixture. |
| Legacy packaging and publication | beffroi-reporting | Introduce orchestration only after rendering compatibility is demonstrated. |
Pass 0 — Inventory and migration plan
- P0.1 Read root and all three component instruction files.
- P0.2 Inspect tracked layout, submodule pins, READMEs, root CI, and legacy entry points.
- P0.3 Record initial ownership boundaries, coupling, and phased acceptance criteria here.
- P0.4 Link this tracker and the actual root instruction file from the README; distinguish current and target paths.
- P0.5 Complete a file/function-level inventory before extraction, including rule/watchlist classification, report fields, CLI behavior, licenses, fonts, and external dependencies. Record source revisions and destination decisions without copying private evidence into this tracker.
- P0.6 Establish reproducible legacy baselines using reviewed synthetic/sanitized fixtures: expected findings, collection completeness, report structure, and representative PDFs. Record exact commands, tool versions, and failures.
Exit: every behavior in the first extraction slice has an owner and an observable baseline. The first synthetic baseline is complete; full inventory and private incident evidence mapping remain open under P0.5 and component tasks.
Pass 1 — Define contracts and compatibility
Depends on P0.5–P0.6 for the selected slice.
- P1.1 win-diagnostics: define
schemas/diagnostic.schema.json, schema versioning, metadata, collection status, observations, findings, warnings, and evidence references. Distinguish missing/failed checks from healthy results. - P1.2 win-diagnostics: document how legacy capture schemas 1 and 2 map to the new diagnostic artifact, including unsupported versions and retained raw evidence.
- P1.3 reportist: define
schema/report.schema.jsonand versioned YAML/JSON input, required/optional fields, generic content blocks, external branding/assets, and actionable validation errors. Map useful legacy report fields explicitly. - P1.4 beffroi-reports: define the adapter mapping and incident structure; distinguish machine findings, human analysis, and recipient-facing conclusions. Specify how regeneration preserves human edits.
- P1.5 components: document independent CLI input/output paths, exit codes, dependencies, and schema compatibility. Add synthetic valid/invalid contract examples and validation checks in their owning repositories.
Exit: producer and consumer agree on explicit artifacts without requiring access to one another's implementation or to the macro repository.
Pass 2 — Extract standalone diagnostics
Depends on the diagnostic contract and legacy baselines. Work in win-diagnostics.
- P2.1 Migrate the collector incrementally, retaining supported collection modes, raw evidence, and explicit unavailable/admin-only check status; avoid invasive system changes.
- P2.2 Implement offline normalization of stored legacy captures without Typst or Reportist.
- P2.3 Move generic diagnostic rules, evidence correlation, severity/confidence, deduplication, and time-dependent behavior out of the renderer. Use a defined reference time for repeatable analysis.
- P2.4 Emit schema-valid
diagnostic.jsonwith traceable observations and findings; keep report prose and organisational recommendations out of the diagnostic engine. - P2.5 Add sanitized regression coverage for supported capture versions/modes, partial collection, unknown events, rule matches, and evidence references; compare against P0.6 and explain intentional changes.
- P2.6 Verify a standalone clone can analyse fixtures without sibling repositories; validate collection on supported Windows/PowerShell environments and document any untested platform behavior.
Exit: the component independently produces a valid diagnostic artifact, with verified offline analysis and clearly documented Windows collection support.
Pass 3 — Extract a generic renderer
Depends on the report contract and legacy visual baselines; can proceed separately from Pass 2 once its contract is established. Work in reportist.
- P3.1 Extract reusable Typst layout/components and preserve the sober visual style; replace hard-coded identity, machine labels, diagnostic interpretation, and default Beffroi assets with generic inputs.
- P3.2 Implement input validation and a simple YAML/JSON-to-PDF CLI with explicit output paths and clear errors.
- P3.3 Provide a synthetic example and replaceable branding; document asset resolution, fonts, Typst version, and installation requirements.
- P3.4 Test valid rendering, invalid input, missing optional fields, and alternate branding; inspect representative PDFs for layout regressions.
- P3.5 Verify the example renders in a standalone checkout without diagnostics, reports, macro, or legacy repositories.
Exit: Reportist renders documented generic report input independently and contains no diagnostic engine, real incidents, or hard-coded Beffroi identity.
Pass 4 — Build the report adapter and migrate one incident
Depends on working diagnostic and renderer slices. Work in beffroi-reports.
- P4.1 Implement the diagnostic-to-report adapter against public contracts; generate a reviewable draft and verify reruns preserve human conclusions, recommendations, and contextual notes.
- P4.2 Move Beffroi branding/configuration and investigation-specific policy to this repository, supplying them through Reportist's public interface.
- P4.3 Migrate one representative incident with evidence, analysis, report input, chronology, source provenance, and relevant component/schema versions.
- P4.4 Choose and document whether PDFs are archived deliverables or reproducible uncommitted artifacts; document regeneration and external dependencies.
- P4.5 Compare the migrated incident's findings, content, evidence links, and rendered PDF with its legacy baseline. Record differences and verify source preservation before migrating further incidents.
- P4.6 Test adapter errors and preservation of human edits using synthetic data; verify operation with independently installed tools and no macro-repository dependency.
Exit: one incident can be understood and its report recreated without the original machine; automated draft content remains distinct from reviewed analysis.
Pass 5 — Wire the reproducible integration workspace
Depends on a working end-to-end slice from Passes 2–4. Work in beffroi-reporting.
- P5.1 Align submodule paths with
diagnostics/,reports/,reporter/; update.gitmodules, documentation, scripts, and CI together, preserving pinned revisions and local work. - P5.2 Add bootstrap to initialize pinned submodules, check actual tool/platform dependencies, explain missing requirements, and prepare workspace directories without silent system modifications.
- P5.3 Add high-level workflow commands based on the component CLIs for collection, offline analysis, draft report generation, rendering, and a complete incident run. Keep implementation in components.
- P5.4 Add an integration test: sanitized capture → analysis → diagnostic artifact → report adapter → report input → Reportist → PDF. Validate schemas, expected evidence/findings, and PDF output; use isolated temporary outputs.
- P5.5 Invoke component checks and the integration test from Jenkins; report actual validation coverage, tool versions, and artifacts accurately.
- Component contract suites are wired through
make checkand Jenkins; the diagnostic-to-report slice is now included, while analysis, PDF rendering, and the complete end-to-end integration test remain pending. - P5.6 Pin the tested component commits intentionally and document external dependencies plus clean-checkout reproduction commands; verify
git clone --recursivefollowed by bootstrap and integration testing.
Exit: a pinned integration revision runs the sanitized pipeline reproducibly, subject to documented system dependencies, while each component stays standalone.
Pass 6 — Migrate remaining history and retire legacy coupling
Depends on the verified integrated slice.
- P6.1 beffroi-reports: migrate remaining incidents in reviewable batches, retaining original evidence, report content, chronology, and source-to-destination records; verify each batch before retiring originals.
- P6.2 all components: audit for legacy paths, duplicated implementation, private generic fixtures, hard-coded branding, and reverse/circular dependencies; close remaining compatibility gaps.
- P6.3 integration: determine whether encrypted packaging is still required; if retained, migrate and test it using configured secrets and sanitized outputs after the new pipeline works.
- P6.4 integration: compare generated deliverables with existing production reports before enabling publication, as required by the current Jenkinsfile. Document destination, credentials, and recovery behavior.
- P6.5 integration: remove runtime reliance on
references/; retain source commit/provenance records and verified historical access before intentionally retiring reference submodules. - P6.6 all repositories: update usage/migration documentation, resolve stale instruction/license links, and run standalone component plus clean recursive-checkout integration verification.
Exit: the complete environment contains known-compatible components; historical reports remain understandable/recreatable and individual tools need no macro repo.
Pass handoff log
2026-09-15 — First diagnostic rule batch
- Advanced P2.3 / WD3.1 from one to 15 reviewed technical event rules. Added schema-supported age/relevance metadata for legacy fading behavior while keeping remediation outside win-diagnostics. Unmatched events remain unanalysed.
- Validation: 21 diagnostic tests assert the exact migrated catalog, evidence grouping, confidence caps and deterministic age weighting. The remaining 38 event rules and seven watchlist entries keep P2.3 open.
- Next: migrate the remaining event rules in reviewable batches, then implement watchlist/correlation behavior before claiming rule-engine parity.
2026-09-15 — First complete sanitized pipeline
- Completed P2.2, P2.4–P2.5 and P5.4–P5.5 for the first bounded analyser slice.
Root
make checknow runs sanitized raw capture → offline analysis → validated diagnostic → immutable branded report draft → Reportist → PDF in a temporary directory, asserting the expected Event 7000 finding and evidence ID. - Win Diagnostics supports legacy capture schemas 1/2 and one reviewed event rule; unmatched events remain explicitly unanalysed. P2.3 remains open for the other 52 rules, watchlist matching and correlation. Native collection remains P2.1.
- Validation: 19 diagnostic, 15 Reportist and 20 adapter tests pass with Python 3.11.14 and Typst 0.15.1; the integrated PDF has a valid signature. Jenkins itself was not executed.
- Next: migrate remaining diagnostic rules in reviewed batches, then add high-level workflow/bootstrap commands and clean-checkout verification.
2026-09-15 — First generic PDF rendering slice
- Completed Reportist RT1.5, RT2.1–RT2.4 and RT3.1–RT3.3 with a generic validated
YAML/JSON-to-PDF CLI, neutral defaults, replaceable branding and safe asset
staging. Root
make checknow renders the adapter's branded synthetic draft. - Validation: eight Reportist contract and seven rendering tests pass with Typst 0.15.1; the integration path produces a PDF signature after both schemas pass. Diagnostic analysis is still absent, so P5.4/P5.5 remain open.
- Next: visual/pagination comparison, then implement offline diagnostic analysis to connect raw capture input to this now-working adapter/renderer chain.
2026-09-15 — Beffroi branding adapter slice
- Migrated the two legacy Beffroi logos and three presentation palettes into the reports component. Adapter generations now snapshot selected branding and its logo, while synthetic alternate branding verifies the renderer contract remains replaceable rather than hard-coded.
- Validation: logo hashes match the pinned legacy sources; 15 standalone adapter tests and the owner-validator integration cases pass. BR2.3 remains open until first-incident policy is migrated; root pipeline milestones remain open.
- Next: standalone validator discovery (BR2.5), then diagnostic analysis and Reportist rendering slices needed for the complete integration test.
2026-09-15 — Adapter negative-path coverage
- Completed reports task BR2.4 with standalone preservation tests and integration
cases against both owning validators. Root
make checknow covers malformed and unsupported diagnostics, invalid report output, evidence/path failures, regeneration conflicts and atomic publication races using synthetic data. - Added adapter tests to the reports component Jenkinsfile; cross-component cases remain owned by this integration workspace. Jenkins itself was not run.
- Validation: 10 diagnostic contract, eight Reportist contract and 16 adapter tests pass. P5.4/P5.5 remain open until analysis and PDF rendering are present.
- Next: reports branding/tool discovery, then the first diagnostic analyser and generic Reportist rendering slices.
2026-09-15 — First diagnostic-to-report slice
- Completed reports tasks BR2.1–BR2.2 with an immutable adapter generation,
evidence snapshots, validator delegation, hash-based conflict detection and
atomic Linux publication. Updated
make checkto execute its six preservation tests and a real synthetic generation through both pinned validators. - Validation: 10 diagnostic, eight Reportist and six adapter tests pass; the generated draft validates as Reportist v1. Analysis and PDF output remain out of scope for this slice, so P5.4/P5.5 remain open.
- Next: expand adapter error coverage and branding, implement the first offline diagnostic analysis and generic renderer slices, then connect PDF integration.
2026-09-15 — Adapter regeneration policy
- Completed P1.4 / BR1.4 as a specification in the reports component. Generated drafts use immutable directories with exact evidence snapshots and ownership hashes; linked regeneration detects edits and never replaces reviewed sources.
- Defined planned CLI inputs, conflict recovery, publication failure behavior and synthetic acceptance cases. Implementation and preservation tests remain open.
- Validation: checked the contract against existing diagnostic evidence-root handling and Reportist schema boundaries; whitespace checks passed.
- The reports component revision and integration gitlink are committed together after validation so the regeneration policy remains reproducibly pinned.
- Next: implement the adapter and preservation tests in beffroi-reports, and finish collection/analysis/render CLI contracts under P1.5.
2026-09-15 — Root component-check orchestration
- Advanced the component-check portion of P5.5 with
scripts/check-components.sh,make check, and a Jenkins stage using the same runner. P5.5 remains open until the complete sanitized pipeline exists and runs in CI. - Each component uses its own Python 3.11 environment and pinned requirements; the runner prints uv/Python versions and checked-out revisions. No component implementation or gitlink changed.
- Validation:
make checkpassed all 10 diagnostic and eight report contract tests with Python 3.11.14 and uv 0.12.13. Jenkins itself was not executed. - Documented setup, dependency downloads, isolated environments, and coverage.
- Next: finish the CLI contracts and draft regeneration policy, then implement diagnostic, rendering, and adapter slices before the full integration test.
2026-09-15 — Initial planning pass
- Completed: P0.1–P0.4. Added this tracker and corrected root README navigation/layout descriptions.
- Inspected: all component instructions, repository inventory, root CI, component READMEs, legacy documentation, and selected normalization/layout entry points.
- Validation: checked submodule status against pinned gitlinks and reviewed the documentation diff. No collector, renderer, or integration execution was performed.
- Limitations: ownership map is preliminary; legacy fixture sanitization, full behavior inventory, and baseline PDF generation remain open. No component implementation or submodule pins changed.
- Next pass: P0.5–P0.6, then define P1 contracts for a small representative slice before porting implementation.
2026-09-15 — Component planning pass
- Added standalone phased trackers and README navigation in all three destination components; linked their trackers above.
- Recorded existing component CI instruction/license filename discrepancies as pending tasks. Reference repositories were not changed.
- Validation: checked new documentation links, unique task IDs, checkbox syntax, and whitespace. No runtime implementation changed or pipeline tests ran.
- Commit handoff: component documentation commits are pinned by the enclosing integration commit; use its gitlinks to identify the exact revisions.
- Next: complete the source inventories and sanitized baselines in each component, coordinated by P0.5–P0.6. Implementation milestones remain unchecked.
2026-09-15 — Inventory and executable baseline pass
- Completed P0.6 for five synthetic diagnostic captures and two synthetic report examples; added
scripts/check-legacy-baseline.pyand reproduction instructions. - Component inventories classify collector/normalizer functions, 53 event rules, seven watchlist entries, generic layout/fields, and private source ownership. First contract decisions are drafts, not implemented schemas.
- Validation: five expected snapshots, seven rendered PDFs with extracted titles, and three invalid-input checks passed with Typst 0.15.1. First-page visual review covered technical and Compact reports. Component CI file-presence checks passed locally; Jenkins itself was not run.
- Preserved concurrent component checkout updates that renamed instructions to
AGENT.mdand corrected reports CI license paths. References remain unchanged. - Limits: no native Windows collection (PowerShell unavailable), migrated engine/renderer/adapter, private historical rendering, full pagination review, or advisory revalidation. P0.5 remains open for the remaining detailed historical/packaging inventory.
- Next: implement WD1/RT1 versioned schemas and synthetic validation examples; finish BR0.5 claim/evidence mapping before moving private incidents.
2026-09-15 — Versioned contract pass and push workflow
- Completed P1.1–P1.3: two independent v1 schemas/validators, synthetic examples, invalid-input tests, evidence-reference validation, documented compatibility, and pinned dependency files.
- Added concrete report-adapter mapping and incident/provenance layout. P1.4 remains open for exact draft ownership/conflict/recovery behavior; P1.5 remains open for collection/analysis/render command contracts beyond the implemented validators.
- Documented
git push --recurse-submodules=on-demand; verified current branches have upstreams. No push or local Git configuration change was performed. - Validation: 10 diagnostic and eight report unittest cases pass independently on Python 3.11; initial core suites also passed on Python 3.14. Component copies run without macro, sibling or reference repositories. CI now invokes those tests; Jenkins itself was not executed.
- Limits: no collector/analyzer, generic renderer, adapter, full pipeline, or private historical baseline is claimed. Existing reference sources and legacy fixtures remain unchanged.
- Next: finish executable collection/analysis/render CLI contracts and draft regeneration policy, then extract the first diagnostic and generic rendering slices against the preserved baseline.