docs: remove agent instructions
This commit is contained in:
parent
5902c6bc43
commit
67e3687b50
239
AGENT.md
239
AGENT.md
|
|
@ -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.
|
||||
154
AGENTS-TASKS.md
154
AGENTS-TASKS.md
|
|
@ -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.
|
||||
Loading…
Reference in New Issue