docs: add migration roadmaps and pin component planning commits
Beffroi Reporting CI Beffroi Reporting integration CI failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit
Details
Beffroi Reporting CI Beffroi Reporting integration CI failed.
Beffroi/beffroi-reporting/pipeline/head There was a failure building this commit
Details
This commit is contained in:
parent
71a2a7652d
commit
509a940e88
|
|
@ -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.
|
||||
13
README.md
13
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
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
Subproject commit a14d627b0dd6a818bf044c86cc7f8d5bdc23331f
|
||||
Subproject commit 35498b3d8e4e09ef1e4f993491b0837878d663db
|
||||
|
|
@ -1 +1 @@
|
|||
Subproject commit de764c1961dcaf6a036cc6f602d0fc695a7d83ec
|
||||
Subproject commit 2c1c085ca2940e3908c16035398d739a8773644c
|
||||
|
|
@ -1 +1 @@
|
|||
Subproject commit f019b33a4e40ad76589b1b9f7eff2f327953d894
|
||||
Subproject commit 861757f0d165429e789e042cf4d015ab5b72f85c
|
||||
Loading…
Reference in New Issue