docs: remove agent instructions

This commit is contained in:
Dandaedre 2026-09-16 01:28:10 +02:00
parent 5902c6bc43
commit 67e3687b50
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
2 changed files with 0 additions and 393 deletions

239
AGENT.md
View File

@ -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.

View File

@ -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.