From 509a940e88fb1a72cada13d238c2a08b910980fc Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 15 Sep 2026 15:56:57 +0200 Subject: [PATCH] docs: add migration roadmaps and pin component planning commits --- AGENTS-TASKS.md | 163 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 13 ++-- beffroi-reports | 2 +- reportist | 2 +- win-diagnostics | 2 +- 5 files changed, 175 insertions(+), 7 deletions(-) create mode 100644 AGENTS-TASKS.md diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md new file mode 100644 index 0000000..33fde17 --- /dev/null +++ b/AGENTS-TASKS.md @@ -0,0 +1,163 @@ +# Reporting migration tracker + +## How to use this tracker + +This is the cross-repository handoff for a migration in several passes. Follow +[AGENTS.md](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. + +## Current baseline — 2026-09-15 + +Component task details and handoffs are maintained in: + +- [Win Diagnostics tracker](win-diagnostics/AGENTS-TASKS.md) +- [Reportist tracker](reportist/AGENTS-TASKS.md) +- [Beffroi Reports tracker](beffroi-reports/AGENTS-TASKS.md) + +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/`, and + `reportist/`. The integration instructions target `diagnostics/`, `reports/`, + and `reporter/`; the path migration remains a separate task. +- Legacy sources are pinned under `references/WinDiagnostics/` and + `references/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 + +- [x] P0.1 Read root and all three component instruction files. +- [x] P0.2 Inspect tracked layout, submodule pins, READMEs, root CI, and legacy entry points. +- [x] P0.3 Record initial ownership boundaries, coupling, and phased acceptance criteria here. +- [x] 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. Inventory and baseline execution have not yet been completed. + +## 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.json` and 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.json` with 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. +- [ ] P5.6 Pin the tested component commits intentionally and document external dependencies plus clean-checkout reproduction commands; verify `git clone --recursive` followed 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 — 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. diff --git a/README.md b/README.md index 5e95c4d..e37064a 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,14 @@ It brings the complete environment together as Git submodules: ```text id="8efkt6" beffroi-reporting -├── diagnostics/ → win-diagnostics -├── reports/ → beffroi-reports -└── reporter/ → reportist +├── win-diagnostics/ +├── beffroi-reports/ +└── reportist/ ``` +The target layout uses `diagnostics/`, `reports/`, and `reporter/` respectively. +Renaming the current submodule paths is tracked in the migration roadmap. + During migration, the previous implementations are also available under `references/` so developers and agents can inspect the complete old and new workflows from one workspace. The target pipeline is: @@ -50,7 +53,9 @@ git submodule update --init --recursive 🚧 **Architecture migration in progress** -`AGENTS-TASKS.md` contains the migration roadmap. `AGENT.md` defines repository ownership and rules for agents working across the workspace. +[AGENTS-TASKS.md](AGENTS-TASKS.md) tracks completed work, remaining migration passes, +acceptance criteria, and the next-pass handoff. [AGENTS.md](AGENTS.md) defines +repository ownership and rules for agents working across the workspace. ## License diff --git a/beffroi-reports b/beffroi-reports index a14d627..35498b3 160000 --- a/beffroi-reports +++ b/beffroi-reports @@ -1 +1 @@ -Subproject commit a14d627b0dd6a818bf044c86cc7f8d5bdc23331f +Subproject commit 35498b3d8e4e09ef1e4f993491b0837878d663db diff --git a/reportist b/reportist index de764c1..2c1c085 160000 --- a/reportist +++ b/reportist @@ -1 +1 @@ -Subproject commit de764c1961dcaf6a036cc6f602d0fc695a7d83ec +Subproject commit 2c1c085ca2940e3908c16035398d739a8773644c diff --git a/win-diagnostics b/win-diagnostics index f019b33..861757f 160000 --- a/win-diagnostics +++ b/win-diagnostics @@ -1 +1 @@ -Subproject commit f019b33a4e40ad76589b1b9f7eff2f327953d894 +Subproject commit 861757f0d165429e789e042cf4d015ab5b72f85c