From 67e3687b50522435b16a25ad2e967dc65d14c93d Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 01:28:10 +0200 Subject: [PATCH] docs: remove agent instructions --- AGENT.md | 239 ------------------------------------------------ AGENTS-TASKS.md | 154 ------------------------------- 2 files changed, 393 deletions(-) delete mode 100644 AGENT.md delete mode 100644 AGENTS-TASKS.md diff --git a/AGENT.md b/AGENT.md deleted file mode 100644 index a970ab4..0000000 --- a/AGENT.md +++ /dev/null @@ -1,239 +0,0 @@ -# AGENT.md — Reportist - -## Mission - -Reportist is a generic structured report renderer. - -Its responsibility is strictly: - - YAML / JSON - ↓ - Reportist - ↓ - Typst - ↓ - PDF - -Reportist must remain independent from any specific diagnostic system, -organisation, incident database, or reporting workflow. - -The existing `typst_reporter` repository may be used as a migration source, -but this repository is a clean implementation with intentionally defined -boundaries. - ---- - -## Primary goals - -1. Provide a stable structured report format. -2. Validate report input. -3. Render professional PDF reports using Typst. -4. Support configurable branding and presentation. -5. Remain usable as a standalone tool. -6. Preserve the sober corporate visual style of the original - `typst_reporter`. - ---- - -## Non-goals - -Reportist is NOT responsible for: - -- collecting diagnostic information; -- interpreting Windows events; -- generating diagnostic conclusions; -- storing historical reports; -- managing incidents; -- knowing what Beffroi is; -- knowing what WinDiagnostics is. - -Do not introduce dependencies on these concepts. - ---- - -## Migration source - -The existing `typst_reporter` project contains useful existing work. - -When migrating from it, classify files before copying them. - -Migrate: - -- generic Typst templates; -- generic components; -- generic rendering scripts; -- generic styling; -- reusable validation logic. - -Do NOT migrate: - -- actual Beffroi reports; -- investigation history; -- diagnostic output; -- machine-specific information; -- hard-coded Beffroi branding. - -Historical reports will eventually live in `beffroi-reports`. - ---- - -## Input format - -Reportist should define and document its input format. - -Prefer: - - schema/report.schema.json - -Reports should carry an explicit schema version. - -Conceptually: - - schema_version - metadata - branding - title - summary - findings - recommendations - actions - appendices - -Do not blindly implement this structure if the existing report format -already provides a better representation. - -Preserve useful compatibility with existing reports where practical. - ---- - -## Branding - -Organisation-specific branding must be supplied as data/assets. - -Do not hard-code: - -- organisation name; -- logo; -- author; -- department; -- machine name; -- incident terminology. - -A Beffroi report should be possible, but Reportist should work equally well -for an unrelated personal project. - ---- - -## CLI - -Aim for a simple interface. - -For example: - - reportist report.yaml - -and: - - reportist report.yaml --output report.pdf - -During early development, a wrapper such as: - - ./render.sh report.yaml - -is acceptable. - -Do not make the CLI unnecessarily complex. - ---- - -## Project structure - -Prefer a structure approximately like: - - src/ - templates/ - components/ - schema/ - examples/ - tests/ - assets/ - -Adapt this structure when there is a good reason. - -Do not create empty architecture merely to satisfy this example. - ---- - -## Examples - -Maintain at least one synthetic example: - - examples/example-report.yaml - -It should exercise the important renderer functionality without containing -private or machine-specific information. - -The example should render successfully as part of testing. - ---- - -## Compatibility - -Treat the report schema as a public interface. - -Once versions are used by external report repositories, avoid breaking them -without: - -- incrementing the schema version; -- documenting the change; -- providing a migration path when reasonable. - ---- - -## Testing - -At minimum test: - -1. valid example report renders; -2. invalid input is rejected; -3. missing optional fields do not break rendering; -4. branding can be replaced; -5. output does not require external Beffroi repositories. - ---- - -## Development principles - -Reportist's production interface must be Make, shell, and Typst. Python may exist only in `tests/`, -must run through a uv-managed virtual environment, and must not be called by -production validation or rendering. - -Prefer: - -- explicit schemas; -- simple tooling; -- deterministic output; -- readable Typst; -- clear error messages; -- few dependencies. - -Avoid: - -- hidden coupling; -- absolute paths; -- report-specific hacks; -- duplicated rendering logic. - ---- - -## Definition of success - -A fresh clone of Reportist can render its example PDF without: - -- WinDiagnostics; -- win-diagnostics; -- beffroi-reports; -- beffroi-reporting. - -If another project needs to know Reportist internals in order to produce a -report, improve the input contract instead. diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md deleted file mode 100644 index bbb8b10..0000000 --- a/AGENTS-TASKS.md +++ /dev/null @@ -1,154 +0,0 @@ -# Reportist migration tracker - -## Pass 5 — Runtime without Python - -- [x] RT5.1 Replace Python validation and rendering CLIs with shell and Typst. -- [x] RT5.2 Preserve JSON/YAML loading, version failures, safe relative assets, atomic output, and overwrite behavior. -- [x] RT5.3 Add Make targets and move all Python support code under tests with uv-only execution. -- [x] RT5.4 Verify standalone rendering through the shell/Typst entry point with no Python invocation. - -Follow [AGENT.md](AGENT.md). Reportist owns generic structured report validation -and Typst/PDF rendering. Diagnostic interpretation, incident history, report -conclusions, and Beffroi identity belong outside this repository. - -## 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 renderer, report schema, synthetic examples, or rendering tests have -been migrated. Legacy `typst_reporter` mixes reusable layout with diagnostics -and organisation-specific content, so files must be classified before extraction. - -## Pass 0 — Inventory and visual baselines - -- [x] RT0.1 Read repository instructions and inspect tracked files, README, and Jenkins scaffold. -- [x] RT0.2 Create this phased tracker and link it and the instructions from the README. -- [x] RT0.3 Inventory legacy `report.typ`, rendering wrappers, models, themes, validation, and content blocks; record source revisions, licenses, fonts, Typst requirements, and CLI behavior. -- [x] RT0.4 Classify reusable layout separately from diagnostics normalization/rules, hard-coded identity/assets, and real report content. Record destinations before copying anything. -- [x] RT0.5 Create synthetic representative reports and capture legacy visual/behavior baselines, including headings, tables, findings, actions, appendices, and page breaks where supported. - -Exit: the first extraction slice has a reusable feature inventory and observable -visual baseline without importing private reports into generic fixtures. - -## Pass 1 — Public report contract - -Depends on Pass 0 for the selected slice. - -- [x] RT1.1 Define `schema/report.schema.json` with explicit schema version, required/optional fields, metadata, branding, and generic report content; preserve useful legacy compatibility deliberately. -- [x] RT1.2 Map existing report fields and diagnostics presentation needs to generic content structures; keep evidence interpretation outside the renderer. -- [x] RT1.3 Define external asset resolution, theme overrides, missing branding behavior, and neutral defaults without organisation-specific names, authors, logos, or incident terminology. -- [x] RT1.4 Specify YAML/JSON validation errors, unsupported schema handling, and schema evolution/migration policy. -- [x] RT1.5 Define a simple CLI with explicit input and output paths, documented exit codes, and installation requirements; publish synthetic valid/invalid examples. - -Exit: unrelated callers can author valid reports without knowing internal Typst -modules or using a diagnostic/reporting repository. - -## Pass 2 — Generic rendering slice - -Depends on Pass 1. - -- [x] RT2.1 Extract generic templates/components and styling, retaining the sober visual style while supplying identity and domain labels through input data. -- [x] RT2.2 Implement schema validation before rendering with actionable errors. -- [x] RT2.3 Implement the YAML/JSON-to-Typst-to-PDF CLI; document output behavior and support invocation outside the repository working directory. -- [x] RT2.4 Add `examples/example-report.yaml` using synthetic content and generic assets; exercise the first supported content blocks. -- [x] RT2.5 Compare output with the baseline and record intentional visual or compatibility changes; add remaining reusable constructs in bounded slices. - -Exit: a documented generic example renders through the public CLI without legacy -sources, diagnostic code, real incidents, or hard-coded Beffroi identity. - -## Pass 3 — Validation and presentation coverage - -Depends on the working renderer. - -- [x] RT3.1 Test successful rendering of valid YAML and JSON reports and rejection of malformed input or unsupported schema versions. -- [x] RT3.2 Test that omitted optional fields render successfully and missing required fields produce clear errors. -- [x] RT3.3 Test replaceable branding with unrelated synthetic identities and verify neutral defaults. -- [x] RT3.4 Exercise supported blocks, long content, pagination, and asset paths; inspect representative PDFs for clipping, broken layout, and missing content. -- [x] RT3.5 Document and control relevant Typst/font/tool dependencies so output can be recreated; state reproducibility limitations explicitly. - -Exit: the required rendering behaviors are covered by synthetic tests and visual -review, with no private source material in examples. - -## Pass 4 — Standalone delivery and integration handoff - -Depends on validated rendering. - -- [x] RT4.1 Enable schema, example rendering, and regression checks in Jenkins; report actual validation coverage and tool versions. -- [x] RT4.2 Document standalone installation, CLI usage, schema authoring, branding, asset paths, and troubleshooting. -- [x] RT4.3 Verify a fresh clone renders its example without WinDiagnostics, win-diagnostics, beffroi-reports, beffroi-reporting, or legacy checkout paths. -- [x] RT4.4 Audit for diagnostic interpretation, hard-coded branding, historical content, duplicated rendering logic, and absolute machine-specific paths. -- [x] RT4.5 Provide a verified component revision and public validation/rendering commands to consumers; leave report packaging/publication and cross-repository orchestration outside Reportist. - -Exit: Reportist is an independently usable renderer whose documented input -contract is sufficient for any report-producing application. - -## Handoff log - -### 2026-09-15 — Presentation and standalone verification - -- Completed RT2.5, RT3.4–RT3.5, and RT4.2–RT4.4. Recorded intentional differences - from the legacy baseline: neutral defaults, external branding, schema-first - validation, and explicit output paths. -- Added a synthetic long-content regression that verifies multi-page flow and - retained first/tail text with Poppler when available. Added an isolated-copy - test that renders the full example with no sibling or legacy repositories. -- Documented installation, asset resolution, troubleshooting, exact commands, - Typst/font dependencies, and the limits of byte-for-byte PDF reproducibility. - Audited the implementation and fixtures for domain interpretation, hard-coded - identity, historical content, duplicated rendering logic, and absolute paths. -- Validation: implementation revision `3356f3e` passes 17 tests with Python 3.11.14 - and Typst 0.15.1, including a long report of at least four pages. Consumers can - use the documented `tools/validate.py` and `tools/render.py` commands; packaging, - publication, and cross-repository workflows remain outside Reportist. - -### 2026-09-15 — First standalone generic renderer - -- Completed RT1.5, RT2.1–RT2.4 and RT3.1–RT3.3 with a schema-first Python CLI - and generic Typst template. YAML/JSON reports render from any working directory; - identity, logo and colors are supplied only through report data. -- Rendering stages the validated input and logo in a temporary Typst root, rejects - symlinks/traversal, and publishes a complete PDF atomically. Existing outputs - require `--force`; input files can never be output targets. -- Added seven rendering tests covering YAML/JSON, minimal input, invalid reports, - neutral defaults, unrelated branding/logo, output protection and asset safety. -- Validation: all eight contract and seven rendering tests pass with Python 3.11.14 - and Typst 0.15.1. The full example produces a readable three-page A4 PDF and - the minimal example produces one page; extracted text contains expected content. -- Limits: RT2.5 visual baseline comparison, long-content/pagination review and - clean standalone clone verification remain open. -- Jenkins now requires Typst, prints its version and runs schema plus rendering - tests. Next: compare representative pages with the preserved baseline, then - extend pagination and asset coverage. - -### 2026-09-15 — Planning pass - -- Completed RT0.1–RT0.2; added roadmap and README navigation. -- Validation: documentation links, task IDs, and whitespace checked; renderer tests were not run because no implementation exists yet. -- Open: detailed source classification, synthetic examples, and baseline PDFs. -- Next: RT0.3–RT0.5, then define the first RT1 schema/CLI slice. - -### 2026-09-15 — Inventory and executable baseline pass - -- Completed RT0.3–RT0.5 for the initial rendering slice: source/function inventory, draft field mapping, and two synthetic legacy report examples with retained MIT notice. -- Evidence: [migration inventory](docs/migration-inventory.md), `tests/fixtures/legacy/`. -- Validation: macro baseline command rendered both report PDFs and rejected missing author/date and unknown theme. Reviewed the technical report first page; later-page/long-content/alternate-branding coverage remains open. -- Existing Beffroi logo coupling remains visible in legacy output. No generic renderer implementation or public schema is claimed yet. -- Next: RT1 schema/validation fixtures, then RT2 generic rendering extraction. - -### 2026-09-15 — Versioned contract pass - -- Completed RT1.1–RT1.4: generic report v1 schema, YAML/JSON validator and paired synthetic examples, optional branding/path contract, generic blocks, and version/legacy mapping documentation. -- Evidence: [report contract](docs/report-contract.md), `schema/report.schema.json`, `tools/validate.py`, `examples/`, `tests/test_contract.py`. -- Validation: eight unittest cases with many invalid-input subcases passed on Python 3.11 and 3.14, including an isolated standalone copy. Covers YAML/JSON parity, minimal reports, invalid dates/versions, duplicate keys, generic branding shape, nested blocks and parser errors. -- Jenkins now runs the contract tests. Rendering, actual asset loading and visual branding are not implemented or validated by these schema tests. -- Next: finish RT1.5 exact rendering command/output behavior, then RT2 extraction. No render command is claimed yet.