diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..0475203d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,80 @@ +# Changelog + +All notable changes to the Argumentum project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.9.0] — 2026-06-XX + +### Added — Multilingual Support (8 Languages) + +The entire pipeline now generates assets in **8 languages**: French, English, Russian, Portuguese, Spanish, Arabic, Farsi, and Chinese. + +- **CSV data**: 100% translation coverage for Fallacies, Virtues, Scenarii, and Rules across all 8 languages (title, description, example, family hierarchy, links) +- **PDF generation**: CardSets (Tarot, Poker, A0 posters, Print&Play) produce localized PDFs for all 8 languages via `CardSetLocalizations` field mapping +- **MindMap SVGs**: FreeMind mind maps generated for all 8 languages with localized node text, family hierarchy, and descriptions +- **Mémo cards**: Front/back cards with language-invariant grouping selectors and localized taxonomy labels +- **Rules cards**: Translated rule content for all 8 languages including AR/ES/FA/ZH additions +- **Entity layer**: Added AR/FA/ZH properties to `Fallacy.cs` (21 properties + 21 CsvHelper mappings) and `Rule.cs` (4 properties) +- **MindMap localization**: Extended `StaticConversions` in `AssetConverterConfig.cs` for AR/FA/ZH text, description, example, link, and family hierarchy fields +- **Taxonomy validation**: Test suite updated to validate all 8 languages (`_supportedLanguages: fr/en/ru/pt/es/ar/fa/zh`) + +### Added — Pipeline Infrastructure + +- **DatasetUpdater** (PR #210): Migration to official OpenAI .NET SDK v2.10.0 with multi-provider support (OpenAI + alternative providers). 7 task configs, 29 prompt files, function calling with structured output +- **GSheet ↔ CSV Sync** (PR #200): Bidirectional synchronization module with 6-layer upload protection (dry-run, diff, thresholds, confirmation, backup, verify). 4 spreadsheet configs for Fallacies, Scenarii, Virtues, Rules +- **Visual QA harness** (#412): Mechanical pixel-detector system for automated visual regression testing of generated PDFs and cards +- **Footer-collision detector** (#412 follow-up): Per-CardSet calibrated thresholds for Rules overflow detection +- **Playwright visual regression tests** (#212 scaffold): Test infrastructure for screenshot-based PDF verification + +### Added — Documentation + +- **Publication validation guide** (#140): Comprehensive per-language visual verification guide with scenarios and acceptance criteria +- **Architecture documentation**: `ARCHITECTURE_PIPELINE.md` with pipeline stage descriptions and data flow +- **SDDD methodology docs**: Investigation methodology, conversation grounding, and triple-grounding protocol +- **37 investigation reports** (2025-2026): Complete regression history, git archaeology, and closure reports in `docs/investigations/` + +### Fixed — Pipeline Recovery (Oct 2025 — Jun 2026) + +Complete restoration of the generation pipeline from the April 2024 Golden Master state: + +- **HarvestManager**: Restored 120s timeout (from 60s), removed manual frame.js injection, added explicit `generateImages()` call, raised Playwright timeout to 300s for heavy CardSets, fixed CardPen global race condition in Release mode +- **PdfManager**: Restored global QuestPDF lock (NOT thread-safe), fixed Rules card positioning (#119) +- **CardPen templates**: Restored `argumentsVertueux` CSS class, fixed Scenarii asset paths to GitHub URLs, auto-shrink overflowing card titles (#316), auto-shrink Virtues body text overflow (#420) +- **CSV injection**: Restored Golden Master CSV injection (no `Replace("\n", "\\n")` — PapaParse handles newlines correctly) +- **Configuration**: Removed erroneous `RowsetNb=14` for Scenarii CardSet, restored Virtues CardSet (critical for Print&Play Tarot) +- **SVG generation**: Replaced XSLT-based SVGs with FreeMind Batik SVGs (20 SVGs, 4 languages × 5 types), automated FreePlane GUI via `SendKeys.SendWait` +- **Mémo Back cards**: Language-invariant control-break grouping (#449), localized taxonomy labels for all 8 languages (#446), cyrillic font fallbacks + vertical grid auto-fit for RU (#452) + +### Fixed — Data Quality + +- **Fallacies FR audit**: Cell-by-cell review of all 7 family roots — selective revert of bloated/MT-contaminated descriptions (135+ cells audited, ~30 reverts) +- **Fallacies i18n**: Deterministic translation consistency fixes across all 8 languages (#432), cosmetic polish for PT/FA/ZH (#411, #424, #447) +- **Scenarii i18n**: 167/167 records 100% covered for EN/RU/PT across all 8 translatable fields (was 54% — 76 records missing) +- **Virtues i18n**: 100% coverage for title/description/remark × 4 languages (was 0% — added via PRs #218/#236/#246/#290/#295) +- **Rules i18n**: PT retranslation (#211), AR/ES/FA/ZH P&P content added, cover row EN contamination fixed +- **Fallacies taxonomy**: Propagated hierarchy labels to true 100% across 8 languages (#408) +- **Virtues FA blank-fill**: 100% i18n coverage across all 8 languages (#407) +- **PT Scenarii**: Deterministic enclitic-hyphen + MT-artefact cleanup (#383) + +### Changed + +- **DNN platform**: Upgraded 2sxc 15→21.07 with Razor14 migration + IRenderService fix (#418) +- **Dependencies**: System.Linq.Dynamic.Core 1.3.12→1.7.2 (security), Spectre.Console→0.50.0, QuestPDF pinned to 2022.12.12 (MIT free license), Magick.NET 13.5.0, SkiaSharp.NativeAssets.Win32 2.88.6 +- **Build artifacts**: Stopped tracking 968 MB of regenerable build outputs (#415 Phase 1) +- **Mémo Back taxonomy**: Grouping selector now language-invariant (CSS class-based, not text-based) + +### Test Coverage + +- **155 tests** pass (up from 0 in April 2024) +- Coverage includes: CsvDiffEngine, SyncSafetyChecker, DiffReport, CsvToGrid, MindMapHtmlWrapper, FallaciesLocalizationTests, TaxonomyValidationTests, Memo_Back localization, Playwright visual tests +- 1 skip (Freeplane GUI — requires interactive session) +- 5 skips (visual/infrastructure-dependent) + +### Migration Notes + +- **SkipConfigFile** must be `true` in `AssetConverterConfig.cs` — tuple serialization breaks `Translations` in JSON config +- **CSV data is read-only** — never modify before CardPen injection +- **QuestPDF global lock** — do not remove or parallelize PDF generation +- **Playwright timeout** — minimum 120s for harvesting, 300s for heavy CardSets diff --git a/RELEASE-NOTES-v0.9.0.md b/RELEASE-NOTES-v0.9.0.md new file mode 100644 index 00000000..95e044aa --- /dev/null +++ b/RELEASE-NOTES-v0.9.0.md @@ -0,0 +1,133 @@ +# Release Notes — Argumentum v0.9.0 + +**Release date**: TBD (pending DNN deployment, see #134) +**Scope**: 8-language support (FR, EN, RU, PT, ES, AR, FA, ZH) + +--- + +## Highlights + +### 🌍 8-Language Support + +Argumentum now generates its entire educational card game in **8 languages**: + +| Language | Code | Script | Status | +|----------|------|--------|--------| +| Français | `fr` | Latin | ✅ Complete (source) | +| English | `en` | Latin | ✅ Complete | +| Русский | `ru` | Cyrillic | ✅ Complete | +| Português | `pt` | Latin | ✅ Complete | +| Español | `es` | Latin | ✅ Complete | +| العربية | `ar` | Arabic (RTL) | ✅ Complete | +| فارسی | `fa` | Persian (RTL) | ✅ Complete | +| 中文 | `zh` | CJK | ✅ Complete | + +All CSV data (Fallacies, Virtues, Scenarii, Rules) is 100% translated across all 8 languages. The generation pipeline produces localized PDFs, MindMap SVGs, and card images for each language. + +### 🃏 Generated Assets + +| Asset Type | Languages | Count | +|------------|-----------|-------| +| Tarot Card PDFs | 8 | ~64 | +| Poker Card PDFs | 8 | ~8 | +| A0 Poster PDFs | 8 | ~16 | +| Print&Play PDFs | 8 | ~16 | +| MindMap SVGs | 8 | ~40 | +| Card Images (PNG) | 8 | ~9,834 | +| OWL Ontology | 1 (FR) | 1 (664 KB) | + +### 🛠 Pipeline Recovery + +After a series of regressions (May–September 2025), the entire .NET generation pipeline has been **fully restored and validated** against the April 2024 Golden Master: + +- **HarvestManager**: Playwright-based card image generation restored with correct timeouts and CSV injection +- **PdfManager**: QuestPDF assembly working with thread-safe serialization +- **MindMapper**: FreeMind + Batik SVG generation automated (including FreePlane GUI) +- **Tests**: 155 automated tests (up from 0) + +### 📊 Data Quality + +- **Fallacies FR audit**: All 7 family roots reviewed cell-by-cell — bloated/MT-contaminated descriptions reverted to authoritative FR source +- **Deterministic i18n**: Translation consistency enforced across all 8 languages (no MT artefacts, correct scripts for RU/AR/FA/ZH) +- **Virtues**: 100% translated (title/description/remark × 4 languages, extended to 8) +- **Scenarii**: 167/167 records fully translated (was 54%) + +--- + +## New Modules + +### DatasetUpdater (Translation Pipeline) + +Automated CSV translation using OpenAI GPT with structured output: + +- **SDK**: Official OpenAI .NET SDK v2.10.0 +- **Multi-provider**: OpenAI + alternative providers configurable +- **Tasks**: 7 task configs (all disabled by default — enable for on-demand translation) +- **Prompts**: 29 prompt files with function calling + JSON schema validation + +### GSheet ↔ CSV Sync + +Bidirectional synchronization between Google Sheets and local CSV files: + +- **6-layer safety**: dry-run → diff report → threshold check → user confirmation → backup → verify +- **4 spreadsheet configs**: Fallacies, Scenarii, Virtues, Rules +- **Formula protection**: Preserves Google Sheets formulas during sync + +### Visual QA Harness + +Automated visual regression testing for generated assets: + +- **Pixel detectors**: Footer-collision, text-overflow, margin calibration +- **Per-CardSet thresholds**: Custom calibration for each card type +- **8-language validation**: Automated checks across all supported languages + +--- + +## Known Limitations + +1. **RTL languages (AR, FA)**: Card layouts assume LTR — RTL-aware CSS may be needed for optimal rendering +2. **CJK fonts (ZH)**: Requires system-installed CJK fonts for correct rendering in PDFs and card images +3. **DNN site**: Deployment pending (#131/#132) — release coupled with site update (Decision 2) +4. **OWLOntology**: Published in French only — multilingual ontology planned for future release +5. **MindMap SVGs for AR/FA/ZH**: Pipeline configured but SVG regeneration pending (post-merge #454) + +--- + +## Breaking Changes + +- **SkipConfigFile = true**: The JSON config file is now ignored by default. C# source code is the single source of truth. This was necessary because `System.Text.Json` cannot serialize value tuples used in `Translations` lists. +- **`_supportedLanguages` expanded**: Test classes that validate language coverage now check 8 languages (was 4). Any custom test fixtures must be updated accordingly. +- **Fallacy entity**: 21 new properties added (AR/FA/ZH). CSV files must include corresponding columns or use `.Optional()` mappings. + +--- + +## Dependencies + +| Package | Version | Change | +|---------|---------|--------| +| QuestPDF | 2022.12.12 | Pinned (MIT free license, thread-safety boundary) | +| Magick.NET | 13.5.0 | Stable for SVG conversion | +| Microsoft.Playwright | 1.43.0 | Browser automation | +| OpenAI .NET SDK | 2.10.0 | New — translation pipeline | +| System.Linq.Dynamic.Core | 1.7.2 | Security upgrade (GHSA-4cv2-4hjh-77rx) | +| SkiaSharp.NativeAssets.Win32 | 2.88.6 | QuestPDF rendering backend | + +--- + +## Contributors + +- **jsboige** — Project lead, data curation, French source validation +- **Claude (ai-01)** — Pipeline recovery, code review, visual validation, documentation +- **Claude (po-2023)** — Heavy pipeline builds, data quality audits, translation pipeline operations + +--- + +## Next Steps (v1.0 Roadmap) + +- [ ] #131/#132 — DNN site deployment + Stripe integration +- [ ] #134 — GitHub Release with packaged assets +- [ ] #415 — `git-filter-repo` history cleanup (3-person coordinated operation) +- [ ] #212 — Full Playwright visual regression test suite +- [ ] #133 — OWL ontology publication +- [ ] RTL-aware card templates for Arabic and Farsi +- [ ] CJK font optimization for Chinese cards