30 KiB
Reporting migration tracker
Pass 7 — Remove production Python
- P7.1 Rewrite agent instructions and public commands around Make, shell, jq, PowerShell, and Typst; confine Python to uv-managed tests.
- P7.2 Replace win-diagnostics Python normalization, analysis, and validation without changing contract or rule outcomes.
- P7.3 Replace beffroi-reports Python adaptation and immutable publication while preserving race safety and regeneration guarantees.
- P7.4 Replace Reportist Python validation/rendering while preserving input, asset, overwrite, and standalone behavior.
- P7.5 Remove Python from bootstrap and runtime dependency checks; make uv and Python test-only dependencies.
- P7.6 Run component tests through uv, then verify capture-to-PDF integration without Python on the runtime PATH.
Validation: 70 component tests pass through uv-managed environments, including all five owning-validator adapter integration tests. The root workflow then performs capture analysis, draft generation, validation, and PDF rendering using only shell, jq, Typst, and the native publication helper.
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.
- The initial submodule paths were
win-diagnostics/,beffroi-reports/, andreportist/; P5.1 later aligned them todiagnostics/,reports/, andreporter/. - 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.
- The 53-event catalog, seven watchlist entries, grouping, candidate correlation, and time fading are migrated; reliability deduplication and non-event health checks remain.
- 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 complete analysis, diagnostic-to-report, and PDF-rendering path is included. - 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-16 — Locally actionable migration work complete
- Completed the cross-repository inventory/CLI documentation, reliability-history deduplication, standalone diagnostic handoff, reports PDF/archive policy, independent adapter operation, CI cleanup, and legacy/coupling audits.
- Closed P0.5, P1.5, P4.1, P4.4, P4.6, P6.2–P6.3, and P6.5–P6.6 with component evidence. Runtime orchestration uses only the three active pinned components; reference submodules remain provenance/baseline sources, not runtime dependencies.
- Encrypted packaging is not retained without an approved distribution channel.
Publication remains disabled.
docs/remaining-gates.mdrecords the exact Windows, private-incident, and production inputs required for the remaining tasks. - Validation: a fresh clone bootstrapped all five pinned revisions, passed 66 component tests plus the complete capture-to-PDF workflow, passed the exact-pin check, and remained clean.
2026-09-15 — Integration workspace layout complete
- Completed P5.1 and therefore Pass 5 by moving the active pinned submodules to
diagnostics/,reports/, andreporter/. Component repository names and remote URLs remain unchanged; reference submodules remain underreferences/. - Updated bootstrap, workflow commands, component checks, legacy baseline paths, documentation links, and CI-facing scripts together. No component implementation was copied into the integration repository.
- Validation: the exact-pin bootstrap check, all 64 component tests, and the complete capture-to-PDF workflow pass both in the working tree and a fresh clone. The fresh clone initialized all five pinned revisions and remained clean.
- Next: continue explicitly scoped component/native-platform or historical-data work from Pass 6; the reproducible integration workspace pass is complete.
2026-09-15 — FreeBSD adapter publication fix
- Pinned beffroi-reports with a FreeBSD-safe
publish_exclusive: native no-replace rename remains the first path, while unsupported libc/filesystems use an atomic destination-directory reservation before the final POSIX rename. - The fallback directly covers FreeBSD's reported
EOPNOTSUPP/errno 45 response. Existing and concurrently created destinations remain untouched; staged content remains available on reservation failure. - Validation: all 22 adapter tests pass with owning validators, all 42 diagnostic and renderer tests pass, and the complete capture-to-PDF workflow succeeds. FreeBSD Jenkins is still required to confirm behavior on the affected worker.
2026-09-15 — Bootstrap and workflow orchestration
- Completed P5.2–P5.3 with
bootstrap.sh, explicitmake analyse,make draft,make render, andmake allentry points. The root only composes the pinned public component CLIs; component implementation stays in its owning repository. - Bootstrap initializes recorded submodule revisions, reports missing Git/uv/Typst,
prepares isolated pinned Python environments, and makes no system-package changes.
Its
--checkmode verifies tools, component presence, and exact gitlink revisions. - The integration suite now exercises
scripts/workflow.sh allitself, producing a diagnostic artifact, immutable generation, and PDF in a fresh temporary run. Explicit reference time and report metadata prevent clock/account defaults. - Validation: 62 component tests plus the complete workflow pipeline pass. A clean local clone initialized all five recorded gitlinks, ran bootstrap, repeated the suite, and remained clean. Local source URLs replaced HTTPS only to keep this reproducibility check offline; the recorded public URLs were unchanged.
- Documented the tested Git/uv/Python/Typst versions, fonts, optional Poppler tools, network boundary, exact reproduction commands, and PDF byte limitations. Native Windows collection remains outside the current Linux validation.
- Next: align the three active submodule paths under P5.1, then address remaining component migration work.
2026-09-15 — Standalone renderer pass complete
- Completed P3.1–P3.5. Reportist now has the generic schema-first YAML/JSON-to-PDF renderer, neutral defaults, external branding, safe asset staging, documented dependencies, and an isolated-copy render that has no sibling dependencies.
- Added long-content pagination coverage that checks first and tail text in a multi-page PDF. Visually inspected the three-page synthetic report; its first and appendix pages are readable without clipping or missing content.
- Recorded intentional differences from the legacy baseline and fixed stale Jenkins reporting that claimed rendering was still pending.
- Validation: 17 Reportist tests pass with Python 3.11.14 and Typst 0.15.1. Poppler verifies pagination and extracted tail content when installed.
- Pinned the verified standalone renderer through the Reportist component handoff; packaging and publication remain outside that component.
- Next: implement root bootstrap and workflow commands for the already working end-to-end pipeline.
2026-09-15 — Complete event/watchlist analysis catalog
- Advanced P2.3 and completed WD3.1 for the selected event scope with all 53 legacy event rules and seven advisory watchlist matchers. Every finding links to raw observations; unknown events remain grouped and explicitly unanalysed.
- Exact identity, basename, version, enabled-state, prerequisite and repeated-event gates are regression-tested. Candidate matches do not claim exploitation, active conflict or causation, and remediation remains in the reports layer.
- Validation: 25 diagnostic tests plus the raw-capture-to-PDF integration pipeline pass. Native collection and additional structured hardware/health checks remain.
- Next: add high-level workflow/bootstrap commands, then broaden non-event checks and perform Windows collection validation.
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.