From 4225b5b962438177cdf1b0071c35057f0307c7d8 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Sun, 10 May 2026 16:12:26 +0300
Subject: [PATCH 1/7] docs(roadmap): consolidate 7 completed phase files into
 completed-phases.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tidy-up of the docs/roadmap/ directory: every completed phase file
(Phase 10 / 10.5 / 11 / 11.5 / 12 / 12.5 / 12.6) is now absorbed into
the canonical completed-phases.md archive with full content (heading
shift +1 level), and the standalone files are removed. The roadmap
directory now carries only the planning surface — completed-phases.md
+ releases.md + risks-and-decisions.md + the two PLANNED phase files
(phase-13-pro-cli.md, phase-14-pipeline-chains.md).

Changes:

- docs/roadmap/completed-phases.md: 656 → 1285 lines. Replaces the
  earlier Phase 10 stub with the full phase-10-post-training.md content;
  appends Phase 10.5, 11, 11.5, 12, 12.5, 12.6 in chronological order,
  each as a top-level "## Phase N" section.
- docs/roadmap/phase-10-post-training.md (deleted)
- docs/roadmap/phase-10-5-quickstart.md (deleted)
- docs/roadmap/phase-11-data-ingestion.md (deleted)
- docs/roadmap/phase-11-5-backlog.md (deleted)
- docs/roadmap/phase-12-data-curation-maturity.md (deleted)
- docs/roadmap/phase-12-5-backlog.md (deleted)
- docs/roadmap/phase-12-6-closure-cycle.md (deleted)

References redirected to completed-phases.md (with internal anchors
where useful):

- CHANGELOG.md (3 references)
- docs/roadmap.md + docs/roadmap-tr.md (table + tree visualisation)
- docs/roadmap/phase-14-pipeline-chains.md
- docs/roadmap/releases.md
- docs/standards/documentation.md
- docs/standards/release.md
- tools/bench_simhash.py
- tests/test_phase12_5.py
- forgelm/ingestion.py
- .claude/skills/add-trainer-feature/SKILL.md

Verified: ruff format/check clean, all 6 doc CI guards green
(anchor-resolution 266 files, bilingual-parity 45 pairs, cli-help
439 invocations, wizard-defaults 3/8, no-analysis-refs, dry-run).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .claude/skills/add-trainer-feature/SKILL.md   |   2 +-
 CHANGELOG.md                                  |   6 +-
 docs/roadmap-tr.md                            |  15 +-
 docs/roadmap.md                               |  17 +-
 docs/roadmap/completed-phases.md              | 647 +++++++++++++++++-
 docs/roadmap/phase-10-5-quickstart.md         |  54 --
 docs/roadmap/phase-10-post-training.md        |  71 --
 docs/roadmap/phase-11-5-backlog.md            |  92 ---
 docs/roadmap/phase-11-data-ingestion.md       |  53 --
 docs/roadmap/phase-12-5-backlog.md            |  46 --
 docs/roadmap/phase-12-6-closure-cycle.md      | 149 ----
 .../phase-12-data-curation-maturity.md        | 160 -----
 docs/roadmap/phase-14-pipeline-chains.md      |   2 +-
 docs/roadmap/releases.md                      |   4 +-
 docs/standards/documentation.md               |   2 +-
 docs/standards/release.md                     |   2 +-
 forgelm/ingestion.py                          |   4 +-
 tests/test_phase12_5.py                       |   2 +-
 tools/bench_simhash.py                        |   2 +-
 19 files changed, 660 insertions(+), 670 deletions(-)
 delete mode 100644 docs/roadmap/phase-10-5-quickstart.md
 delete mode 100644 docs/roadmap/phase-10-post-training.md
 delete mode 100644 docs/roadmap/phase-11-5-backlog.md
 delete mode 100644 docs/roadmap/phase-11-data-ingestion.md
 delete mode 100644 docs/roadmap/phase-12-5-backlog.md
 delete mode 100644 docs/roadmap/phase-12-6-closure-cycle.md
 delete mode 100644 docs/roadmap/phase-12-data-curation-maturity.md

diff --git a/.claude/skills/add-trainer-feature/SKILL.md b/.claude/skills/add-trainer-feature/SKILL.md
index 0d101b11..2cf08bc2 100644
--- a/.claude/skills/add-trainer-feature/SKILL.md
+++ b/.claude/skills/add-trainer-feature/SKILL.md
@@ -24,7 +24,7 @@ Do **not** use for:
 
 1. [docs/standards/architecture.md](../../../docs/standards/architecture.md) — module boundaries
 2. [docs/standards/testing.md](../../../docs/standards/testing.md) — what tests CI demands
-3. The **phase file** describing the feature (e.g., [docs/roadmap/phase-10-post-training.md](../../../docs/roadmap/phase-10-post-training.md))
+3. The **phase file** describing the feature (e.g., [docs/roadmap/completed-phases.md](../../../docs/roadmap/completed-phases.md))
 4. Existing similar feature — read one similar trainer/module end-to-end before writing yours
 
 ## The scaffold
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5f188866..a0973cb0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -782,7 +782,7 @@ review-cycle fixes applied across the four phases above).
 ### Phase 12.5 — Data Curation Polish (backlog items #1–#4)
 
 Four follow-up items from
-[`docs/roadmap/phase-12-5-backlog.md`](docs/roadmap/phase-12-5-backlog.md)
+[`docs/roadmap/completed-phases.md`](docs/roadmap/completed-phases.md)
 ship together — none require new architecture; each is a small
 additive surface on top of the Phase 12 ingestion + audit lineage.
 
@@ -1141,7 +1141,7 @@ Round-1 review of the Phase 12 commit surfaced four critical regressions / bugs
 
 ### Added — Phase 12 (Data Curation Maturity, targeting v0.5.2)
 
-Direct continuation of the Phase 11 / 11.5 ingestion + audit lineage. Closes the four concrete gaps surfaced by the post-`v0.5.1` competitive review (LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling). Tier 1 (5 must-have tasks) shipped; Tier 2/3 (Presidio adapter, Croissant metadata, `--all-mask`, wizard "audit first") deferred to a [Phase 12.5 backlog](docs/roadmap/phase-12-5-backlog.md).
+Direct continuation of the Phase 11 / 11.5 ingestion + audit lineage. Closes the four concrete gaps surfaced by the post-`v0.5.1` competitive review (LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling). Tier 1 (5 must-have tasks) shipped; Tier 2/3 (Presidio adapter, Croissant metadata, `--all-mask`, wizard "audit first") deferred to a [Phase 12.5 backlog](docs/roadmap/completed-phases.md).
 
 - **MinHash LSH dedup option** (`forgelm/data_audit.py`: `compute_minhash`, `find_near_duplicates_minhash`, `_count_leaked_rows_minhash`) — Opt-in `--dedup-method minhash --jaccard-threshold 0.85` route via the optional `[ingestion-scale]` extra (`datasketch>=1.6.0`). Default simhash + LSH banding from Phase 11.5 stays untouched and remains the only method that runs without an optional dependency. `audit_dataset(...)` API gains `dedup_method`, `minhash_jaccard`, `minhash_num_perm` parameters; `near_duplicate_summary.method` records which path ran. Cross-split overlap + within-split duplicate scan share the same method flag. MinHash is approximate (permutation noise; default `num_perm=128`) — pin `num_perm` for cross-run determinism.
 - **Markdown-aware splitter** (`forgelm/ingestion.py`: `_chunk_markdown`, `_chunk_markdown_tokens`, `_markdown_sections`, `_heading_breadcrumb`) — New `--strategy markdown` parses heading hierarchy (`# H1` … `###### H6`), keeps code-fenced blocks atomic (heading-shaped lines inside ```` ``` ```` blocks are not interpreted as section boundaries), and inlines a heading **breadcrumb** at the top of each chunk so SFT loss sees the document context. Composes with the Phase 11.5 token-aware mode (`--chunk-tokens` + `--tokenizer`).
@@ -1305,7 +1305,7 @@ Operational polish on top of `v0.5.0`'s ingestion + audit surface — no new tra
 ### Documentation
 
 - New "Option 0: One-Command Quickstart Template" section at the top of `docs/guides/quickstart.md`.
-- `docs/roadmap.md`, `docs/roadmap-tr.md`, `docs/roadmap/phase-10-5-quickstart.md`, `docs/roadmap/releases.md` updated to mark Phase 10.5 as Done.
+- `docs/roadmap.md`, `docs/roadmap-tr.md`, `docs/roadmap/completed-phases.md`, `docs/roadmap/releases.md` updated to mark Phase 10.5 as Done.
 - `README.md` quickstart section updated to lead with `forgelm quickstart`.
 
 ---
diff --git a/docs/roadmap-tr.md b/docs/roadmap-tr.md
index 4c53e3fa..79213060 100644
--- a/docs/roadmap-tr.md
+++ b/docs/roadmap-tr.md
@@ -7,10 +7,10 @@
 | Tür | Faz | Durum |
 |-----|-----|-------|
 | ✅ Tamam | [Faz 1-9](roadmap/completed-phases.md) | SOTA iyileştirmeleri, değerlendirme, güvenilirlik, kurumsal entegrasyon, ekosistem, hizalama stack'i, güvenlik, EU AI Act uyumluluğu (Madde 9-17 + Ek IV), gelişmiş güvenlik zekası |
-| ✅ Tamam | [Faz 10 — Post-Training Tamamlama](roadmap/phase-10-post-training.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — `v0.4.0` |
-| ✅ Tamam | [Faz 10.5 — Quickstart Katmanı ve Onboarding](roadmap/phase-10-5-quickstart.md) | `forgelm quickstart <template>`, 5 hazır template, seed veri setleri — `v0.4.5` |
+| ✅ Tamam | [Faz 10 — Post-Training Tamamlama](roadmap/completed-phases.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — `v0.4.0` |
+| ✅ Tamam | [Faz 10.5 — Quickstart Katmanı ve Onboarding](roadmap/completed-phases.md) | `forgelm quickstart <template>`, 5 hazır template, seed veri setleri — `v0.4.5` |
 | ✅ Tamam | [Faz 11 + 11.5 + 12 + 12.5 — Doküman Yutma ve Veri Curation Pipeline'ı](roadmap/releases.md#v050-document-ingestion-data-curation-pipeline) | `forgelm ingest`, `forgelm audit`, PII regex + simhash dedup, LSH banding, streaming reader, PII şiddet katmanları, wizard ingest+audit, MinHash LSH dedup, markdown splitter, code/secrets tarama, kalite heuristic'leri, DOCX tablo koruması, `--all-mask`, Croissant 1.0, Presidio NER — `v0.5.0` (PyPI 2026-04-30) |
-| ✅ Tamam | [Faz 12.6 — Kapanış Döngüsü (5 wave boyunca 38 faz)](roadmap/phase-12-6-closure-cycle.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommand'leri, compliance verification toolbelt, bilingual mirror sweep + 4 CI guard, supply-chain security, cross-OS release matrix — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
+| ✅ Tamam | [Faz 12.6 — Kapanış Döngüsü (5 wave boyunca 38 faz)](roadmap/completed-phases.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommand'leri, compliance verification toolbelt, bilingual mirror sweep + 4 CI guard, supply-chain security, cross-OS release matrix — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
 | ✅ Tamam | Faz 22 — CLI sihirbazı tarayıcı yüzeyiyle eşdeğerlik | `forgelm --wizard` artık tarayıcı sihirbazıyla aynı 9-adımlı akışı çalıştırıyor (welcome → use-case → model → strategy → trainer → dataset → training-params → compliance → evaluation), `--wizard-start-from <yaml>` ile idempotent yeniden çalıştırma, şema-güdümlü varsayılanlar SOT, ayrı `EXIT_WIZARD_CANCELLED = 5` exit kodu, `$XDG_CACHE_HOME` altında durum kalıcılığı ve çıkışta validate — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
 | ✅ Tamam | Site dokümantasyon düzeltme taraması | `site/*.html` üzerindeki tüm görünür YAML / artefakt-yolu / CLI / şema iddiaları artık live `forgelm/` yüzeyine karşı doğrulanıyor. Hero YAML demo'su gerçek Pydantic alan adlarıyla yeniden yazıldı, compliance artefakt ağacı disk düzenine göre yeniden çizildi, hayalet YAML anahtarları + CLI flag'leri kaldırıldı, ifadeler live davranışa hizalandı. Altı dilde i18n (en / tr / de / fr / es / zh) tam paritede (her biri 731 anahtar) — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
 | 📋 Planlandı | [Faz 14 — Çok Aşamalı Pipeline Zincirleri](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO config zinciri, pipeline kaynak izleri → `v0.6.0` |
@@ -81,14 +81,7 @@ docs/
 ├── roadmap.md                                  # İngilizce özet index
 ├── roadmap-tr.md                               # Bu dosya — Türkçe mirror
 └── roadmap/
-    ├── completed-phases.md                     # Faz 1-10 arşivi (detaylı, İngilizce)
-    ├── phase-10-post-training.md               # Tamamlandı — v0.4.0
-    ├── phase-10-5-quickstart.md                # Tamam (Faz 10.5) — v0.4.5 olarak yayınlandı
-    ├── phase-11-data-ingestion.md              # Tamam (Faz 11) — v0.5.0'a birleştirildi
-    ├── phase-11-5-backlog.md                   # Tamam (Faz 11.5) — v0.5.0'a birleştirildi; ingestion/audit cilası
-    ├── phase-12-data-curation-maturity.md      # Tamam (Faz 12 Tier 1) — v0.5.0'a birleştirildi; MinHash LSH, markdown splitter, secrets scan
-    ├── phase-12-5-backlog.md                   # Tamam (Faz 12.5) — v0.5.0'a birleştirildi; Presidio, Croissant, --all-mask, wizard audit-first
-    ├── phase-12-6-closure-cycle.md             # Tamam — 5 wave boyunca 38 faz, v0.5.5 ile paketlenmiş
+    ├── completed-phases.md                     # Faz 1-12.6 arşivi (detaylı, İngilizce) — Faz 10 / 10.5 / 11 / 11.5 / 12 / 12.5 / 12.6 inline gömüldü (sırasıyla v0.4.0 / v0.4.5 / v0.5.0 / v0.5.5)
     ├── phase-13-pro-cli.md                     # Planlandı — v0.6.0-pro (gated)
     ├── phase-14-pipeline-chains.md             # Planlandı — v0.6.0 (v0.5.5 kapanış döngüsünün takip release'i)
     ├── releases.md                             # v0.3.0 → v0.6.0 sürüm notları
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 72efa407..a3e5675f 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -7,10 +7,10 @@
 | Type | Phase | Status |
 |-----|-------|--------|
 | ✅ Done | [Phase 1-9](roadmap/completed-phases.md) | SOTA upgrades, evaluation, reliability, enterprise integration, ecosystem, alignment stack, safety, EU AI Act compliance (Articles 9-17 + Annex IV), advanced safety intelligence |
-| ✅ Done | [Phase 10 — Post-Training Completion](roadmap/phase-10-post-training.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — shipped `v0.4.0` |
-| ✅ Done | [Phase 10.5 — Quickstart Layer & Onboarding](roadmap/phase-10-5-quickstart.md) | `forgelm quickstart <template>`, 5 bundled templates with seed datasets — shipped `v0.4.5` |
+| ✅ Done | [Phase 10 — Post-Training Completion](roadmap/completed-phases.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — shipped `v0.4.0` |
+| ✅ Done | [Phase 10.5 — Quickstart Layer & Onboarding](roadmap/completed-phases.md) | `forgelm quickstart <template>`, 5 bundled templates with seed datasets — shipped `v0.4.5` |
 | ✅ Done | [Phase 11 + 11.5 + 12 + 12.5 — Document Ingestion & Data Curation Pipeline](roadmap/releases.md#v050-document-ingestion-data-curation-pipeline) | `forgelm ingest`, `forgelm audit`, PII regex + simhash dedup, LSH banding, streaming reader, PII severity tiers, wizard ingest+audit, MinHash LSH dedup, markdown splitter, code/secrets scan, quality heuristics, DOCX table preservation, `--all-mask`, Croissant 1.0, Presidio NER — shipped `v0.5.0` (PyPI 2026-04-30) |
-| ✅ Done | [Phase 12.6 — Closure Cycle (37 content fazlar + 1 release tag = 38 entries across 5 waves)](roadmap/phase-12-6-closure-cycle.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommands, compliance verification toolbelt, bilingual mirror sweep + 4 CI guards, supply-chain security, cross-OS release matrix — bundled into `v0.5.5` (PyPI 2026-05-10) |
+| ✅ Done | [Phase 12.6 — Closure Cycle (37 content fazlar + 1 release tag = 38 entries across 5 waves)](roadmap/completed-phases.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommands, compliance verification toolbelt, bilingual mirror sweep + 4 CI guards, supply-chain security, cross-OS release matrix — bundled into `v0.5.5` (PyPI 2026-05-10) |
 | ✅ Done | Phase 22 — CLI wizard parity with the in-browser surface | `forgelm --wizard` runs the same 9-step flow as the web wizard (welcome → use-case → model → strategy → trainer → dataset → training-params → compliance → evaluation), with idempotent re-run via `--wizard-start-from <yaml>`, schema-driven defaults SOT, distinct `EXIT_WIZARD_CANCELLED = 5` exit code, state persistence under `$XDG_CACHE_HOME`, and validate-on-exit — bundled into `v0.5.5` (PyPI 2026-05-10) |
 | ✅ Done | Site documentation correction sweep | All visible YAML / artefact-path / CLI / schema claims on `site/*.html` now validate against the live `forgelm/` surface. Hero YAML demo rewritten with real Pydantic field names, compliance artefact tree redrawn against the on-disk layout, ghost YAML keys + CLI flags removed, wording aligned with live behaviour. Six-language i18n (en / tr / de / fr / es / zh) now at full parity (731 keys each) — bundled into `v0.5.5` (PyPI 2026-05-10) |
 | 📋 Planned | [Phase 14 — Multi-Stage Pipeline Chains](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO chained config, pipeline provenance artifacts → `v0.6.0` |
@@ -33,7 +33,7 @@ Originally planned as four sequential PyPI tags (`v0.5.0` / `v0.5.1` / `v0.5.2`
 
 **Current state:** 19 phases (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12, 12.5, 12.6, 22) shipped on PyPI under `v0.5.5`.  2 phases (13, 14) planned post-release.
 
-> **Phase 12.6 / Faz dual-axis note:** Phase 12.6 is itself a 38-task closure cycle (Faz 1-38) tracked at [`roadmap/phase-12-6-closure-cycle.md`](roadmap/phase-12-6-closure-cycle.md); per-wave PR descriptions carry the closure-task delta.
+> **Phase 12.6 / Faz dual-axis note:** Phase 12.6 is itself a 38-task closure cycle (Faz 1-38) tracked at [`roadmap/completed-phases.md`](roadmap/completed-phases.md); per-wave PR descriptions carry the closure-task delta.
 
 ## Quick summary of what's planned
 
@@ -85,14 +85,7 @@ docs/
 ├── roadmap.md                                  # This file — short index
 ├── roadmap-tr.md                               # Turkish mirror
 └── roadmap/
-    ├── completed-phases.md                     # Phase 1-10 archive (detailed)
-    ├── phase-10-post-training.md               # Completed — v0.4.0
-    ├── phase-10-5-quickstart.md                # Done (Phase 10.5) — shipped as v0.4.5
-    ├── phase-11-data-ingestion.md              # Done (Phase 11) — consolidated into v0.5.0
-    ├── phase-11-5-backlog.md                   # Done (Phase 11.5) — consolidated into v0.5.0; ingestion/audit polish
-    ├── phase-12-data-curation-maturity.md      # Done (Phase 12 Tier 1) — consolidated into v0.5.0; MinHash LSH, markdown splitter, secrets scan
-    ├── phase-12-5-backlog.md                   # Done (Phase 12.5) — consolidated into v0.5.0; Presidio adapter, Croissant metadata, --all-mask, wizard audit-first
-    ├── phase-12-6-closure-cycle.md             # Done — 38 fazlar / 5 waves bundled into v0.5.5
+    ├── completed-phases.md                     # Phase 1-12.6 archive (detailed) — Phase 10 / 10.5 / 11 / 11.5 / 12 / 12.5 / 12.6 absorbed inline (each shipped as v0.4.0 / v0.4.5 / v0.5.0 / v0.5.5)
     ├── phase-13-pro-cli.md                     # Planned — v0.6.0-pro (gated)
     ├── phase-14-pipeline-chains.md             # Planned — v0.6.0 (follow-up to the v0.5.5 closure cycle)
     ├── releases.md                             # v0.3.0 → v0.6.0 release notes
diff --git a/docs/roadmap/completed-phases.md b/docs/roadmap/completed-phases.md
index 637305ee..0228df16 100644
--- a/docs/roadmap/completed-phases.md
+++ b/docs/roadmap/completed-phases.md
@@ -640,17 +640,646 @@ graph TD
 
 ---
 
-## Phase 10: Post-Training Completion ✅ (v0.4.0)
+## Phase 10: Post-Training Completion
 
-> **Ayrıntılar:** [phase-10-post-training.md](phase-10-post-training.md)
+> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md).
 
-5 görev, 5 yeni modül, 89 yeni test. `inference.py`, `chat.py`, `fit_check.py`, `export.py`, `deploy.py`. CLI subcommand mimarisi (`forgelm chat / export / deploy`), `--fit-check` flag. Nisan 2026.
+**Goal:** Close the "trained, now what?" gap. After a fine-tune finishes, users should be able to sanity-check, export, and hand the model to a serving runtime (Ollama, vLLM, TGI) without leaving ForgeLM.
+**Estimated Effort:** Medium (2-3 months)
+**Priority:** High — single biggest post-9 UX gap; foundation for Phase 12 (quickstart)
 
-**Tasks:**
-1. [x] `forgelm/inference.py` — `load_model`, `generate`, `generate_stream`, `logit_stats`, `adaptive_sample`
-2. [x] `forgelm chat` — streaming REPL, slash commands, rich rendering, Llama Guard routing
-3. [x] `forgelm export` — GGUF via llama-cpp-python, 6 quant levels, SHA-256 → model_integrity.json
-4. [x] `forgelm --fit-check` — VRAM estimator, FITS/TIGHT/OOM/UNKNOWN verdict, JSON output
-5. [x] `forgelm deploy` — ollama / vllm / tgi / hf-endpoints config dosyası üretimi
+> **Context:** External analyses of two adjacent projects (QKV-Core, Trion) plus internal retrospectives converged on the same finding: ForgeLM stops at `output_dir/` with an HF-format adapter/merged model, but the user's actual journey continues to sanity chat → quantization → serving. Competitors (Axolotl, Unsloth) leave this to external tooling. Owning this handoff — without rewriting the inference ecosystem — is a high-value, low-risk addition.
+
+**Status: ✅ Complete** — shipped in `v0.4.0` (April 2026)
+
+#### Tasks:
+
+1. [x] **`forgelm/inference.py` — generation + logit statistics + adaptive sampling**
+   Core API: `load_model(path, adapter=None, backend="transformers")`, `generate(model, tokenizer, prompt, **kwargs)`, `generate_stream(...)` (streaming via `TextIteratorStreamer`), `logit_stats(logits) -> {entropy, top1_prob, effective_vocab}`, `adaptive_sample(logits, temperature, top_k, top_p, entropy_threshold=6.5)`. Chat template reuse via `tokenizer.apply_chat_template`. Fallback to `"role: content"` join when no template. Shared by `chat.py`, `judge.py`, `synthetic.py`.
+   ```python
+   from forgelm.inference import load_model, generate
+   model, tok = load_model("./outputs/my_run", adapter="./outputs/my_run/adapter_model")
+   text = generate(model, tok, "Hello", max_new_tokens=200, temperature=0.7)
+   ```
+
+2. [x] **`forgelm chat` — interactive terminal loop**
+   Terminal REPL in `forgelm/chat.py`: streaming output (default), `/reset`, `/save [file]`, `/temperature 0.x`, `/system <prompt>`, `/help` commands. `rich` optional rendering. History management with 50-pair cap. The `--safety` per-turn screen flag is planned for v0.6.0+ Pro CLI (today's safety pipeline runs through the YAML `safety:` block during training/eval).
+   ```bash
+   forgelm chat ./outputs/my_run
+   ```
+
+   `forgelm chat`'s shipping form takes a positional checkpoint path
+   plus optional `--adapter`. The per-turn Llama Guard screen via
+   `--safety` is planned for v0.6.0+ Pro CLI (see Phase 13 roadmap);
+   today operators get the same screening by enabling
+   `safety: enabled: true` in the YAML config the chat REPL reads.
+   The flag-form preview (`forgelm chat ... --safety`) is NOT
+   runnable today.
+
+3. [x] **`forgelm export` — HF → GGUF conversion**
+   Wraps `llama-cpp-python`'s `convert_hf_to_gguf.py`; no reimplementation. Handles adapter merge (LoRA + base → merged fp16) before conversion. Supports quants: `q2_k`, `q3_k_m`, `q4_k_m`, `q5_k_m`, `q8_0`, `f16`. SHA-256 of output artifact appended to `model_integrity.json`. Optional dependency: `pip install forgelm[export]`.
+   ```bash
+   forgelm export ./outputs/my_run --format gguf --quant q4_k_m --output model.gguf
+   ```
+
+4. [x] **`--fit-check` — VRAM fit advisor**
+   Pre-flight memory estimator in `forgelm/fit_check.py`. Detects GPU via `torch.cuda.mem_get_info()`. Estimates peak VRAM = base (params × dtype) + LoRA adapter + optimizer state (AdamW/8bit/GaLore variants) + activations (with gradient-checkpointing scaling). Produces verdict (FITS / TIGHT / OOM / UNKNOWN) with ordered recommendations. Falls back to hypothetical mode when no GPU is detected.
+   ```bash
+   forgelm --config my.yaml --fit-check
+   # → GPU: RTX 3060 12GB; Estimated peak: 10.8 GB; Verdict: ✅ FITS
+   forgelm --config my.yaml --fit-check --output-format json
+   ```
+
+5. [x] **`forgelm deploy` — serving handoff config generation**
+   Template-based config generation in `forgelm/deploy.py`; does not run the server. Targets: `ollama` (Modelfile), `vllm` (engine config YAML), `tgi` (docker-compose.yaml), `hf-endpoints` (JSON spec). All targets support `--output-format json`.
+   ```bash
+   forgelm deploy ./outputs/my_run --target ollama --output ./Modelfile
+   forgelm deploy ./outputs/my_run --target vllm --output ./vllm_config.yaml
+   forgelm deploy ./outputs/my_run --target tgi --output ./docker-compose.yaml
+   forgelm deploy ./outputs/my_run --target hf-endpoints --output ./endpoint.json
+   ```
+
+#### Requirements:
+- All five modules must work without GPU for config generation (fit-check excepted — it reads GPU but doesn't require one, falls back to hypothetical mode).
+- `inference.py` and `chat.py` share the same load/generate primitives with `safety.py`, `judge.py`, and `synthetic.py`; refactor duplicated `model.generate()` calls into the new module.
+- Each CLI command supports `--output-format json` for pipeline integration.
+- `pip install forgelm[export]` is optional; core install must not require `llama-cpp-python`.
+- Windows/Linux/macOS compatibility for all CLI surface (GGUF export may require specific toolchains, document clearly).
+
+#### Delivery:
+- Target release: `v0.4.0` ("Post-Training Completion")
+- Each task = independent PR with tests; no cross-task blocking dependencies.
+
+---
 
 ---
+
+## Phase 10.5: Quickstart Layer & Onboarding
+
+> **Status:** ✅ **DONE** — shipped as `v0.4.5` on 2026-04-26 (PyPI). Module: [`forgelm/quickstart.py`](../../forgelm/quickstart.py); five bundled templates under [`forgelm/templates/`](../../forgelm/templates/); CLI: `forgelm quickstart <template>`; tests: [`tests/test_quickstart.py`](../../tests/test_quickstart.py); CI smoke in [nightly.yml](../../.github/workflows/nightly.yml).
+
+> **Note:** This file details a single phase. For a summary of all phases, see [../roadmap.md](../roadmap.md).
+> **Filename history:** Originally `phase-12-quickstart.md` (the slot Quickstart held in early planning); renamed to (see relevant Phase section above/below) in the v0.5.2 cycle so the filename matches the current phase number. The Phase 12 slot now belongs to [Data Curation Maturity](#phase-12-data-curation-maturity).
+
+**Goal:** Make "my first fine-tune" a 10-minute experience. One command, one model in the end, zero YAML writing. Without sacrificing the CI/CD-native core — quickstart generates a YAML the user can later customize.
+**Estimated Effort:** Medium (1-2 months) — **Actual: 1 week**
+**Priority:** Critical — community flywheel; directly drives EU AI Act enterprise pipeline
+
+> **Phase ordering rationale:** Reprioritized from Phase 12 to Phase 10.5. Quickstart is the primary community growth driver; stars → enterprise leads → compliance sales. EU AI Act enforcement (August 2, 2026) creates a closing window. This phase must ship before Data Ingestion (Phase 11).
+
+> **Context:** Strategic decision documented in the internal enterprise-vs-simple paradox analysis: ForgeLM adds a "Layer 0" entry point without changing its CI/CD-native identity. The same YAML schema, the same trainer, the same outputs — just wrapped in pre-built templates and opinionated defaults. Depends on Phase 10 (`chat`) for end-of-training sanity loop.
+
+#### Tasks:
+
+1. [x] **`forgelm/quickstart.py` + `forgelm quickstart <template>` CLI**
+   Takes a template name, optional model override, optional dataset override. Generates a `my_run.yaml` under `./configs/` and immediately invokes `forgelm --config ./configs/my_run.yaml`. On completion, auto-invokes `forgelm chat` unless `--no-chat` flag. Transparent about what it did — prints generated YAML path.
+   ```bash
+   forgelm quickstart customer-support
+   forgelm quickstart code-assistant --model Qwen/Qwen2.5-Coder-7B-Instruct
+   forgelm quickstart --list
+   ```
+
+2. [x] **Template library: `forgelm/templates/` + bundled sample datasets**
+   Initial five templates, each = YAML config + sample JSONL (100-500 examples, license-clean):
+   - `customer-support` (Qwen/Qwen2.5-7B-Instruct primary, HuggingFaceTB/SmolLM2-1.7B-Instruct fallback, 58 examples, QLoRA r=8, ~15 min on RTX 3060)
+   - `code-assistant` (Qwen/Qwen2.5-Coder-7B-Instruct primary, Qwen/Qwen2.5-Coder-1.5B-Instruct fallback, 59 examples, QLoRA, ~25 min)
+   - `domain-expert` (Qwen/Qwen2.5-7B-Instruct primary, HuggingFaceTB/SmolLM2-1.7B-Instruct fallback, BYOD — no bundled dataset)
+   - `medical-qa-tr` (Qwen/Qwen2.5-7B-Instruct primary, Qwen/Qwen2.5-1.5B-Instruct fallback, 49 TR examples; Turkish-language flagship)
+   - `grpo-math` (Qwen/Qwen2.5-Math-7B-Instruct primary, Qwen/Qwen2.5-Math-1.5B-Instruct fallback, 40 prompts with gold_answer field, GRPO with built-in format+correctness reward, ~45 min)
+   Each template must produce a working model on an 8-12 GB consumer GPU. `fit_check` integration: if GPU too small, quickstart auto-downsizes model choice.
+
+3. [x] **Conservative default policy for quickstart**
+   All templates ship with: QLoRA 4-bit NF4, rank=8, batch=1 with gradient accumulation, gradient checkpointing on, safety eval off (opt-in only), compliance artifacts off (opt-in only). Rationale: minimize "GPU OOM on first run" and "compliance scared me off" failure modes.
+
+4. [x] **Wizard integration — template selector first**
+   `forgelm --wizard` opens with "Start from a template?" question. If yes → pass to quickstart flow. If no → existing 10-question flow. Merges the two paths.
+
+5. [x] **End-to-end smoke test in CI**
+   Nightly CI runs: `forgelm quickstart customer-support --dry-run` for each template. Validates YAML generation + dataset parse + config validation. No GPU required (dry-run). Catches template drift early.
+
+#### Requirements:
+- Sample datasets must be license-clean (CC-BY-SA 4.0 or similar permissive, documented in `forgelm/templates/LICENSES.md`).
+- Each template has a companion YouTube video (scheduled in marketing roadmap, not this roadmap).
+- Templates are a foundation for community contributions: `CONTRIBUTING.md` should document how to add new templates; each template is an atomic PR.
+- Quickstart must not introduce a "quickstart vs real training" bifurcation — same underlying code paths, same YAML schema.
+
+#### Delivery:
+- Target release: `v0.4.5` ("Quickstart Layer")
+- Blocks on Phase 10 tasks 1 + 2 (`inference.py` and `chat.py`). Phase 10 tasks 3-5 (export, fit-check, deploy) can develop in parallel.
+
+---
+
+---
+
+## Phase 11: Document Ingestion & Data Audit
+
+> **Status:** ✅ **DONE** — shipped as `v0.5.0` (PR #11 merged to `main` 2026-04-27).
+> Modules: [`forgelm/ingestion.py`](../../forgelm/ingestion.py),
+> [`forgelm/data_audit.py`](../../forgelm/data_audit/); CLI:
+> `forgelm ingest <path>` + `forgelm --data-audit <path>`; tests:
+> [`tests/test_ingestion.py`](../../tests/test_ingestion.py),
+> [`tests/test_data_audit.py`](../../tests/test_data_audit.py); docs:
+> [`docs/guides/ingestion.md`](../guides/ingestion.md),
+> [`docs/guides/data_audit.md`](../guides/data_audit.md). Follow-up
+> work tracked in [Phase 11.5 backlog](#phase-115-ingestion-audit-polish).
+>
+> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların
+> özeti için [../roadmap.md](../roadmap.md).
+
+**Goal:** Turn raw domain documents (PDF, DOCX, EPUB, TXT, plus structured sources) into training-ready JSONL, with automatic data quality reports that plug into EU AI Act Article 10 data governance.
+**Estimated Effort:** Medium (1-2 months) — **Actual: 1 day**
+**Priority:** High — enterprise onboarding accelerator; bridges ingestion → training → compliance audit in one tool.
+
+> **Context:** Dataset loading today goes through HuggingFace `load_dataset` + JSONL/CSV/Parquet. Enterprises arriving with directories of PDFs (legal, medical, policy manuals) have to write custom preprocessing. This module removes that friction and simultaneously generates governance artifacts that satisfy Article 10 (data collection method, quality metrics, bias declarations).
+
+### Tasks
+
+1. [x] **`forgelm/ingestion.py` — multi-format → JSONL**
+   Parsers for PDF (`pypdf`), DOCX (`python-docx`, including table cells), EPUB (`ebooklib` + `beautifulsoup4`), plain TXT, Markdown. Chunking strategies as shipped: `sliding` (fixed character window with `--overlap`) and `paragraph` (greedy paragraph packer; default). `semantic` is reserved for a follow-up phase and intentionally hidden from the CLI `--strategy` choice list — it raises `NotImplementedError` if invoked programmatically. Output is `{"text": "<chunk>"}` JSONL — recognized by `forgelm/data.py` as pre-formatted SFT input without further preprocessing. Optional dependency group: `pip install forgelm[ingestion]`.
+   ```bash
+   forgelm ingest ./book.epub --chunk-size 2048 --strategy paragraph --output data/sft.jsonl
+   forgelm ingest ./policies/ --recursive --output data/policies.jsonl
+   ```
+
+2. [x] **`forgelm/data_audit.py` — dataset quality & governance report**
+   Analyzes a JSONL dataset, produces `data_audit_report.json` with: sample count per split, column schema, text length distribution (min/max/mean/p50/p95), language detection (top-3), duplicate / near-duplicate rate (simhash-based), null/empty rate, PII flag counts (regex-based; optional `presidio` integration). Feeds Phase 8 Article 10 artifact (`data_governance_report.json`).
+   ```bash
+   forgelm --data-audit data/sft.jsonl --output audit/
+   ```
+
+3. [x] **PII detection hooks**
+   Regex-based detector for: emails, phone numbers (international formats), credit cards (Luhn-validated), IBAN, national IDs (TR, DE, FR, US SSN). Counts flags per sample; optionally masks via `--pii-mask`. Does not block training by default — surfaces in audit report.
+
+4. [x] **Near-duplicate detection across splits**
+   Simhash / MinHash across train/validation/test. Reports overlap rate. Critical for fair benchmarking — train-test leakage is a silent quality killer.
+
+### Requirements
+- Ingestion must handle malformed files gracefully (scan PDFs with no text layer → warning + empty result, not crash).
+- Audit runs on CPU; no GPU required.
+- All outputs integrate with Phase 8 compliance artifacts — data governance report references the audit JSON.
+- OCR is out of scope; document this as a limitation and suggest external tooling (Tesseract, AWS Textract).
+
+### Delivery
+- Target release: `v0.5.0`
+- Can start after Phase 10.5 (Quickstart) lands; no hard blocker on code, but UX sequencing matters.
+
+---
+
+---
+
+## Phase 11.5 — Ingestion / Audit Polish
+
+> **Note (post-consolidation):** Originally targeted `v0.5.1`, now ships
+> as part of the consolidated `v0.5.0` release alongside Phases 11, 12,
+> and 12.5 — see [releases.md](releases.md#v050-document-ingestion-data-curation-pipeline).
+> Version-label references below preserve the historical planning trail.
+>
+> **Status:** ✅ Landed for the (originally) `v0.5.1` cycle. All 12 follow-ups carved
+> out of Phase 11's review backlog have shipped. Modules touched:
+> [`forgelm/data_audit/`](../../forgelm/data_audit/),
+> [`forgelm/ingestion.py`](../../forgelm/ingestion.py),
+> [`forgelm/cli/`](../../forgelm/cli/),
+> [`forgelm/wizard/`](../../forgelm/wizard/); CLI:
+> `forgelm audit <path>` (new subcommand, with `--data-audit` preserved
+> as deprecation alias) + token-aware `forgelm ingest` flags; tests:
+> [`tests/test_data_audit.py`](../../tests/test_data_audit.py),
+> [`tests/test_ingestion.py`](../../tests/test_ingestion.py),
+> [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py),
+> [`tests/test_wizard_byod.py`](../../tests/test_wizard_byod.py).
+
+**Goal:** Operational polish on top of `v0.5.0`'s ingestion + audit
+surface — no new training capabilities, but materially better handling
+for large corpora and a cleaner CLI shape.
+
+### What landed
+
+| # | Item | Where it lives | One-line takeaway |
+|---|---|---|---|
+| **1** | LSH banding for near-duplicate detection | `find_near_duplicates`, `_count_leaked_rows` in [`data_audit.py`](../../forgelm/data_audit/) | Pigeonhole-banded LSH (default `bands = threshold + 1`). Drops within-split + cross-split scans from `O(n²)` to ~`O(n × k)`; brute-force fallback when bands shrink below 4 bits. |
+| **2** | Streaming `_read_jsonl_split` | [`data_audit.py`](../../forgelm/data_audit/) | Reader is now a generator yielding `(row, parse_err, decode_err)`; `_audit_split` consumes it row-by-row via a `_StreamingAggregator` so RAM stays bounded on multi-million-row splits. |
+| **3** | Token-aware `--chunk-tokens` | [`ingestion.py`](../../forgelm/ingestion.py), [`cli.py`](../../forgelm/cli/) | New `--chunk-tokens N` + `--tokenizer MODEL` flags on `forgelm ingest`. Chunks are sized via `AutoTokenizer.encode` instead of raw character counts so they line up with `model.max_length` exactly. |
+| **4** | PDF page-level header / footer dedup | `_strip_repeating_page_lines` in [`ingestion.py`](../../forgelm/ingestion.py) | Lines that recur as the first or last non-empty line on ≥ 70 % of a PDF's pages are stripped. Reduces audit near-duplicate noise on long policy / book PDFs. |
+| **5** | Token-level `lru_cache` memo | `_token_digest` in [`data_audit.py`](../../forgelm/data_audit/) | Per-token digest is cached at module scope (`maxsize=10_000`). Distinct tokens follow Zipf, so ~10 K cache slots cover most corpus traffic. |
+| **6** | xxhash backend for simhash | `_token_digest` in [`data_audit.py`](../../forgelm/data_audit/) | Optional `xxhash` import (added to the `[ingestion]` extra) drives the digest path when present; BLAKE2b is preserved as the fallback. |
+| **7** | `forgelm audit` proper subcommand | [`cli.py`](../../forgelm/cli/) | New `forgelm audit PATH` (with `--verbose`, `--near-dup-threshold`, `--output`). The legacy `--data-audit FLAG` keeps working as a deprecation alias (logs a one-line notice). |
+| **8** | PII severity tiers | `PII_SEVERITY`, `_build_pii_severity` in [`data_audit.py`](../../forgelm/data_audit/) | Audit JSON now carries `pii_severity` with `worst_tier`, `by_tier`, and `by_type`. Notes line lead with the worst tier (e.g. `WORST tier: CRITICAL`). |
+| **9** | `summarize_report` truncation policy | [`data_audit.py`](../../forgelm/data_audit/) | Default `verbose=False` folds zero-finding splits into a single tail line. CLI exposes `--verbose` on the new `audit` subcommand for full output. |
+| **10** | Structured ingestion notes | `IngestionResult.notes_structured` in [`ingestion.py`](../../forgelm/ingestion.py) | Free-text `extra_notes` stays for humans; new `notes_structured` carries machine-readable `{key: value}` for CI/CD consumers. JSON output already exposes both. |
+| **11** | Wizard "ingest first" entry point | `_offer_ingest_for_directory` + `_prompt_dataset_path_with_ingest_offer` in [`forgelm/wizard/_byod.py`](../../forgelm/wizard/_byod.py) | Both BYOD quickstart and the full 9-step wizard now offer to run `ingest` inline when the typed path is a directory of raw documents. |
+| **12** | Atomic audit-report write | `_atomic_write_json` in [`data_audit.py`](../../forgelm/data_audit/) | Writes via `tempfile.NamedTemporaryFile` + `os.replace` so a crashed audit can never leave a half-written `data_audit_report.json` on disk. |
+
+### Measured speedups (xxhash + lru_cache hot path)
+
+Local microbenchmark on Apple Silicon, Python 3.11.2, xxhash 3.7.0
+(median of 21 runs, 50 K hashes per round; end-to-end uses 1 K texts of
+50–150 Zipfian-English tokens with the cache cleared between runs):
+
+| Scenario                                | Speedup (xxh3 vs blake2b) |
+| --------------------------------------- | ------------------------- |
+| Raw digest, short keys (2–6 chars)      | 1.31×                     |
+| Raw digest, Zipfian English (~3 chars)  | 1.34×                     |
+| Raw digest, long keys (40–80 chars)     | 1.33×                     |
+| End-to-end `compute_simhash` (cache cleared) | 1.05×                |
+
+xxhash's well-known "4–10× faster than crypto hashes" figure refers to
+C-level pure-hash benchmarks; the Python wrapping (UTF-8 encode → call →
+`intdigest`) levels the field. The bigger wall-clock win in real audits
+comes from the token-level `lru_cache` — Zipfian token frequency means
+~10 K cache slots cover the vast majority of a corpus's traffic, so a
+second pass over the same corpus runs almost entirely from cache.
+
+The benchmark script is at `tools/bench_simhash.py` (run with
+`python tools/bench_simhash.py`); it is not part of the regular `pytest`
+suite because it is wall-clock-noisy.
+
+### Behavioural deltas worth highlighting
+
+- **Default near-duplicate detection is now LSH-banded.** Behaviour at
+  the default `threshold=3` is identical to the old quadratic scan
+  (pigeonhole gives exact recall), but the cost on a 100 K row corpus
+  drops from "tens of seconds, gigabytes of comparisons" to ~seconds.
+- **Audit output JSON adds `pii_severity`.** Existing consumers that
+  read only `pii_summary` keep working — the new field is additive.
+  Pipelines that want a one-glance verdict should read
+  `pii_severity.worst_tier` and gate on `critical` / `high`.
+- **`forgelm audit PATH` is the recommended invocation.** The
+  `--data-audit` top-level flag continues to work but logs a one-line
+  deprecation notice. Plan to remove it no earlier than `v0.7.0`.
+- **`--chunk-tokens` requires `--tokenizer`.** Token-aware chunking
+  needs to know which vocab to count against; we refuse to default to a
+  hidden tokenizer because the chunk count would silently differ
+  per-model. Set both or neither.
+- **PDF dedup is opt-out by being short-doc-tolerant.** Documents
+  with fewer than 3 pages skip the dedup step entirely; the statistical
+  signal is too weak to distinguish "header" from "actual repetition"
+  on small docs.
+
+### What's next
+
+`v0.5.2` ([Phase 12 — Data Curation Maturity](#phase-12-data-curation-maturity)) is the direct continuation of this lineage: MinHash LSH dedup for >50K-row corpora, markdown-aware splitter, code/secrets leakage scan, heuristic quality filter, DOCX/Markdown table preservation. Driven by the post-`v0.5.1` competitive review that compared ForgeLM's ingestion + audit against LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling.
+
+`v0.5.3` ([Phase 14 — Multi-Stage Pipeline Chains](phase-14-pipeline-chains.md)) was reslotted from `v0.5.2` so the ingestion/audit lineage finishes uninterrupted before the trainer-orchestration surface gets reshaped.
+
+---
+
+## Phase 12: Data Curation Maturity
+
+> **Note (post-consolidation):** Originally targeted `v0.5.2`, now ships
+> as part of the consolidated `v0.5.0` release alongside Phases 11, 11.5,
+> and 12.5 — see [releases.md](releases.md#v050-document-ingestion-data-curation-pipeline).
+> Version-label references below preserve the historical planning trail.
+>
+> **Status:** ✅ **Tier 1 DONE** — landed on `development` for the (originally) `v0.5.2` cycle. All five must-have tasks shipped: MinHash LSH dedup option (`[ingestion-scale]` extra via `datasketch`), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`[ingestion-secrets]` extra via `detect-secrets` with regex fallback), heuristic quality filter (`--quality-filter`), DOCX/Markdown table preservation. Tier 2 (Presidio adapter, Croissant metadata) and Tier 3 (`--all-mask` composite, wizard "audit first" hook) are deferred to a follow-up **Phase 12.5** backlog file (analogous to Phase 11.5 → (see relevant Phase section above/below)). Modules: [`forgelm/data_audit.py`](../../forgelm/data_audit/), [`forgelm/ingestion.py`](../../forgelm/ingestion.py), [`forgelm/cli.py`](../../forgelm/cli/); tests: [`tests/test_data_audit_phase12.py`](../../tests/test_data_audit_phase12.py), [`tests/test_ingestion_phase12.py`](../../tests/test_ingestion_phase12.py); CLI tests added in [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py).
+
+> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md). Phase 11 + 11.5 built the ingestion / audit lineage (Phase 11 → `v0.5.0`, Phase 11.5 → `v0.5.1`); this phase moves the same lineage from **enterprise-acceptable** to **enterprise-competitive**.
+
+**Goal:** Mature ForgeLM's `forgelm ingest` + `forgelm audit` layer along three axes — **scale** (LSH-based near-duplicate detection beyond ~50K rows, large-corpus throughput), **security** (code/secret leakage scanning + optional ML-based PII), and **quality** (markdown-aware chunking + heuristic quality filters + table structure preservation). The competitive review that followed Phase 11.5 (see `docs/roadmap/phase-11-5-backlog.md` "Measured speedups" section + the 2026-04-27 ingestion-comparison synthesis) lists the exact gaps this phase closes.
+
+**Estimated Effort:** Medium (4-6 weeks) — **Actual: ~1 day** (single-author implementation, leveraging the streaming aggregator + tier-mapped pattern from Phase 11.5).
+**Priority:** High — answers the enterprise demand surfaced after the `v0.5.0` PyPI launch; sequences naturally with Phase 14 (Multi-Stage Pipeline Chains), which is reslotted to `v0.5.3`.
+
+> **Context:** Phase 11 shipped multi-format extraction (PDF/DOCX/EPUB/TXT/MD) + paragraph/sliding chunkers; Phase 11.5 added token-aware chunking, PDF page-level header/footer dedup, the `forgelm audit` subcommand, PII severity tiers, LSH-banded simhash dedup, and atomic JSON writes. The cross-tool comparison (LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling) found ForgeLM **uncontested** in the *fine-tuning + compliance* niche but **behind** in four concrete areas: (1) MinHash LSH dedup for >50K-row corpora, (2) heading-preserving markdown chunking, (3) code / credential leakage scanning, (4) DOCX/PDF table structure preservation. This phase closes those four. Layout-aware PDF parsing (Marker/Docling delegation) and embedding-based semantic dedup are **deliberately deferred to Phase 13+** — adding either would require runtime ML dependencies that conflict with the project's "we don't write our own quantization / VLM" boundary (codified in `CLAUDE.md` "What ForgeLM is not") and the air-gapped reproducibility guarantees Annex IV depends on.
+
+### Tasks
+
+#### Tier 1 — Must-have (Phase 12's thesis)
+
+1. [x] **MinHash LSH dedup option** (`[ingestion-scale]` extra, `datasketch>=1.6.0,<2.0.0`)
+   `find_near_duplicates` and `_count_leaked_rows` keep simhash + LSH banding as the **default**; an opt-in `--dedup-method minhash --jaccard-threshold 0.85` route delegates to [datasketch](https://github.com/ekzhu/datasketch) `MinHashLSH`. Simhash is ideal up to ~50K rows; MinHash LSH is the industry standard above that scale (NeMo Curator, Dolma, RedPajama all use it). Surface contract:
+   ```bash
+   forgelm audit data/large_corpus.jsonl --dedup-method minhash --jaccard-threshold 0.85
+   ```
+   ```python
+   # Programmatic:
+   forgelm.data_audit.audit_dataset(..., dedup_method="minhash", minhash_jaccard=0.85)
+   ```
+   `cross_split_overlap` and `near_duplicate_pairs` share the same method parameter. Audit JSON gains `near_duplicate_summary.method: "minhash" | "simhash"`; default-method audits stay **schema-additive** (older parsers reading `pairs_per_split` keep working unchanged) — the on-disk JSON is *not* byte-identical because `near_duplicate_summary.method` and `cross_split_overlap.method` are now always present alongside the existing fields.
+
+2. [x] **Markdown-aware splitter** (new third strategy: `--strategy markdown`)
+   `_chunk_markdown(text, max_chars_or_tokens, ...)` parses heading hierarchy (`# H1` / `## H2` / `### H3`); breaks chunks at heading boundaries; inlines the heading path **into the chunk body** (`# H1 / ## H2\n\n…`) rather than as a separate metadata field — output stays `{"text": "..."}` JSONL so SFT loss benefits from the heading signal. Code-block (` ``` `) and list-item boundaries are preserved (no mid-code-block splits). Composes with token-aware mode: `--strategy markdown --chunk-tokens 1024 --tokenizer Qwen/Qwen2.5-7B-Instruct`. Existing `paragraph` and `sliding` behaviour stays byte-identical.
+
+3. [x] **Code / secrets leakage tagger** (`[ingestion-secrets]` extra, `detect-secrets>=1.5.0,<2.0.0`)
+   Audit gains a `secrets_summary` block: AWS / GCP / Azure access keys, GitHub / GitLab / Slack tokens, OpenSSH / PGP private-key headers, JWT, OpenAI API keys (`sk-…`), generic high-entropy strings. Audit JSON shape:
+   ```json
+   {
+     "secrets_summary": {
+       "total": 3,
+       "by_type": {"aws_access_key": 1, "github_token": 2},
+       "lines_flagged": 3
+     }
+   }
+   ```
+   Ingest side: `--secrets-mask` flag mirrors `--pii-mask`'s helper pattern, replacing detected spans with `[REDACTED-SECRET]`. The `detect-secrets` package is optional; without it a regex-only fallback set (~10 common patterns) runs and an INFO log says *"install `forgelm[ingestion-secrets]` for full coverage"*. Compliance angle is **critical** — credentials leaked into an SFT corpus are memorised by the trained model; Phase 12 is the first line of defence for this risk class.
+
+4. [x] **Heuristic quality filter** (audit-side, opt-in `forgelm audit --quality-filter`)
+   Classic Gopher / C4 / RefinedWeb heuristics: mean-word-length (flag if outside 3-12 chars), alphabetic-character ratio (< 70 % → flag), end-of-line punctuation ratio (< 50 % → flag), repeated-line ratio (top-3 distinct lines covering > 30 % of non-empty lines → flag), short-paragraph ratio (`\n\n`-separated blocks with < 5 words, > 50 % of total → flag). Markdown fenced code blocks are stripped before heuristics run so legitimate code rows don't trip the prose-oriented checks. Opt-in default-off; new `quality_summary`:
+   ```json
+   {
+     "quality_summary": {
+       "samples_flagged": 47,
+       "by_check": {
+         "low_alpha_ratio": 12,
+         "low_punct_endings": 8,
+         "abnormal_mean_word_length": 3,
+         "short_paragraphs": 27,
+         "repeated_lines": 5
+       },
+       "overall_quality_score": 0.94
+     }
+   }
+   ```
+   ML-based classifiers (NeMo Curator's fastText / DeBERTa quality model) are **out of scope** — deferred to Phase 13+ (model dependency, non-deterministic, reproducibility risk).
+
+5. [x] **DOCX / Markdown table preservation**
+   `_extract_docx` replaces the current `" | "` flat join with markdown table syntax:
+   ```text
+   | Header 1 | Header 2 | Header 3 |
+   |---|---|---|
+   | Cell A1  | Cell A2  | Cell A3  |
+   ```
+   PDF tables stay flat — `pypdf`'s table support is weak and Docling delegation is Phase 13+ scope. The Markdown extractor (`.md` route) already expects markdown, so the new strategy aligns naturally. SFT use cases where this matters (code-assistant, financial-assistant, tabular Q&A) get a noticeable lift; that lift is measured post-merge, not gated on Phase 12 acceptance.
+
+#### Tier 2 — Should-have (Phase 12 if scope allows; otherwise Phase 12.5)
+
+6. [ ] **Presidio adapter** (`[ingestion-pii-ml]` extra, optional)
+   ForgeLM keeps the regex + Luhn + TC Kimlik checksum PII detector as the **default**. `--pii-engine presidio` opts into Microsoft Presidio for the ML-NER signals regex misses (person names, organisations, locations). Presidio output maps into the existing `pii_severity` table with a new tier (`person_name` → medium, `organization` → low). Scope is ingest-side only; audit contract is unchanged. Fallback: missing Presidio → INFO log *"install `forgelm[ingestion-pii-ml]` for ML-based detection"*.
+
+7. [ ] **Croissant metadata compatibility** (audit JSON, optional)
+   Audit report gains a top-level `croissant_compatible: true` flag plus a subset of Google's [Croissant ML metadata](https://github.com/mlcommons/croissant) schema fields (`@type: "sc:Dataset"`, `name`, `description`, `recordSet`, …). Combined with the EU AI Act Article 10 governance bundle, this produces a **dual-standard** artifact — both Croissant consumers and AI Act auditors can parse the same file. Opt-in: `--croissant` flag or programmatic `croissant=True`. Existing audit consumers are unaffected (additive only).
+
+#### Tier 3 — Could-have (skip if scope is exhausted)
+
+8. [ ] **`forgelm ingest --secrets-mask` + `--pii-mask` composite flag**
+   Runs both masking passes sequentially in one ingest pass (secrets first — high-entropy spans masked; PII second — remaining spans). Order matters because some secrets (GitHub tokens) partially match PII regexes (`de_id`-shaped). Single-flag shorthand: `--all-mask` enables both. Test: known fixtures combining secrets + PII, roundtrip + masked-output coverage.
+
+9. [ ] **Wizard "audit first" entry point**
+   Phase 11.5 added the ingest-first hook. Phase 12 mirrors it for symmetry: when the user provides a JSONL path, the wizard offers to run `forgelm audit` automatically; the summary is printed to stdout and the user decides whether to proceed based on the leakage / PII / quality verdicts. UX shape: *"Detected 18 emails, 1 critical-tier PII (credit card), and 7 near-duplicate pairs in your dataset. Continue training?"*. New helper: `_offer_audit_for_jsonl`.
+
+### Won't-do (deliberately out of Phase 12 scope)
+
+- ❌ **VLM-based PDF parsing** (Marker / Docling / Nemotron-Parse) — Phase 13+ scope. ForgeLM holds the "we don't write our own VLM" line (codified in `CLAUDE.md` "What ForgeLM is not"); even external delegation (Docling) adds runtime weight + risks the air-gapped guarantee. Ships as a separate optional extra in a later phase.
+- ❌ **Embedding-based semantic dedup** (NeMo Curator `semantic.py` analogue) — runtime embedding-model dependency + non-deterministic chunk counts violate Annex IV reproducibility. Deferred to Phase 13+ (only viable if a deterministic-snapshot mode is designed first).
+- ❌ **Built-in OCR** — out of scope since Phase 11; docs already point at Tesseract / AWS Textract recipes. This stays unchanged.
+- ❌ **ML-based quality classifier** (fastText / DeBERTa) — non-deterministic + model-snapshot dependency. The heuristic filter in Tier 1 #4 is sufficient for this phase; classifiers are Phase 13+.
+- ❌ **GPU/Ray-scale execution** (NeMo Curator territory) — ForgeLM's niche is *small-to-medium corpus, enterprise compliance*. 8 TB pretraining curation is NeMo Curator's job; ForgeLM should be sufficient for 100K–1M-row SFT corpora, which Phase 12 (streaming + LSH) achieves without distributed runtime.
+- ❌ **HTML extractor** — useful for enterprise scrape (intranet wikis) but scope creep. Operators can pre-process with BeautifulSoup; ForgeLM doesn't need to ingest HTML directly.
+
+### Requirements
+
+- **Backward compatibility**: Default-flag `forgelm ingest` and `forgelm audit` outputs are **schema-additive** with v0.5.1 (older parsers keep working) — they are *not* byte-identical because new always-on fields (`secrets_summary`, `near_duplicate_summary.method`, `cross_split_overlap.method`) are now part of every report. v0.5.1 audit consumers must parse v0.5.2 reports without changes; the stdout JSON envelope retains the v0.5.1 `near_duplicate_pairs_per_split` key alongside the richer `near_duplicate_summary`.
+- **Optional extras**: Every new heavy dependency (`datasketch`, `detect-secrets`, `presidio-analyzer`) goes under `pyproject.toml` `[project.optional-dependencies]` with the `ImportError` + install-hint pattern from `docs/standards/architecture.md` §3.
+- **Determinism**: Every new path (MinHash, markdown chunker, secrets scan, quality heuristics) preserves the fixed-input → fixed-output contract. Annex IV reproducibility guarantee.
+- **CLI**: All new flags appear in `forgelm audit --help` and `forgelm ingest --help`; `--output-format json` envelope is additive.
+- **Compliance**: New audit fields (`secrets_summary`, `quality_summary`) are auto-inlined into the governance bundle by `forgelm/compliance.py::_maybe_inline_audit_report` without code changes — the existing `json.load` path passes them through as-is.
+- **Documentation**: `docs/guides/ingestion.md` + TR mirror, `docs/guides/data_audit.md` + TR mirror, `docs/qms/sop_data_management.md` (new SOP step for secrets scan + quality filter), `CHANGELOG.md`, `docs/reference/usage.md` + TR mirror, `docs/standards/architecture.md` extras matrix.
+- **Tests**: At least three tests per Tier 1 task (happy path + edge case + extras-skip). MinHash needs a `test_minhash_parity_with_simhash_at_default_threshold` (LSH parity-style). Markdown splitter needs a heading-preservation test. Secrets needs known-fixture roundtrip + mask test.
+- **Smoke**: `forgelm --config config_template.yaml --dry-run` must produce v0.5.1-equivalent output; new flags have no effect on dry-run.
+- **Lint + coverage**: ruff clean, coverage stays at `fail_under=40` (Phase 12 adds new code; tests must not drop the floor).
+
+### Kill criteria
+
+For the quarterly gate review:
+
+- **Tier 1 task #1 (MinHash LSH)**: If it doesn't land within 6 weeks **and** a 100K-row smoke fixture under `forgelm audit --dedup-method minhash` doesn't beat the brute-force O(n²) baseline by ≥ 5× → demote to Tier 2, keep simhash as default, push the MinHash extra to v0.5.3.
+- **Tier 1 task #4 (Quality filter)**: If false-positive rate on industry benchmark fixtures exceeds 10 % → opt-in default-off (already the plan), document the limitation, add a *"calibrate before applying"* note for operators.
+- **Compatibility regression**: If a v0.5.1 audit consumer (the Phase 11/11.5 compliance bundle inliner) cannot parse a v0.5.2 report → kill, roll back any non-additive changes.
+- **Performance regression**: If the default simhash path slows by > 5 % vs. the Phase 11.5 baseline (`tools/bench_simhash.py`) → revisit the refactor.
+
+If fewer than three Tier 1 items land within three months, Phase 12 is reset; the "Data Curation Maturity" thesis is re-examined (refresh the competitive analysis, ask whether it's still the right work).
+
+### Delivery
+
+- **Target release: `v0.5.2`** — natural continuation of Phase 11.5 (`v0.5.1`). Phase 14 (Multi-Stage Pipeline Chains) is reslotted from `v0.5.2` to `v0.5.3`.
+- Phase 14 reslot rationale: Phase 12 is an extension of the ingestion lineage and shares thematic continuity with Phase 11.5; Phase 14 is an independent feature whose 3-6-week scope can run after Phase 12 with a parallel implementer. Phase 14 has high enterprise demand, but the EU AI Act enforcement deadline (August 2026) gives the audit / secrets surface higher near-term weight.
+- Phase 13 (Pro CLI) `v0.6.0-pro` — after Phase 12 + 14, traction-gated.
+- Roadmap table (`docs/roadmap.md` + TR mirror), the mermaid diagram, and `releases.md` are all updated by this phase doc; this file pins those commitments.
+
+### Module touchpoints
+
+| Module | Change | Risk |
+|---|---|---|
+| `forgelm/data_audit.py` | `compute_minhash`, `find_near_duplicates_minhash`, `_count_leaked_rows_minhash` (parallel API surface); `secrets_summary` builder; `quality_summary` builder; `audit_dataset(..., dedup_method=...)` parameter | Low — additive; default behaviour preserved |
+| `forgelm/ingestion.py` | `_chunk_markdown`, `_strategy_dispatch` "markdown" branch; `_extract_docx` markdown-table output; `--secrets-mask` extractor wiring | Low-medium — DOCX output shape changes; v0.5.1 fixtures must update |
+| `forgelm/cli.py` | `--strategy markdown`, `--dedup-method`, `--jaccard-threshold`, `--quality-filter`, `--secrets-mask`, `--pii-engine`, `--croissant` flags | Low — argparse additions only |
+| `forgelm/wizard.py` | (Tier 3) `_offer_audit_for_jsonl` helper; BYOD path post-validation hook | Low — opt-in pattern, symmetric with the existing `_offer_ingest_for_directory` |
+| `pyproject.toml` | New extras: `[ingestion-scale]` (datasketch), `[ingestion-secrets]` (detect-secrets), `[ingestion-pii-ml]` (presidio-analyzer); version bump `0.5.1rc1 → 0.5.2rc1` | Low |
+| `docs/guides/{ingestion,data_audit}{,-tr}.md` | New sections: markdown splitter, secrets scan, quality filter, MinHash; legacy CLI patterns preserved | Low |
+| `docs/qms/sop_data_management.md` | Quality-check checklist gains `--quality-filter` + secrets-scan rows; v0.5.1 `forgelm audit` is already documented (Phase 11.5 update) | Low |
+| `docs/standards/architecture.md` | Extras matrix gains `ingestion-scale`, `ingestion-secrets`, `ingestion-pii-ml` rows | Low |
+| `CHANGELOG.md` | New "Unreleased — Phase 12 (Data Curation Maturity, targeting v0.5.2)" section | Low |
+
+### Suggested sequencing (4-6 week plan)
+
+| Week | Work | Output |
+|---|---|---|
+| 1 | Tier 1 #1 — MinHash LSH dedup + datasketch extra + tests | `compute_minhash`, parity test, `--dedup-method` flag |
+| 2 | Tier 1 #2 — Markdown splitter + token-aware composition + tests | `_chunk_markdown`, `--strategy markdown`, heading-preservation test |
+| 3 | Tier 1 #3 — Code/secrets scan + extra + ingest `--secrets-mask` + tests | `secrets_summary`, detect-secrets integration, mask roundtrip test |
+| 4 | Tier 1 #4 + #5 — Quality filter + DOCX table preservation + tests | `quality_summary`, markdown-table output, fixture tests |
+| 5 | Tier 2 #6 — Presidio adapter (if scope allows) + Tier 2 #7 Croissant metadata | `--pii-engine presidio`, `--croissant` flag |
+| 6 | Docs + roadmap + smoke + tag prep | Guides, CHANGELOG, releases.md, `v0.5.2rc1` |
+
+Tier 3 items (composite mask, wizard audit-first) either join Weeks 5-6 if scope permits, or move to a Phase 12.5 backlog file.
+
+---
+
+---
+
+## Phase 12.5 — Data Curation Polish Backlog
+
+> **Note (post-consolidation):** Originally targeted `v0.5.3`; all four
+> backlog items now ship together with Phases 11 / 11.5 / 12 in the
+> consolidated `v0.5.0` release (see [releases.md](releases.md#v050-document-ingestion-data-curation-pipeline)).
+> The version-label references below preserve the historical planning
+> trail.
+>
+> **Follow-up to Phase 12.** Phase 12 (originally targeted `v0.5.2`) shipped the five Tier 1
+> must-haves: MinHash LSH dedup option, markdown-aware splitter,
+> code/secrets leakage tagger, heuristic quality filter, DOCX/Markdown
+> table preservation. Three Tier 2/3 items were tagged "if scope allows"
+> in the [original Phase 12 plan](#phase-12-data-curation-maturity);
+> they didn't make the same release because the Tier 1 surface was
+> already a complete coherent ship and adding more would have grown the
+> review window without proportional value. This file pins them as the
+> follow-up backlog so a future minor release can pick them up without
+> reopening the Phase 12 plan.
+>
+> **Scope:** small additions only — none require new architecture.
+> Each row is one PR.
+
+| # | Item | Source | Effort | Status |
+|---|---|---|---|---|
+| **1** | ~~**Presidio adapter** (`[ingestion-pii-ml]` extra, optional)~~ | Phase 12 plan Tier 2 #6 | S–M | ✅ Landed on `development` — `forgelm audit --pii-ml`; new `PII_ML_SEVERITY` table; opt-in `[ingestion-pii-ml]` extra (`presidio-analyzer`); ships with `v0.5.0` (consolidated release). |
+| **2** | ~~**Croissant metadata compatibility** (audit JSON)~~ | Phase 12 plan Tier 2 #7 | S | ✅ Landed on `development` — `forgelm audit --croissant`; Croissant 1.0 card under report's `croissant` key; existing keys byte-equivalent when off. Ships with `v0.5.0`. |
+| **3** | ~~**`forgelm ingest --all-mask` composite flag**~~ | Phase 12 plan Tier 3 #8 | XS | ✅ Landed on `development` — `forgelm ingest --all-mask`; set-union with explicit flags; resolved at the CLI boundary. Ships with `v0.5.0`. |
+| **4** | ~~**Wizard "audit first" entry point**~~ | Phase 12 plan Tier 3 #9 | S | ✅ Landed on `development` — `_offer_audit_for_jsonl` invoked from the three JSONL-finalisation paths in `forgelm/wizard.py`. Ships with `v0.5.0`. |
+
+### Why these landed here, not in Phase 12
+
+- **Tier 2 (#1, #2)** add new optional dependencies (`presidio-analyzer`, plus a small Croissant schema mapping). Adding two new extras at once expands the install / extras-skip test matrix; carving them into their own PR keeps each behaviour individually reviewable. Neither closes a competitive gap that mattered for the `v0.5.2` ship — Phase 12's regex+Luhn+TC-Kimlik PII detector and the EU AI Act governance bundle covered the immediate compliance surface.
+- **Tier 3 (#3, #4)** are pure UX polish. They don't unlock anything the operator cannot do today by typing two flags or running `forgelm audit` themselves; they smooth the path. Worth doing, not worth gating Phase 12 on.
+
+### Picking up an item
+
+1. Open an issue referencing the row number above.
+2. PR scope: ONE row per PR.
+3. Update this file when the row lands — strike through and link the
+   commit / PR.
+4. If a row turns out to be the wrong shape, edit it here before doing
+   the work. Stale backlog rows are worse than missing rows.
+
+### Out of scope (still)
+
+The "Won't-do" list at the bottom of [(see Phase 12 — Data Curation Maturity section)](#phase-12-data-curation-maturity) is not weakened by this backlog. VLM PDF parsing, embedding-based semantic dedup, built-in OCR, ML quality classifiers, GPU/Ray scale, and HTML extractor stay out of scope as deliberately as Phase 12 declared them.
+
+---
+
+## Phase 12.6 — Closure Cycle (38 fazlar across 5 waves)
+
+> **Status:** ✅ Done — Faz 33 release publish remains as POST-WAVE.
+> **Bundled into:** [v0.5.5 release](releases.md#v055-closure-cycle-bundle-phase-22-wizard-site-documentation-sweep-2026-05-10).
+> **Source review:** v0.5.0 master code review (175 findings: 8 Critical + 67 Major + 60 Minor + 40 Nit) — distilled into the Faz 1-38 task list below.
+> **Target:** ★★★★★ across all 8 quality dimensions before v0.5.5 PyPI publish.
+
+### Why this exists as a single phase entry
+
+The v0.5.0 master code review surfaced **175 findings** plus **4 user-added scope items** (Library API support, ISO 27001 / SOC 2 alignment, GDPR right-to-erasure full implementation, Article 14 real staging). Rather than stretch these across 5 sequential patch releases, the maintainer chose **Path B — full Faz 1-38 sweep into a single v0.5.5 tag**:
+
+- Bisectable PR-per-faz history
+- One coherent surface (every faz feeds the same release candidate)
+- 5/5 quality bar reached before publish, not after
+
+The 38 fazlar were merged across **5 integration waves** (Wave 0/1 through Wave 5). Each wave landed via a dedicated PR onto `development`, then into `main`. This file is the index that maps every faz to its wave, integration PR, and merge SHA.
+
+### Scope (in / out)
+
+**In scope:**
+
+- All 175 master-review findings (Critical → Nit)
+- 4 user-added scope items: Library API, ISO 27001 / SOC 2, GDPR full implementation, Article 14 real staging + `forgelm approve`
+- 5 ghost-feature drift items surfaced during Wave 4 + 5 (GH-001 doctor, GH-002/003 air-gap pre-cache, GH-004/005/009 verification toolbelt, GH-007 approvals listing, GH-014 reverse-pii)
+- Documentation final pass: `docs/` EN+TR, `docs/usermanuals/{en,tr}/`, `site/*`, all 10 standards files, README + CONTRIBUTING + CLAUDE.md, roadmap + roadmap-tr.md
+
+**Explicitly out of scope:**
+
+- DE / FR / ES / ZH user-manual translation (deferred to a future cycle — bilingual policy formalised in [`docs/standards/localization.md`](../standards/localization.md))
+- Cloud SaaS product (separate offering)
+- New roadmap features: Phase 13 (Pro CLI) and Phase 14 (Pipeline Chains) work
+- Marketing / GTM expansion
+
+### Wave timeline
+
+| Wave | Branch | Integration PR | Merge SHA | Date | Net new tests |
+|---|---|---|---|---|---|
+| **Wave 0** (foundation) | `closure/wave1-integration` (early bundle) | PR #19 → `main` | (see PR #19) | 2026-04-30 | baseline |
+| **Wave 1** (foundation residuals) | `closure/wave1-integration` (continuation) | PR #21 → `development` | (see PR #21) | 2026-05-02 | +0 (refactor) |
+| **Wave 2a** | `closure/wave2a-integration` | PR #28 → `development` | (see PR #28) | 2026-05-04 | → 1160 |
+| **Wave 2b** | `closure/wave2b-integration` | PR #30 → `development` | `b05edb5` | 2026-05-05 | 1160 → 1298 (+138) |
+| **Wave 3** | `closure/wave3-integration` | PR #31 → `development` | `b87c872` | 2026-05-05 | 1298 → 1374 (+76) |
+| **Wave 4** | `closure/wave4-integration` | PR #33 → `development` | `01e40ba` | 2026-05-06 | 1374 → 1411 (+37) |
+| **Wave 5** | `closure/wave5-integration` | PR #34 → `development` merged `8f9f951` | `8f9f951` | 2026-05-06 | 1411 → ~1442 (+31) |
+| **Faz 33** (POST-WAVE) | release commit | tag `v0.5.5` → `main` | (post-Wave-5) | TBD | n/a |
+
+### Faz inventory (38 entries)
+
+| # | Faz | Wave | Status |
+|---|---|---|---|
+| 1 | Site & doc honesty + count drift sweep | Wave 0 (PR #19) | ✅ |
+| 2 | CI gates & standards drift cleanup | Wave 0 (PR #19) | ✅ |
+| 3 | Operator identity + audit forensic completeness | Wave 0 (PR #19) | ✅ |
+| 4 | Performance: lazy torch + safety/judge batching + paragraph chunker | Wave 0 (PR #19) | ✅ |
+| 5 | Notebook PyPI pin + nightly grep guard | Wave 0 (PR #19) | ✅ |
+| 6 | `forgelm verify-audit` subcommand + library function | Wave 0 (PR #19) | ✅ |
+| 7 | `safe_post` HTTP discipline extension | Wave 0 (PR #19) | ✅ |
+| 8 | Webhook lifecycle vocabulary | Wave 0 (PR #19) | ✅ |
+| 9 | Article 14: honesty fix + real staging + `forgelm approve` | Wave 1 | ✅ |
+| 10 | Pydantic Literal sweep (6 remaining fields) | Wave 1 | ✅ |
+| 11 | Wizard `_print` indirection + drop coverage omit | Wave 1 | ✅ |
+| 12 | Fixture consolidation (`tests/_helpers/`) | Wave 1 | ✅ |
+| 13 | `--data-audit` deprecation discipline | Wave 1 | ✅ |
+| 14 | `data_audit/` package split (5-PR series D-1..D-5) | Wave 1 | ✅ |
+| 15 | `cli/` package split (6-PR series C-1..C-6) | Wave 1 | ✅ |
+| 16 | Pydantic `description=` migration with CI guard (4 PR) | Wave 2b (PR #30) | ✅ |
+| 17 | `--workers N` audit determinism | Wave 2a (PR #28) | ✅ |
+| 18 | Library API support — Analysis & design | Wave 2a (PR #28) | ✅ |
+| 19 | Library API support — Implementation | Wave 2b (PR #30) | ✅ |
+| 20 | GDPR right-to-erasure — Analysis & design | Wave 2a (PR #28) | ✅ |
+| 21 | GDPR right-to-erasure — Implementation | Wave 2b (PR #30) | ✅ |
+| 22 | ISO 27001 / SOC 2 Type II — Analysis & gap assessment | Wave 4 (PR #33) | ✅ |
+| 23 | ISO 27001 / SOC 2 Type II — Implementation | Wave 4 (PR #33) | ✅ |
+| 24 | Bilingual TR mirror sweep + `tools/check_bilingual_parity.py` | Wave 3 (PR #31) | ✅ |
+| 25 | Site picker honesty + site-as-tested-surface CI guard | Wave 1 | ✅ |
+| 26 | QMS bilingual EN+TR mirror + `tools/check_anchor_resolution.py` | Wave 4 (PR #33) | ✅ |
+| 27 | Silent `except Exception:` sweep | Wave 1 | ✅ |
+| 28 | Remaining Major + Minor cleanup | Wave 3 (PR #31) | ✅ |
+| 29 | Nit sweep (40-item mass-edit) | Wave 1 | ✅ |
+| 30 | Final documentation + site finalization (EN+TR only) | Wave 4 partial + Wave 5 full sweep | ✅ |
+| 31 | Cross-OS release-tag matrix workflow | Wave 1 | ✅ |
+| 32 | `.pre-commit-config.yaml` (optional) | Wave 1 | ✅ |
+| 33 | **v0.5.5 RELEASE** (CHANGELOG, version bump, tag, PyPI) | POST-WAVE | ⏳ |
+| 34 | `forgelm doctor` env-check subcommand (GH-001) | Wave 2a (PR #28) | ✅ |
+| 35 | Air-gap pre-cache (`cache-models` + `cache-tasks`) (GH-002, GH-003) | Wave 2b (PR #30) | ✅ |
+| 36 | Compliance verification toolbelt (`safety-eval`, `verify-annex-iv`, `verify-gguf`) (GH-004/005/009) | Wave 2b (PR #30) | ✅ |
+| 37 | `forgelm approvals` listing subcommand (GH-007) | Wave 2a (PR #28) | ✅ |
+| 38 | `forgelm reverse-pii` GDPR Article 15 subcommand (GH-014) | Wave 3 (PR #31) | ✅ |
+
+**Total:** 38 fazlar / ~52 PRs (multi-PR series counted separately).
+
+### Wave-by-wave outcomes
+
+#### Wave 0 / 1 (PR #19, PR #21)
+
+Foundation + the bulk of the master-review backlog — fazlar 1-15, 25, 27, 29, 31, 32. Site honesty fixes, CI gates, audit log forensic completeness, performance pass, the two big package splits (`data_audit/` 5-PR series, `cli/` 6-PR series).
+
+#### Wave 2a (PR #28, 2026-05-04)
+
+5 fazlar: 17 (`audit --workers N`), 18 (Library API design), 20 (GDPR design), 34 (`doctor`), 37 (`approvals`).
+
+#### Wave 2b (PR #30, 2026-05-05, merge `b05edb5`)
+
+5 fazlar: 16 (Pydantic `description=` migration), 19 (Library API implementation), 21 (GDPR erasure implementation), 35 (air-gap pre-cache), 36 (compliance verification toolbelt). Suite 1160 → 1298 (+138). 6 absorption rounds + 4-agent final review + 4 followup absorption commits.
+
+#### Wave 3 (PR #31, 2026-05-05, merge `b87c872`)
+
+3 fazlar: 24 (bilingual TR mirror sweep + `tools/check_bilingual_parity.py`), 28 (curated Tier 1+2 cleanup), 38 (`reverse-pii`). Suite 1298 → 1374 (+76). Behaviour changes: high-risk + unacceptable + safety-disabled now `ConfigError` (F-compliance-110); webhook timeout 5s → 10s default (F-compliance-106).
+
+#### Wave 4 (PR #33, 2026-05-06, merge `01e40ba`)
+
+4 fazlar: 22 + 23 (ISO 27001 / SOC 2 alignment design + implementation), 26 (QMS bilingual mirror + `tools/check_anchor_resolution.py` + `compliance_summary.md` rewrite), 30 partial (Tier 1 ghost-feature drift + stat blocks). Suite 1374 → 1411 (+37: 16 supply-chain + 21 anchor checker). Bilingual parity scope 9/9 → 23/23 pairs.
+
+#### Wave 5 (PR #34 merged `8f9f951`, 2026-05-06)
+
+Faz 30 full sweep: residual ghost-feature drift (GH-011 benchmarks, GH-016 `--export-bundle`, GH-018 deploy-targets `kserve`/`triton`, GH-020 ingest flag drift); Task A doc-triplet completion (~12 features × {guide, reference, usermanual} × {EN, TR} ≈ 50 new files — landed in commit `2a32842`); Task J `tools/check_cli_help_consistency.py` (commit `c7bedc9`); Task N anchor-checker `--strict` flip + 36-baseline cleanup (commit `fbb082d`); Tasks B/C `_meta.yaml` + `build_usermanuals.py` rebuild; Task D site/* finalization; Tasks E/F/G README + CONTRIBUTING + CLAUDE + roadmap + standards final pass; Tasks H/I/K/L/M parity strict + site-claim CI + config regen + locale policy + diagrams.
+
+#### Faz 33 (POST-WAVE)
+
+The actual v0.5.5 PyPI publish:
+
+1. `pyproject.toml` `version = "0.5.5"` — already bumped during Wave 5 Task D (`4610dc6`) so `check_site_claims.py --strict` can pin the site → code version parity. Faz 33 only confirms it remains `0.5.5` and adds the date to the `[0.5.5]` CHANGELOG section.
+2. CHANGELOG `[Unreleased]` → `[0.5.5] — YYYY-MM-DD`
+3. `git tag -s v0.5.5 -m "v0.5.5 — Closure Cycle Bundle"`
+4. `git push origin main v0.5.5`
+5. `publish.yml` runs: build → cross-OS matrix (12 combos) → publish (OIDC trusted publishing, no API token)
+
+The cut-release skill ([`.claude/skills/cut-release/SKILL.md`](../../.claude/skills/cut-release/SKILL.md)) walks the maintainer through the sequence step-by-step.
+
+### Quality dimensions reached
+
+Per the closure plan §1 baseline + §9 exit criteria:
+
+| Dimension | Pre-Wave-0 | Post-Wave-5 target |
+|---|---|---|
+| Business | ★★★½ | ★★★★★ |
+| Code | ★★★½ | ★★★★★ |
+| Compliance | ★★★★ | ★★★★★ |
+| Documentation | ★★★½ | ★★★★★ |
+| Localization | ★★★ | ★★★★★ (EN+TR; DE/FR/ES/ZH user-manual deferred by user decision) |
+| Performance | ★★★★ | ★★★★★ |
+| Security | ★★★★ | ★★★★★ |
+| Testing & CI/CD | ★★★½ | ★★★★★ |
+
+### Related
+
+- [`releases.md`](releases.md) — v0.5.5 release notes
+- [`risks-and-decisions.md`](risks-and-decisions.md) — closure-cycle decision log entries
+- [`CHANGELOG.md`](../../CHANGELOG.md) — `[0.5.5]` section (finalized at release; per-PR closure entries collapse into the v0.5.5 release notes)
diff --git a/docs/roadmap/phase-10-5-quickstart.md b/docs/roadmap/phase-10-5-quickstart.md
deleted file mode 100644
index 9dd8509c..00000000
--- a/docs/roadmap/phase-10-5-quickstart.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# Phase 10.5: Quickstart Layer & Onboarding
-
-> **Status:** ✅ **DONE** — shipped as `v0.4.5` on 2026-04-26 (PyPI). Module: [`forgelm/quickstart.py`](../../forgelm/quickstart.py); five bundled templates under [`forgelm/templates/`](../../forgelm/templates/); CLI: `forgelm quickstart <template>`; tests: [`tests/test_quickstart.py`](../../tests/test_quickstart.py); CI smoke in [nightly.yml](../../.github/workflows/nightly.yml).
-
-> **Note:** This file details a single phase. For a summary of all phases, see [../roadmap.md](../roadmap.md).
-> **Filename history:** Originally `phase-12-quickstart.md` (the slot Quickstart held in early planning); renamed to `phase-10-5-quickstart.md` in the v0.5.2 cycle so the filename matches the current phase number. The Phase 12 slot now belongs to [Data Curation Maturity](phase-12-data-curation-maturity.md).
-
-**Goal:** Make "my first fine-tune" a 10-minute experience. One command, one model in the end, zero YAML writing. Without sacrificing the CI/CD-native core — quickstart generates a YAML the user can later customize.
-**Estimated Effort:** Medium (1-2 months) — **Actual: 1 week**
-**Priority:** Critical — community flywheel; directly drives EU AI Act enterprise pipeline
-
-> **Phase ordering rationale:** Reprioritized from Phase 12 to Phase 10.5. Quickstart is the primary community growth driver; stars → enterprise leads → compliance sales. EU AI Act enforcement (August 2, 2026) creates a closing window. This phase must ship before Data Ingestion (Phase 11).
-
-> **Context:** Strategic decision documented in the internal enterprise-vs-simple paradox analysis: ForgeLM adds a "Layer 0" entry point without changing its CI/CD-native identity. The same YAML schema, the same trainer, the same outputs — just wrapped in pre-built templates and opinionated defaults. Depends on Phase 10 (`chat`) for end-of-training sanity loop.
-
-### Tasks:
-
-1. [x] **`forgelm/quickstart.py` + `forgelm quickstart <template>` CLI**
-   Takes a template name, optional model override, optional dataset override. Generates a `my_run.yaml` under `./configs/` and immediately invokes `forgelm --config ./configs/my_run.yaml`. On completion, auto-invokes `forgelm chat` unless `--no-chat` flag. Transparent about what it did — prints generated YAML path.
-   ```bash
-   forgelm quickstart customer-support
-   forgelm quickstart code-assistant --model Qwen/Qwen2.5-Coder-7B-Instruct
-   forgelm quickstart --list
-   ```
-
-2. [x] **Template library: `forgelm/templates/` + bundled sample datasets**
-   Initial five templates, each = YAML config + sample JSONL (100-500 examples, license-clean):
-   - `customer-support` (Qwen/Qwen2.5-7B-Instruct primary, HuggingFaceTB/SmolLM2-1.7B-Instruct fallback, 58 examples, QLoRA r=8, ~15 min on RTX 3060)
-   - `code-assistant` (Qwen/Qwen2.5-Coder-7B-Instruct primary, Qwen/Qwen2.5-Coder-1.5B-Instruct fallback, 59 examples, QLoRA, ~25 min)
-   - `domain-expert` (Qwen/Qwen2.5-7B-Instruct primary, HuggingFaceTB/SmolLM2-1.7B-Instruct fallback, BYOD — no bundled dataset)
-   - `medical-qa-tr` (Qwen/Qwen2.5-7B-Instruct primary, Qwen/Qwen2.5-1.5B-Instruct fallback, 49 TR examples; Turkish-language flagship)
-   - `grpo-math` (Qwen/Qwen2.5-Math-7B-Instruct primary, Qwen/Qwen2.5-Math-1.5B-Instruct fallback, 40 prompts with gold_answer field, GRPO with built-in format+correctness reward, ~45 min)
-   Each template must produce a working model on an 8-12 GB consumer GPU. `fit_check` integration: if GPU too small, quickstart auto-downsizes model choice.
-
-3. [x] **Conservative default policy for quickstart**
-   All templates ship with: QLoRA 4-bit NF4, rank=8, batch=1 with gradient accumulation, gradient checkpointing on, safety eval off (opt-in only), compliance artifacts off (opt-in only). Rationale: minimize "GPU OOM on first run" and "compliance scared me off" failure modes.
-
-4. [x] **Wizard integration — template selector first**
-   `forgelm --wizard` opens with "Start from a template?" question. If yes → pass to quickstart flow. If no → existing 10-question flow. Merges the two paths.
-
-5. [x] **End-to-end smoke test in CI**
-   Nightly CI runs: `forgelm quickstart customer-support --dry-run` for each template. Validates YAML generation + dataset parse + config validation. No GPU required (dry-run). Catches template drift early.
-
-### Requirements:
-- Sample datasets must be license-clean (CC-BY-SA 4.0 or similar permissive, documented in `forgelm/templates/LICENSES.md`).
-- Each template has a companion YouTube video (scheduled in marketing roadmap, not this roadmap).
-- Templates are a foundation for community contributions: `CONTRIBUTING.md` should document how to add new templates; each template is an atomic PR.
-- Quickstart must not introduce a "quickstart vs real training" bifurcation — same underlying code paths, same YAML schema.
-
-### Delivery:
-- Target release: `v0.4.5` ("Quickstart Layer")
-- Blocks on Phase 10 tasks 1 + 2 (`inference.py` and `chat.py`). Phase 10 tasks 3-5 (export, fit-check, deploy) can develop in parallel.
-
----
diff --git a/docs/roadmap/phase-10-post-training.md b/docs/roadmap/phase-10-post-training.md
deleted file mode 100644
index 80e0bc07..00000000
--- a/docs/roadmap/phase-10-post-training.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# Phase 10: Post-Training Completion
-
-> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md).
-
-**Goal:** Close the "trained, now what?" gap. After a fine-tune finishes, users should be able to sanity-check, export, and hand the model to a serving runtime (Ollama, vLLM, TGI) without leaving ForgeLM.
-**Estimated Effort:** Medium (2-3 months)
-**Priority:** High — single biggest post-9 UX gap; foundation for Phase 12 (quickstart)
-
-> **Context:** External analyses of two adjacent projects (QKV-Core, Trion) plus internal retrospectives converged on the same finding: ForgeLM stops at `output_dir/` with an HF-format adapter/merged model, but the user's actual journey continues to sanity chat → quantization → serving. Competitors (Axolotl, Unsloth) leave this to external tooling. Owning this handoff — without rewriting the inference ecosystem — is a high-value, low-risk addition.
-
-**Status: ✅ Complete** — shipped in `v0.4.0` (April 2026)
-
-### Tasks:
-
-1. [x] **`forgelm/inference.py` — generation + logit statistics + adaptive sampling**
-   Core API: `load_model(path, adapter=None, backend="transformers")`, `generate(model, tokenizer, prompt, **kwargs)`, `generate_stream(...)` (streaming via `TextIteratorStreamer`), `logit_stats(logits) -> {entropy, top1_prob, effective_vocab}`, `adaptive_sample(logits, temperature, top_k, top_p, entropy_threshold=6.5)`. Chat template reuse via `tokenizer.apply_chat_template`. Fallback to `"role: content"` join when no template. Shared by `chat.py`, `judge.py`, `synthetic.py`.
-   ```python
-   from forgelm.inference import load_model, generate
-   model, tok = load_model("./outputs/my_run", adapter="./outputs/my_run/adapter_model")
-   text = generate(model, tok, "Hello", max_new_tokens=200, temperature=0.7)
-   ```
-
-2. [x] **`forgelm chat` — interactive terminal loop**
-   Terminal REPL in `forgelm/chat.py`: streaming output (default), `/reset`, `/save [file]`, `/temperature 0.x`, `/system <prompt>`, `/help` commands. `rich` optional rendering. History management with 50-pair cap. The `--safety` per-turn screen flag is planned for v0.6.0+ Pro CLI (today's safety pipeline runs through the YAML `safety:` block during training/eval).
-   ```bash
-   forgelm chat ./outputs/my_run
-   ```
-
-   `forgelm chat`'s shipping form takes a positional checkpoint path
-   plus optional `--adapter`. The per-turn Llama Guard screen via
-   `--safety` is planned for v0.6.0+ Pro CLI (see Phase 13 roadmap);
-   today operators get the same screening by enabling
-   `safety: enabled: true` in the YAML config the chat REPL reads.
-   The flag-form preview (`forgelm chat ... --safety`) is NOT
-   runnable today.
-
-3. [x] **`forgelm export` — HF → GGUF conversion**
-   Wraps `llama-cpp-python`'s `convert_hf_to_gguf.py`; no reimplementation. Handles adapter merge (LoRA + base → merged fp16) before conversion. Supports quants: `q2_k`, `q3_k_m`, `q4_k_m`, `q5_k_m`, `q8_0`, `f16`. SHA-256 of output artifact appended to `model_integrity.json`. Optional dependency: `pip install forgelm[export]`.
-   ```bash
-   forgelm export ./outputs/my_run --format gguf --quant q4_k_m --output model.gguf
-   ```
-
-4. [x] **`--fit-check` — VRAM fit advisor**
-   Pre-flight memory estimator in `forgelm/fit_check.py`. Detects GPU via `torch.cuda.mem_get_info()`. Estimates peak VRAM = base (params × dtype) + LoRA adapter + optimizer state (AdamW/8bit/GaLore variants) + activations (with gradient-checkpointing scaling). Produces verdict (FITS / TIGHT / OOM / UNKNOWN) with ordered recommendations. Falls back to hypothetical mode when no GPU is detected.
-   ```bash
-   forgelm --config my.yaml --fit-check
-   # → GPU: RTX 3060 12GB; Estimated peak: 10.8 GB; Verdict: ✅ FITS
-   forgelm --config my.yaml --fit-check --output-format json
-   ```
-
-5. [x] **`forgelm deploy` — serving handoff config generation**
-   Template-based config generation in `forgelm/deploy.py`; does not run the server. Targets: `ollama` (Modelfile), `vllm` (engine config YAML), `tgi` (docker-compose.yaml), `hf-endpoints` (JSON spec). All targets support `--output-format json`.
-   ```bash
-   forgelm deploy ./outputs/my_run --target ollama --output ./Modelfile
-   forgelm deploy ./outputs/my_run --target vllm --output ./vllm_config.yaml
-   forgelm deploy ./outputs/my_run --target tgi --output ./docker-compose.yaml
-   forgelm deploy ./outputs/my_run --target hf-endpoints --output ./endpoint.json
-   ```
-
-### Requirements:
-- All five modules must work without GPU for config generation (fit-check excepted — it reads GPU but doesn't require one, falls back to hypothetical mode).
-- `inference.py` and `chat.py` share the same load/generate primitives with `safety.py`, `judge.py`, and `synthetic.py`; refactor duplicated `model.generate()` calls into the new module.
-- Each CLI command supports `--output-format json` for pipeline integration.
-- `pip install forgelm[export]` is optional; core install must not require `llama-cpp-python`.
-- Windows/Linux/macOS compatibility for all CLI surface (GGUF export may require specific toolchains, document clearly).
-
-### Delivery:
-- Target release: `v0.4.0` ("Post-Training Completion")
-- Each task = independent PR with tests; no cross-task blocking dependencies.
-
----
diff --git a/docs/roadmap/phase-11-5-backlog.md b/docs/roadmap/phase-11-5-backlog.md
deleted file mode 100644
index 3b0b9dd2..00000000
--- a/docs/roadmap/phase-11-5-backlog.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Phase 11.5 — Ingestion / Audit Polish
-
-> **Note (post-consolidation):** Originally targeted `v0.5.1`, now ships
-> as part of the consolidated `v0.5.0` release alongside Phases 11, 12,
-> and 12.5 — see [releases.md](releases.md#v050-document-ingestion-data-curation-pipeline).
-> Version-label references below preserve the historical planning trail.
->
-> **Status:** ✅ Landed for the (originally) `v0.5.1` cycle. All 12 follow-ups carved
-> out of Phase 11's review backlog have shipped. Modules touched:
-> [`forgelm/data_audit/`](../../forgelm/data_audit/),
-> [`forgelm/ingestion.py`](../../forgelm/ingestion.py),
-> [`forgelm/cli/`](../../forgelm/cli/),
-> [`forgelm/wizard/`](../../forgelm/wizard/); CLI:
-> `forgelm audit <path>` (new subcommand, with `--data-audit` preserved
-> as deprecation alias) + token-aware `forgelm ingest` flags; tests:
-> [`tests/test_data_audit.py`](../../tests/test_data_audit.py),
-> [`tests/test_ingestion.py`](../../tests/test_ingestion.py),
-> [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py),
-> [`tests/test_wizard_byod.py`](../../tests/test_wizard_byod.py).
-
-**Goal:** Operational polish on top of `v0.5.0`'s ingestion + audit
-surface — no new training capabilities, but materially better handling
-for large corpora and a cleaner CLI shape.
-
-## What landed
-
-| # | Item | Where it lives | One-line takeaway |
-|---|---|---|---|
-| **1** | LSH banding for near-duplicate detection | `find_near_duplicates`, `_count_leaked_rows` in [`data_audit.py`](../../forgelm/data_audit/) | Pigeonhole-banded LSH (default `bands = threshold + 1`). Drops within-split + cross-split scans from `O(n²)` to ~`O(n × k)`; brute-force fallback when bands shrink below 4 bits. |
-| **2** | Streaming `_read_jsonl_split` | [`data_audit.py`](../../forgelm/data_audit/) | Reader is now a generator yielding `(row, parse_err, decode_err)`; `_audit_split` consumes it row-by-row via a `_StreamingAggregator` so RAM stays bounded on multi-million-row splits. |
-| **3** | Token-aware `--chunk-tokens` | [`ingestion.py`](../../forgelm/ingestion.py), [`cli.py`](../../forgelm/cli/) | New `--chunk-tokens N` + `--tokenizer MODEL` flags on `forgelm ingest`. Chunks are sized via `AutoTokenizer.encode` instead of raw character counts so they line up with `model.max_length` exactly. |
-| **4** | PDF page-level header / footer dedup | `_strip_repeating_page_lines` in [`ingestion.py`](../../forgelm/ingestion.py) | Lines that recur as the first or last non-empty line on ≥ 70 % of a PDF's pages are stripped. Reduces audit near-duplicate noise on long policy / book PDFs. |
-| **5** | Token-level `lru_cache` memo | `_token_digest` in [`data_audit.py`](../../forgelm/data_audit/) | Per-token digest is cached at module scope (`maxsize=10_000`). Distinct tokens follow Zipf, so ~10 K cache slots cover most corpus traffic. |
-| **6** | xxhash backend for simhash | `_token_digest` in [`data_audit.py`](../../forgelm/data_audit/) | Optional `xxhash` import (added to the `[ingestion]` extra) drives the digest path when present; BLAKE2b is preserved as the fallback. |
-| **7** | `forgelm audit` proper subcommand | [`cli.py`](../../forgelm/cli/) | New `forgelm audit PATH` (with `--verbose`, `--near-dup-threshold`, `--output`). The legacy `--data-audit FLAG` keeps working as a deprecation alias (logs a one-line notice). |
-| **8** | PII severity tiers | `PII_SEVERITY`, `_build_pii_severity` in [`data_audit.py`](../../forgelm/data_audit/) | Audit JSON now carries `pii_severity` with `worst_tier`, `by_tier`, and `by_type`. Notes line lead with the worst tier (e.g. `WORST tier: CRITICAL`). |
-| **9** | `summarize_report` truncation policy | [`data_audit.py`](../../forgelm/data_audit/) | Default `verbose=False` folds zero-finding splits into a single tail line. CLI exposes `--verbose` on the new `audit` subcommand for full output. |
-| **10** | Structured ingestion notes | `IngestionResult.notes_structured` in [`ingestion.py`](../../forgelm/ingestion.py) | Free-text `extra_notes` stays for humans; new `notes_structured` carries machine-readable `{key: value}` for CI/CD consumers. JSON output already exposes both. |
-| **11** | Wizard "ingest first" entry point | `_offer_ingest_for_directory` + `_prompt_dataset_path_with_ingest_offer` in [`forgelm/wizard/_byod.py`](../../forgelm/wizard/_byod.py) | Both BYOD quickstart and the full 9-step wizard now offer to run `ingest` inline when the typed path is a directory of raw documents. |
-| **12** | Atomic audit-report write | `_atomic_write_json` in [`data_audit.py`](../../forgelm/data_audit/) | Writes via `tempfile.NamedTemporaryFile` + `os.replace` so a crashed audit can never leave a half-written `data_audit_report.json` on disk. |
-
-## Measured speedups (xxhash + lru_cache hot path)
-
-Local microbenchmark on Apple Silicon, Python 3.11.2, xxhash 3.7.0
-(median of 21 runs, 50 K hashes per round; end-to-end uses 1 K texts of
-50–150 Zipfian-English tokens with the cache cleared between runs):
-
-| Scenario                                | Speedup (xxh3 vs blake2b) |
-| --------------------------------------- | ------------------------- |
-| Raw digest, short keys (2–6 chars)      | 1.31×                     |
-| Raw digest, Zipfian English (~3 chars)  | 1.34×                     |
-| Raw digest, long keys (40–80 chars)     | 1.33×                     |
-| End-to-end `compute_simhash` (cache cleared) | 1.05×                |
-
-xxhash's well-known "4–10× faster than crypto hashes" figure refers to
-C-level pure-hash benchmarks; the Python wrapping (UTF-8 encode → call →
-`intdigest`) levels the field. The bigger wall-clock win in real audits
-comes from the token-level `lru_cache` — Zipfian token frequency means
-~10 K cache slots cover the vast majority of a corpus's traffic, so a
-second pass over the same corpus runs almost entirely from cache.
-
-The benchmark script is at `tools/bench_simhash.py` (run with
-`python tools/bench_simhash.py`); it is not part of the regular `pytest`
-suite because it is wall-clock-noisy.
-
-## Behavioural deltas worth highlighting
-
-- **Default near-duplicate detection is now LSH-banded.** Behaviour at
-  the default `threshold=3` is identical to the old quadratic scan
-  (pigeonhole gives exact recall), but the cost on a 100 K row corpus
-  drops from "tens of seconds, gigabytes of comparisons" to ~seconds.
-- **Audit output JSON adds `pii_severity`.** Existing consumers that
-  read only `pii_summary` keep working — the new field is additive.
-  Pipelines that want a one-glance verdict should read
-  `pii_severity.worst_tier` and gate on `critical` / `high`.
-- **`forgelm audit PATH` is the recommended invocation.** The
-  `--data-audit` top-level flag continues to work but logs a one-line
-  deprecation notice. Plan to remove it no earlier than `v0.7.0`.
-- **`--chunk-tokens` requires `--tokenizer`.** Token-aware chunking
-  needs to know which vocab to count against; we refuse to default to a
-  hidden tokenizer because the chunk count would silently differ
-  per-model. Set both or neither.
-- **PDF dedup is opt-out by being short-doc-tolerant.** Documents
-  with fewer than 3 pages skip the dedup step entirely; the statistical
-  signal is too weak to distinguish "header" from "actual repetition"
-  on small docs.
-
-## What's next
-
-`v0.5.2` ([Phase 12 — Data Curation Maturity](phase-12-data-curation-maturity.md)) is the direct continuation of this lineage: MinHash LSH dedup for >50K-row corpora, markdown-aware splitter, code/secrets leakage scan, heuristic quality filter, DOCX/Markdown table preservation. Driven by the post-`v0.5.1` competitive review that compared ForgeLM's ingestion + audit against LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling.
-
-`v0.5.3` ([Phase 14 — Multi-Stage Pipeline Chains](phase-14-pipeline-chains.md)) was reslotted from `v0.5.2` so the ingestion/audit lineage finishes uninterrupted before the trainer-orchestration surface gets reshaped.
diff --git a/docs/roadmap/phase-11-data-ingestion.md b/docs/roadmap/phase-11-data-ingestion.md
deleted file mode 100644
index 8ce66f0c..00000000
--- a/docs/roadmap/phase-11-data-ingestion.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# Phase 11: Document Ingestion & Data Audit
-
-> **Status:** ✅ **DONE** — shipped as `v0.5.0` (PR #11 merged to `main` 2026-04-27).
-> Modules: [`forgelm/ingestion.py`](../../forgelm/ingestion.py),
-> [`forgelm/data_audit.py`](../../forgelm/data_audit/); CLI:
-> `forgelm ingest <path>` + `forgelm --data-audit <path>`; tests:
-> [`tests/test_ingestion.py`](../../tests/test_ingestion.py),
-> [`tests/test_data_audit.py`](../../tests/test_data_audit.py); docs:
-> [`docs/guides/ingestion.md`](../guides/ingestion.md),
-> [`docs/guides/data_audit.md`](../guides/data_audit.md). Follow-up
-> work tracked in [Phase 11.5 backlog](phase-11-5-backlog.md).
->
-> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların
-> özeti için [../roadmap.md](../roadmap.md).
-
-**Goal:** Turn raw domain documents (PDF, DOCX, EPUB, TXT, plus structured sources) into training-ready JSONL, with automatic data quality reports that plug into EU AI Act Article 10 data governance.
-**Estimated Effort:** Medium (1-2 months) — **Actual: 1 day**
-**Priority:** High — enterprise onboarding accelerator; bridges ingestion → training → compliance audit in one tool.
-
-> **Context:** Dataset loading today goes through HuggingFace `load_dataset` + JSONL/CSV/Parquet. Enterprises arriving with directories of PDFs (legal, medical, policy manuals) have to write custom preprocessing. This module removes that friction and simultaneously generates governance artifacts that satisfy Article 10 (data collection method, quality metrics, bias declarations).
-
-## Tasks
-
-1. [x] **`forgelm/ingestion.py` — multi-format → JSONL**
-   Parsers for PDF (`pypdf`), DOCX (`python-docx`, including table cells), EPUB (`ebooklib` + `beautifulsoup4`), plain TXT, Markdown. Chunking strategies as shipped: `sliding` (fixed character window with `--overlap`) and `paragraph` (greedy paragraph packer; default). `semantic` is reserved for a follow-up phase and intentionally hidden from the CLI `--strategy` choice list — it raises `NotImplementedError` if invoked programmatically. Output is `{"text": "<chunk>"}` JSONL — recognized by `forgelm/data.py` as pre-formatted SFT input without further preprocessing. Optional dependency group: `pip install forgelm[ingestion]`.
-   ```bash
-   forgelm ingest ./book.epub --chunk-size 2048 --strategy paragraph --output data/sft.jsonl
-   forgelm ingest ./policies/ --recursive --output data/policies.jsonl
-   ```
-
-2. [x] **`forgelm/data_audit.py` — dataset quality & governance report**
-   Analyzes a JSONL dataset, produces `data_audit_report.json` with: sample count per split, column schema, text length distribution (min/max/mean/p50/p95), language detection (top-3), duplicate / near-duplicate rate (simhash-based), null/empty rate, PII flag counts (regex-based; optional `presidio` integration). Feeds Phase 8 Article 10 artifact (`data_governance_report.json`).
-   ```bash
-   forgelm --data-audit data/sft.jsonl --output audit/
-   ```
-
-3. [x] **PII detection hooks**
-   Regex-based detector for: emails, phone numbers (international formats), credit cards (Luhn-validated), IBAN, national IDs (TR, DE, FR, US SSN). Counts flags per sample; optionally masks via `--pii-mask`. Does not block training by default — surfaces in audit report.
-
-4. [x] **Near-duplicate detection across splits**
-   Simhash / MinHash across train/validation/test. Reports overlap rate. Critical for fair benchmarking — train-test leakage is a silent quality killer.
-
-## Requirements
-- Ingestion must handle malformed files gracefully (scan PDFs with no text layer → warning + empty result, not crash).
-- Audit runs on CPU; no GPU required.
-- All outputs integrate with Phase 8 compliance artifacts — data governance report references the audit JSON.
-- OCR is out of scope; document this as a limitation and suggest external tooling (Tesseract, AWS Textract).
-
-## Delivery
-- Target release: `v0.5.0`
-- Can start after Phase 10.5 (Quickstart) lands; no hard blocker on code, but UX sequencing matters.
-
----
diff --git a/docs/roadmap/phase-12-5-backlog.md b/docs/roadmap/phase-12-5-backlog.md
deleted file mode 100644
index c43d3233..00000000
--- a/docs/roadmap/phase-12-5-backlog.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# Phase 12.5 — Data Curation Polish Backlog
-
-> **Note (post-consolidation):** Originally targeted `v0.5.3`; all four
-> backlog items now ship together with Phases 11 / 11.5 / 12 in the
-> consolidated `v0.5.0` release (see [releases.md](releases.md#v050-document-ingestion-data-curation-pipeline)).
-> The version-label references below preserve the historical planning
-> trail.
->
-> **Follow-up to Phase 12.** Phase 12 (originally targeted `v0.5.2`) shipped the five Tier 1
-> must-haves: MinHash LSH dedup option, markdown-aware splitter,
-> code/secrets leakage tagger, heuristic quality filter, DOCX/Markdown
-> table preservation. Three Tier 2/3 items were tagged "if scope allows"
-> in the [original Phase 12 plan](phase-12-data-curation-maturity.md);
-> they didn't make the same release because the Tier 1 surface was
-> already a complete coherent ship and adding more would have grown the
-> review window without proportional value. This file pins them as the
-> follow-up backlog so a future minor release can pick them up without
-> reopening the Phase 12 plan.
->
-> **Scope:** small additions only — none require new architecture.
-> Each row is one PR.
-
-| # | Item | Source | Effort | Status |
-|---|---|---|---|---|
-| **1** | ~~**Presidio adapter** (`[ingestion-pii-ml]` extra, optional)~~ | Phase 12 plan Tier 2 #6 | S–M | ✅ Landed on `development` — `forgelm audit --pii-ml`; new `PII_ML_SEVERITY` table; opt-in `[ingestion-pii-ml]` extra (`presidio-analyzer`); ships with `v0.5.0` (consolidated release). |
-| **2** | ~~**Croissant metadata compatibility** (audit JSON)~~ | Phase 12 plan Tier 2 #7 | S | ✅ Landed on `development` — `forgelm audit --croissant`; Croissant 1.0 card under report's `croissant` key; existing keys byte-equivalent when off. Ships with `v0.5.0`. |
-| **3** | ~~**`forgelm ingest --all-mask` composite flag**~~ | Phase 12 plan Tier 3 #8 | XS | ✅ Landed on `development` — `forgelm ingest --all-mask`; set-union with explicit flags; resolved at the CLI boundary. Ships with `v0.5.0`. |
-| **4** | ~~**Wizard "audit first" entry point**~~ | Phase 12 plan Tier 3 #9 | S | ✅ Landed on `development` — `_offer_audit_for_jsonl` invoked from the three JSONL-finalisation paths in `forgelm/wizard.py`. Ships with `v0.5.0`. |
-
-## Why these landed here, not in Phase 12
-
-- **Tier 2 (#1, #2)** add new optional dependencies (`presidio-analyzer`, plus a small Croissant schema mapping). Adding two new extras at once expands the install / extras-skip test matrix; carving them into their own PR keeps each behaviour individually reviewable. Neither closes a competitive gap that mattered for the `v0.5.2` ship — Phase 12's regex+Luhn+TC-Kimlik PII detector and the EU AI Act governance bundle covered the immediate compliance surface.
-- **Tier 3 (#3, #4)** are pure UX polish. They don't unlock anything the operator cannot do today by typing two flags or running `forgelm audit` themselves; they smooth the path. Worth doing, not worth gating Phase 12 on.
-
-## Picking up an item
-
-1. Open an issue referencing the row number above.
-2. PR scope: ONE row per PR.
-3. Update this file when the row lands — strike through and link the
-   commit / PR.
-4. If a row turns out to be the wrong shape, edit it here before doing
-   the work. Stale backlog rows are worse than missing rows.
-
-## Out of scope (still)
-
-The "Won't-do" list at the bottom of [`phase-12-data-curation-maturity.md`](phase-12-data-curation-maturity.md) is not weakened by this backlog. VLM PDF parsing, embedding-based semantic dedup, built-in OCR, ML quality classifiers, GPU/Ray scale, and HTML extractor stay out of scope as deliberately as Phase 12 declared them.
diff --git a/docs/roadmap/phase-12-6-closure-cycle.md b/docs/roadmap/phase-12-6-closure-cycle.md
deleted file mode 100644
index 41bb7cc5..00000000
--- a/docs/roadmap/phase-12-6-closure-cycle.md
+++ /dev/null
@@ -1,149 +0,0 @@
-# Phase 12.6 — Closure Cycle (38 fazlar across 5 waves)
-
-> **Status:** ✅ Done — Faz 33 release publish remains as POST-WAVE.
-> **Bundled into:** [v0.5.5 release](releases.md#v055-closure-cycle-bundle-phase-22-wizard-site-documentation-sweep-2026-05-10).
-> **Source review:** v0.5.0 master code review (175 findings: 8 Critical + 67 Major + 60 Minor + 40 Nit) — distilled into the Faz 1-38 task list below.
-> **Target:** ★★★★★ across all 8 quality dimensions before v0.5.5 PyPI publish.
-
-## Why this exists as a single phase entry
-
-The v0.5.0 master code review surfaced **175 findings** plus **4 user-added scope items** (Library API support, ISO 27001 / SOC 2 alignment, GDPR right-to-erasure full implementation, Article 14 real staging). Rather than stretch these across 5 sequential patch releases, the maintainer chose **Path B — full Faz 1-38 sweep into a single v0.5.5 tag**:
-
-- Bisectable PR-per-faz history
-- One coherent surface (every faz feeds the same release candidate)
-- 5/5 quality bar reached before publish, not after
-
-The 38 fazlar were merged across **5 integration waves** (Wave 0/1 through Wave 5). Each wave landed via a dedicated PR onto `development`, then into `main`. This file is the index that maps every faz to its wave, integration PR, and merge SHA.
-
-## Scope (in / out)
-
-**In scope:**
-
-- All 175 master-review findings (Critical → Nit)
-- 4 user-added scope items: Library API, ISO 27001 / SOC 2, GDPR full implementation, Article 14 real staging + `forgelm approve`
-- 5 ghost-feature drift items surfaced during Wave 4 + 5 (GH-001 doctor, GH-002/003 air-gap pre-cache, GH-004/005/009 verification toolbelt, GH-007 approvals listing, GH-014 reverse-pii)
-- Documentation final pass: `docs/` EN+TR, `docs/usermanuals/{en,tr}/`, `site/*`, all 10 standards files, README + CONTRIBUTING + CLAUDE.md, roadmap + roadmap-tr.md
-
-**Explicitly out of scope:**
-
-- DE / FR / ES / ZH user-manual translation (deferred to a future cycle — bilingual policy formalised in [`docs/standards/localization.md`](../standards/localization.md))
-- Cloud SaaS product (separate offering)
-- New roadmap features: Phase 13 (Pro CLI) and Phase 14 (Pipeline Chains) work
-- Marketing / GTM expansion
-
-## Wave timeline
-
-| Wave | Branch | Integration PR | Merge SHA | Date | Net new tests |
-|---|---|---|---|---|---|
-| **Wave 0** (foundation) | `closure/wave1-integration` (early bundle) | PR #19 → `main` | (see PR #19) | 2026-04-30 | baseline |
-| **Wave 1** (foundation residuals) | `closure/wave1-integration` (continuation) | PR #21 → `development` | (see PR #21) | 2026-05-02 | +0 (refactor) |
-| **Wave 2a** | `closure/wave2a-integration` | PR #28 → `development` | (see PR #28) | 2026-05-04 | → 1160 |
-| **Wave 2b** | `closure/wave2b-integration` | PR #30 → `development` | `b05edb5` | 2026-05-05 | 1160 → 1298 (+138) |
-| **Wave 3** | `closure/wave3-integration` | PR #31 → `development` | `b87c872` | 2026-05-05 | 1298 → 1374 (+76) |
-| **Wave 4** | `closure/wave4-integration` | PR #33 → `development` | `01e40ba` | 2026-05-06 | 1374 → 1411 (+37) |
-| **Wave 5** | `closure/wave5-integration` | PR #34 → `development` merged `8f9f951` | `8f9f951` | 2026-05-06 | 1411 → ~1442 (+31) |
-| **Faz 33** (POST-WAVE) | release commit | tag `v0.5.5` → `main` | (post-Wave-5) | TBD | n/a |
-
-## Faz inventory (38 entries)
-
-| # | Faz | Wave | Status |
-|---|---|---|---|
-| 1 | Site & doc honesty + count drift sweep | Wave 0 (PR #19) | ✅ |
-| 2 | CI gates & standards drift cleanup | Wave 0 (PR #19) | ✅ |
-| 3 | Operator identity + audit forensic completeness | Wave 0 (PR #19) | ✅ |
-| 4 | Performance: lazy torch + safety/judge batching + paragraph chunker | Wave 0 (PR #19) | ✅ |
-| 5 | Notebook PyPI pin + nightly grep guard | Wave 0 (PR #19) | ✅ |
-| 6 | `forgelm verify-audit` subcommand + library function | Wave 0 (PR #19) | ✅ |
-| 7 | `safe_post` HTTP discipline extension | Wave 0 (PR #19) | ✅ |
-| 8 | Webhook lifecycle vocabulary | Wave 0 (PR #19) | ✅ |
-| 9 | Article 14: honesty fix + real staging + `forgelm approve` | Wave 1 | ✅ |
-| 10 | Pydantic Literal sweep (6 remaining fields) | Wave 1 | ✅ |
-| 11 | Wizard `_print` indirection + drop coverage omit | Wave 1 | ✅ |
-| 12 | Fixture consolidation (`tests/_helpers/`) | Wave 1 | ✅ |
-| 13 | `--data-audit` deprecation discipline | Wave 1 | ✅ |
-| 14 | `data_audit/` package split (5-PR series D-1..D-5) | Wave 1 | ✅ |
-| 15 | `cli/` package split (6-PR series C-1..C-6) | Wave 1 | ✅ |
-| 16 | Pydantic `description=` migration with CI guard (4 PR) | Wave 2b (PR #30) | ✅ |
-| 17 | `--workers N` audit determinism | Wave 2a (PR #28) | ✅ |
-| 18 | Library API support — Analysis & design | Wave 2a (PR #28) | ✅ |
-| 19 | Library API support — Implementation | Wave 2b (PR #30) | ✅ |
-| 20 | GDPR right-to-erasure — Analysis & design | Wave 2a (PR #28) | ✅ |
-| 21 | GDPR right-to-erasure — Implementation | Wave 2b (PR #30) | ✅ |
-| 22 | ISO 27001 / SOC 2 Type II — Analysis & gap assessment | Wave 4 (PR #33) | ✅ |
-| 23 | ISO 27001 / SOC 2 Type II — Implementation | Wave 4 (PR #33) | ✅ |
-| 24 | Bilingual TR mirror sweep + `tools/check_bilingual_parity.py` | Wave 3 (PR #31) | ✅ |
-| 25 | Site picker honesty + site-as-tested-surface CI guard | Wave 1 | ✅ |
-| 26 | QMS bilingual EN+TR mirror + `tools/check_anchor_resolution.py` | Wave 4 (PR #33) | ✅ |
-| 27 | Silent `except Exception:` sweep | Wave 1 | ✅ |
-| 28 | Remaining Major + Minor cleanup | Wave 3 (PR #31) | ✅ |
-| 29 | Nit sweep (40-item mass-edit) | Wave 1 | ✅ |
-| 30 | Final documentation + site finalization (EN+TR only) | Wave 4 partial + Wave 5 full sweep | ✅ |
-| 31 | Cross-OS release-tag matrix workflow | Wave 1 | ✅ |
-| 32 | `.pre-commit-config.yaml` (optional) | Wave 1 | ✅ |
-| 33 | **v0.5.5 RELEASE** (CHANGELOG, version bump, tag, PyPI) | POST-WAVE | ⏳ |
-| 34 | `forgelm doctor` env-check subcommand (GH-001) | Wave 2a (PR #28) | ✅ |
-| 35 | Air-gap pre-cache (`cache-models` + `cache-tasks`) (GH-002, GH-003) | Wave 2b (PR #30) | ✅ |
-| 36 | Compliance verification toolbelt (`safety-eval`, `verify-annex-iv`, `verify-gguf`) (GH-004/005/009) | Wave 2b (PR #30) | ✅ |
-| 37 | `forgelm approvals` listing subcommand (GH-007) | Wave 2a (PR #28) | ✅ |
-| 38 | `forgelm reverse-pii` GDPR Article 15 subcommand (GH-014) | Wave 3 (PR #31) | ✅ |
-
-**Total:** 38 fazlar / ~52 PRs (multi-PR series counted separately).
-
-## Wave-by-wave outcomes
-
-### Wave 0 / 1 (PR #19, PR #21)
-
-Foundation + the bulk of the master-review backlog — fazlar 1-15, 25, 27, 29, 31, 32. Site honesty fixes, CI gates, audit log forensic completeness, performance pass, the two big package splits (`data_audit/` 5-PR series, `cli/` 6-PR series).
-
-### Wave 2a (PR #28, 2026-05-04)
-
-5 fazlar: 17 (`audit --workers N`), 18 (Library API design), 20 (GDPR design), 34 (`doctor`), 37 (`approvals`).
-
-### Wave 2b (PR #30, 2026-05-05, merge `b05edb5`)
-
-5 fazlar: 16 (Pydantic `description=` migration), 19 (Library API implementation), 21 (GDPR erasure implementation), 35 (air-gap pre-cache), 36 (compliance verification toolbelt). Suite 1160 → 1298 (+138). 6 absorption rounds + 4-agent final review + 4 followup absorption commits.
-
-### Wave 3 (PR #31, 2026-05-05, merge `b87c872`)
-
-3 fazlar: 24 (bilingual TR mirror sweep + `tools/check_bilingual_parity.py`), 28 (curated Tier 1+2 cleanup), 38 (`reverse-pii`). Suite 1298 → 1374 (+76). Behaviour changes: high-risk + unacceptable + safety-disabled now `ConfigError` (F-compliance-110); webhook timeout 5s → 10s default (F-compliance-106).
-
-### Wave 4 (PR #33, 2026-05-06, merge `01e40ba`)
-
-4 fazlar: 22 + 23 (ISO 27001 / SOC 2 alignment design + implementation), 26 (QMS bilingual mirror + `tools/check_anchor_resolution.py` + `compliance_summary.md` rewrite), 30 partial (Tier 1 ghost-feature drift + stat blocks). Suite 1374 → 1411 (+37: 16 supply-chain + 21 anchor checker). Bilingual parity scope 9/9 → 23/23 pairs.
-
-### Wave 5 (PR #34 merged `8f9f951`, 2026-05-06)
-
-Faz 30 full sweep: residual ghost-feature drift (GH-011 benchmarks, GH-016 `--export-bundle`, GH-018 deploy-targets `kserve`/`triton`, GH-020 ingest flag drift); Task A doc-triplet completion (~12 features × {guide, reference, usermanual} × {EN, TR} ≈ 50 new files — landed in commit `2a32842`); Task J `tools/check_cli_help_consistency.py` (commit `c7bedc9`); Task N anchor-checker `--strict` flip + 36-baseline cleanup (commit `fbb082d`); Tasks B/C `_meta.yaml` + `build_usermanuals.py` rebuild; Task D site/* finalization; Tasks E/F/G README + CONTRIBUTING + CLAUDE + roadmap + standards final pass; Tasks H/I/K/L/M parity strict + site-claim CI + config regen + locale policy + diagrams.
-
-### Faz 33 (POST-WAVE)
-
-The actual v0.5.5 PyPI publish:
-
-1. `pyproject.toml` `version = "0.5.5"` — already bumped during Wave 5 Task D (`4610dc6`) so `check_site_claims.py --strict` can pin the site → code version parity. Faz 33 only confirms it remains `0.5.5` and adds the date to the `[0.5.5]` CHANGELOG section.
-2. CHANGELOG `[Unreleased]` → `[0.5.5] — YYYY-MM-DD`
-3. `git tag -s v0.5.5 -m "v0.5.5 — Closure Cycle Bundle"`
-4. `git push origin main v0.5.5`
-5. `publish.yml` runs: build → cross-OS matrix (12 combos) → publish (OIDC trusted publishing, no API token)
-
-The cut-release skill ([`.claude/skills/cut-release/SKILL.md`](../../.claude/skills/cut-release/SKILL.md)) walks the maintainer through the sequence step-by-step.
-
-## Quality dimensions reached
-
-Per the closure plan §1 baseline + §9 exit criteria:
-
-| Dimension | Pre-Wave-0 | Post-Wave-5 target |
-|---|---|---|
-| Business | ★★★½ | ★★★★★ |
-| Code | ★★★½ | ★★★★★ |
-| Compliance | ★★★★ | ★★★★★ |
-| Documentation | ★★★½ | ★★★★★ |
-| Localization | ★★★ | ★★★★★ (EN+TR; DE/FR/ES/ZH user-manual deferred by user decision) |
-| Performance | ★★★★ | ★★★★★ |
-| Security | ★★★★ | ★★★★★ |
-| Testing & CI/CD | ★★★½ | ★★★★★ |
-
-## Related
-
-- [`releases.md`](releases.md) — v0.5.5 release notes
-- [`risks-and-decisions.md`](risks-and-decisions.md) — closure-cycle decision log entries
-- [`CHANGELOG.md`](../../CHANGELOG.md) — `[0.5.5]` section (finalized at release; per-PR closure entries collapse into the v0.5.5 release notes)
diff --git a/docs/roadmap/phase-12-data-curation-maturity.md b/docs/roadmap/phase-12-data-curation-maturity.md
deleted file mode 100644
index 9b8c2811..00000000
--- a/docs/roadmap/phase-12-data-curation-maturity.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# Phase 12: Data Curation Maturity
-
-> **Note (post-consolidation):** Originally targeted `v0.5.2`, now ships
-> as part of the consolidated `v0.5.0` release alongside Phases 11, 11.5,
-> and 12.5 — see [releases.md](releases.md#v050-document-ingestion-data-curation-pipeline).
-> Version-label references below preserve the historical planning trail.
->
-> **Status:** ✅ **Tier 1 DONE** — landed on `development` for the (originally) `v0.5.2` cycle. All five must-have tasks shipped: MinHash LSH dedup option (`[ingestion-scale]` extra via `datasketch`), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`[ingestion-secrets]` extra via `detect-secrets` with regex fallback), heuristic quality filter (`--quality-filter`), DOCX/Markdown table preservation. Tier 2 (Presidio adapter, Croissant metadata) and Tier 3 (`--all-mask` composite, wizard "audit first" hook) are deferred to a follow-up **Phase 12.5** backlog file (analogous to Phase 11.5 → `phase-11-5-backlog.md`). Modules: [`forgelm/data_audit.py`](../../forgelm/data_audit/), [`forgelm/ingestion.py`](../../forgelm/ingestion.py), [`forgelm/cli.py`](../../forgelm/cli/); tests: [`tests/test_data_audit_phase12.py`](../../tests/test_data_audit_phase12.py), [`tests/test_ingestion_phase12.py`](../../tests/test_ingestion_phase12.py); CLI tests added in [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py).
-
-> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md). Phase 11 + 11.5 built the ingestion / audit lineage (Phase 11 → `v0.5.0`, Phase 11.5 → `v0.5.1`); this phase moves the same lineage from **enterprise-acceptable** to **enterprise-competitive**.
-
-**Goal:** Mature ForgeLM's `forgelm ingest` + `forgelm audit` layer along three axes — **scale** (LSH-based near-duplicate detection beyond ~50K rows, large-corpus throughput), **security** (code/secret leakage scanning + optional ML-based PII), and **quality** (markdown-aware chunking + heuristic quality filters + table structure preservation). The competitive review that followed Phase 11.5 (see `docs/roadmap/phase-11-5-backlog.md` "Measured speedups" section + the 2026-04-27 ingestion-comparison synthesis) lists the exact gaps this phase closes.
-
-**Estimated Effort:** Medium (4-6 weeks) — **Actual: ~1 day** (single-author implementation, leveraging the streaming aggregator + tier-mapped pattern from Phase 11.5).
-**Priority:** High — answers the enterprise demand surfaced after the `v0.5.0` PyPI launch; sequences naturally with Phase 14 (Multi-Stage Pipeline Chains), which is reslotted to `v0.5.3`.
-
-> **Context:** Phase 11 shipped multi-format extraction (PDF/DOCX/EPUB/TXT/MD) + paragraph/sliding chunkers; Phase 11.5 added token-aware chunking, PDF page-level header/footer dedup, the `forgelm audit` subcommand, PII severity tiers, LSH-banded simhash dedup, and atomic JSON writes. The cross-tool comparison (LLaMA-Factory / Axolotl / Unsloth / NeMo Curator / Dolma / RedPajama / LlamaIndex / LangChain / Marker / Docling) found ForgeLM **uncontested** in the *fine-tuning + compliance* niche but **behind** in four concrete areas: (1) MinHash LSH dedup for >50K-row corpora, (2) heading-preserving markdown chunking, (3) code / credential leakage scanning, (4) DOCX/PDF table structure preservation. This phase closes those four. Layout-aware PDF parsing (Marker/Docling delegation) and embedding-based semantic dedup are **deliberately deferred to Phase 13+** — adding either would require runtime ML dependencies that conflict with the project's "we don't write our own quantization / VLM" boundary (codified in `CLAUDE.md` "What ForgeLM is not") and the air-gapped reproducibility guarantees Annex IV depends on.
-
-## Tasks
-
-### Tier 1 — Must-have (Phase 12's thesis)
-
-1. [x] **MinHash LSH dedup option** (`[ingestion-scale]` extra, `datasketch>=1.6.0,<2.0.0`)
-   `find_near_duplicates` and `_count_leaked_rows` keep simhash + LSH banding as the **default**; an opt-in `--dedup-method minhash --jaccard-threshold 0.85` route delegates to [datasketch](https://github.com/ekzhu/datasketch) `MinHashLSH`. Simhash is ideal up to ~50K rows; MinHash LSH is the industry standard above that scale (NeMo Curator, Dolma, RedPajama all use it). Surface contract:
-   ```bash
-   forgelm audit data/large_corpus.jsonl --dedup-method minhash --jaccard-threshold 0.85
-   ```
-   ```python
-   # Programmatic:
-   forgelm.data_audit.audit_dataset(..., dedup_method="minhash", minhash_jaccard=0.85)
-   ```
-   `cross_split_overlap` and `near_duplicate_pairs` share the same method parameter. Audit JSON gains `near_duplicate_summary.method: "minhash" | "simhash"`; default-method audits stay **schema-additive** (older parsers reading `pairs_per_split` keep working unchanged) — the on-disk JSON is *not* byte-identical because `near_duplicate_summary.method` and `cross_split_overlap.method` are now always present alongside the existing fields.
-
-2. [x] **Markdown-aware splitter** (new third strategy: `--strategy markdown`)
-   `_chunk_markdown(text, max_chars_or_tokens, ...)` parses heading hierarchy (`# H1` / `## H2` / `### H3`); breaks chunks at heading boundaries; inlines the heading path **into the chunk body** (`# H1 / ## H2\n\n…`) rather than as a separate metadata field — output stays `{"text": "..."}` JSONL so SFT loss benefits from the heading signal. Code-block (` ``` `) and list-item boundaries are preserved (no mid-code-block splits). Composes with token-aware mode: `--strategy markdown --chunk-tokens 1024 --tokenizer Qwen/Qwen2.5-7B-Instruct`. Existing `paragraph` and `sliding` behaviour stays byte-identical.
-
-3. [x] **Code / secrets leakage tagger** (`[ingestion-secrets]` extra, `detect-secrets>=1.5.0,<2.0.0`)
-   Audit gains a `secrets_summary` block: AWS / GCP / Azure access keys, GitHub / GitLab / Slack tokens, OpenSSH / PGP private-key headers, JWT, OpenAI API keys (`sk-…`), generic high-entropy strings. Audit JSON shape:
-   ```json
-   {
-     "secrets_summary": {
-       "total": 3,
-       "by_type": {"aws_access_key": 1, "github_token": 2},
-       "lines_flagged": 3
-     }
-   }
-   ```
-   Ingest side: `--secrets-mask` flag mirrors `--pii-mask`'s helper pattern, replacing detected spans with `[REDACTED-SECRET]`. The `detect-secrets` package is optional; without it a regex-only fallback set (~10 common patterns) runs and an INFO log says *"install `forgelm[ingestion-secrets]` for full coverage"*. Compliance angle is **critical** — credentials leaked into an SFT corpus are memorised by the trained model; Phase 12 is the first line of defence for this risk class.
-
-4. [x] **Heuristic quality filter** (audit-side, opt-in `forgelm audit --quality-filter`)
-   Classic Gopher / C4 / RefinedWeb heuristics: mean-word-length (flag if outside 3-12 chars), alphabetic-character ratio (< 70 % → flag), end-of-line punctuation ratio (< 50 % → flag), repeated-line ratio (top-3 distinct lines covering > 30 % of non-empty lines → flag), short-paragraph ratio (`\n\n`-separated blocks with < 5 words, > 50 % of total → flag). Markdown fenced code blocks are stripped before heuristics run so legitimate code rows don't trip the prose-oriented checks. Opt-in default-off; new `quality_summary`:
-   ```json
-   {
-     "quality_summary": {
-       "samples_flagged": 47,
-       "by_check": {
-         "low_alpha_ratio": 12,
-         "low_punct_endings": 8,
-         "abnormal_mean_word_length": 3,
-         "short_paragraphs": 27,
-         "repeated_lines": 5
-       },
-       "overall_quality_score": 0.94
-     }
-   }
-   ```
-   ML-based classifiers (NeMo Curator's fastText / DeBERTa quality model) are **out of scope** — deferred to Phase 13+ (model dependency, non-deterministic, reproducibility risk).
-
-5. [x] **DOCX / Markdown table preservation**
-   `_extract_docx` replaces the current `" | "` flat join with markdown table syntax:
-   ```text
-   | Header 1 | Header 2 | Header 3 |
-   |---|---|---|
-   | Cell A1  | Cell A2  | Cell A3  |
-   ```
-   PDF tables stay flat — `pypdf`'s table support is weak and Docling delegation is Phase 13+ scope. The Markdown extractor (`.md` route) already expects markdown, so the new strategy aligns naturally. SFT use cases where this matters (code-assistant, financial-assistant, tabular Q&A) get a noticeable lift; that lift is measured post-merge, not gated on Phase 12 acceptance.
-
-### Tier 2 — Should-have (Phase 12 if scope allows; otherwise Phase 12.5)
-
-6. [ ] **Presidio adapter** (`[ingestion-pii-ml]` extra, optional)
-   ForgeLM keeps the regex + Luhn + TC Kimlik checksum PII detector as the **default**. `--pii-engine presidio` opts into Microsoft Presidio for the ML-NER signals regex misses (person names, organisations, locations). Presidio output maps into the existing `pii_severity` table with a new tier (`person_name` → medium, `organization` → low). Scope is ingest-side only; audit contract is unchanged. Fallback: missing Presidio → INFO log *"install `forgelm[ingestion-pii-ml]` for ML-based detection"*.
-
-7. [ ] **Croissant metadata compatibility** (audit JSON, optional)
-   Audit report gains a top-level `croissant_compatible: true` flag plus a subset of Google's [Croissant ML metadata](https://github.com/mlcommons/croissant) schema fields (`@type: "sc:Dataset"`, `name`, `description`, `recordSet`, …). Combined with the EU AI Act Article 10 governance bundle, this produces a **dual-standard** artifact — both Croissant consumers and AI Act auditors can parse the same file. Opt-in: `--croissant` flag or programmatic `croissant=True`. Existing audit consumers are unaffected (additive only).
-
-### Tier 3 — Could-have (skip if scope is exhausted)
-
-8. [ ] **`forgelm ingest --secrets-mask` + `--pii-mask` composite flag**
-   Runs both masking passes sequentially in one ingest pass (secrets first — high-entropy spans masked; PII second — remaining spans). Order matters because some secrets (GitHub tokens) partially match PII regexes (`de_id`-shaped). Single-flag shorthand: `--all-mask` enables both. Test: known fixtures combining secrets + PII, roundtrip + masked-output coverage.
-
-9. [ ] **Wizard "audit first" entry point**
-   Phase 11.5 added the ingest-first hook. Phase 12 mirrors it for symmetry: when the user provides a JSONL path, the wizard offers to run `forgelm audit` automatically; the summary is printed to stdout and the user decides whether to proceed based on the leakage / PII / quality verdicts. UX shape: *"Detected 18 emails, 1 critical-tier PII (credit card), and 7 near-duplicate pairs in your dataset. Continue training?"*. New helper: `_offer_audit_for_jsonl`.
-
-## Won't-do (deliberately out of Phase 12 scope)
-
-- ❌ **VLM-based PDF parsing** (Marker / Docling / Nemotron-Parse) — Phase 13+ scope. ForgeLM holds the "we don't write our own VLM" line (codified in `CLAUDE.md` "What ForgeLM is not"); even external delegation (Docling) adds runtime weight + risks the air-gapped guarantee. Ships as a separate optional extra in a later phase.
-- ❌ **Embedding-based semantic dedup** (NeMo Curator `semantic.py` analogue) — runtime embedding-model dependency + non-deterministic chunk counts violate Annex IV reproducibility. Deferred to Phase 13+ (only viable if a deterministic-snapshot mode is designed first).
-- ❌ **Built-in OCR** — out of scope since Phase 11; docs already point at Tesseract / AWS Textract recipes. This stays unchanged.
-- ❌ **ML-based quality classifier** (fastText / DeBERTa) — non-deterministic + model-snapshot dependency. The heuristic filter in Tier 1 #4 is sufficient for this phase; classifiers are Phase 13+.
-- ❌ **GPU/Ray-scale execution** (NeMo Curator territory) — ForgeLM's niche is *small-to-medium corpus, enterprise compliance*. 8 TB pretraining curation is NeMo Curator's job; ForgeLM should be sufficient for 100K–1M-row SFT corpora, which Phase 12 (streaming + LSH) achieves without distributed runtime.
-- ❌ **HTML extractor** — useful for enterprise scrape (intranet wikis) but scope creep. Operators can pre-process with BeautifulSoup; ForgeLM doesn't need to ingest HTML directly.
-
-## Requirements
-
-- **Backward compatibility**: Default-flag `forgelm ingest` and `forgelm audit` outputs are **schema-additive** with v0.5.1 (older parsers keep working) — they are *not* byte-identical because new always-on fields (`secrets_summary`, `near_duplicate_summary.method`, `cross_split_overlap.method`) are now part of every report. v0.5.1 audit consumers must parse v0.5.2 reports without changes; the stdout JSON envelope retains the v0.5.1 `near_duplicate_pairs_per_split` key alongside the richer `near_duplicate_summary`.
-- **Optional extras**: Every new heavy dependency (`datasketch`, `detect-secrets`, `presidio-analyzer`) goes under `pyproject.toml` `[project.optional-dependencies]` with the `ImportError` + install-hint pattern from `docs/standards/architecture.md` §3.
-- **Determinism**: Every new path (MinHash, markdown chunker, secrets scan, quality heuristics) preserves the fixed-input → fixed-output contract. Annex IV reproducibility guarantee.
-- **CLI**: All new flags appear in `forgelm audit --help` and `forgelm ingest --help`; `--output-format json` envelope is additive.
-- **Compliance**: New audit fields (`secrets_summary`, `quality_summary`) are auto-inlined into the governance bundle by `forgelm/compliance.py::_maybe_inline_audit_report` without code changes — the existing `json.load` path passes them through as-is.
-- **Documentation**: `docs/guides/ingestion.md` + TR mirror, `docs/guides/data_audit.md` + TR mirror, `docs/qms/sop_data_management.md` (new SOP step for secrets scan + quality filter), `CHANGELOG.md`, `docs/reference/usage.md` + TR mirror, `docs/standards/architecture.md` extras matrix.
-- **Tests**: At least three tests per Tier 1 task (happy path + edge case + extras-skip). MinHash needs a `test_minhash_parity_with_simhash_at_default_threshold` (LSH parity-style). Markdown splitter needs a heading-preservation test. Secrets needs known-fixture roundtrip + mask test.
-- **Smoke**: `forgelm --config config_template.yaml --dry-run` must produce v0.5.1-equivalent output; new flags have no effect on dry-run.
-- **Lint + coverage**: ruff clean, coverage stays at `fail_under=40` (Phase 12 adds new code; tests must not drop the floor).
-
-## Kill criteria
-
-For the quarterly gate review:
-
-- **Tier 1 task #1 (MinHash LSH)**: If it doesn't land within 6 weeks **and** a 100K-row smoke fixture under `forgelm audit --dedup-method minhash` doesn't beat the brute-force O(n²) baseline by ≥ 5× → demote to Tier 2, keep simhash as default, push the MinHash extra to v0.5.3.
-- **Tier 1 task #4 (Quality filter)**: If false-positive rate on industry benchmark fixtures exceeds 10 % → opt-in default-off (already the plan), document the limitation, add a *"calibrate before applying"* note for operators.
-- **Compatibility regression**: If a v0.5.1 audit consumer (the Phase 11/11.5 compliance bundle inliner) cannot parse a v0.5.2 report → kill, roll back any non-additive changes.
-- **Performance regression**: If the default simhash path slows by > 5 % vs. the Phase 11.5 baseline (`tools/bench_simhash.py`) → revisit the refactor.
-
-If fewer than three Tier 1 items land within three months, Phase 12 is reset; the "Data Curation Maturity" thesis is re-examined (refresh the competitive analysis, ask whether it's still the right work).
-
-## Delivery
-
-- **Target release: `v0.5.2`** — natural continuation of Phase 11.5 (`v0.5.1`). Phase 14 (Multi-Stage Pipeline Chains) is reslotted from `v0.5.2` to `v0.5.3`.
-- Phase 14 reslot rationale: Phase 12 is an extension of the ingestion lineage and shares thematic continuity with Phase 11.5; Phase 14 is an independent feature whose 3-6-week scope can run after Phase 12 with a parallel implementer. Phase 14 has high enterprise demand, but the EU AI Act enforcement deadline (August 2026) gives the audit / secrets surface higher near-term weight.
-- Phase 13 (Pro CLI) `v0.6.0-pro` — after Phase 12 + 14, traction-gated.
-- Roadmap table (`docs/roadmap.md` + TR mirror), the mermaid diagram, and `releases.md` are all updated by this phase doc; this file pins those commitments.
-
-## Module touchpoints
-
-| Module | Change | Risk |
-|---|---|---|
-| `forgelm/data_audit.py` | `compute_minhash`, `find_near_duplicates_minhash`, `_count_leaked_rows_minhash` (parallel API surface); `secrets_summary` builder; `quality_summary` builder; `audit_dataset(..., dedup_method=...)` parameter | Low — additive; default behaviour preserved |
-| `forgelm/ingestion.py` | `_chunk_markdown`, `_strategy_dispatch` "markdown" branch; `_extract_docx` markdown-table output; `--secrets-mask` extractor wiring | Low-medium — DOCX output shape changes; v0.5.1 fixtures must update |
-| `forgelm/cli.py` | `--strategy markdown`, `--dedup-method`, `--jaccard-threshold`, `--quality-filter`, `--secrets-mask`, `--pii-engine`, `--croissant` flags | Low — argparse additions only |
-| `forgelm/wizard.py` | (Tier 3) `_offer_audit_for_jsonl` helper; BYOD path post-validation hook | Low — opt-in pattern, symmetric with the existing `_offer_ingest_for_directory` |
-| `pyproject.toml` | New extras: `[ingestion-scale]` (datasketch), `[ingestion-secrets]` (detect-secrets), `[ingestion-pii-ml]` (presidio-analyzer); version bump `0.5.1rc1 → 0.5.2rc1` | Low |
-| `docs/guides/{ingestion,data_audit}{,-tr}.md` | New sections: markdown splitter, secrets scan, quality filter, MinHash; legacy CLI patterns preserved | Low |
-| `docs/qms/sop_data_management.md` | Quality-check checklist gains `--quality-filter` + secrets-scan rows; v0.5.1 `forgelm audit` is already documented (Phase 11.5 update) | Low |
-| `docs/standards/architecture.md` | Extras matrix gains `ingestion-scale`, `ingestion-secrets`, `ingestion-pii-ml` rows | Low |
-| `CHANGELOG.md` | New "Unreleased — Phase 12 (Data Curation Maturity, targeting v0.5.2)" section | Low |
-
-## Suggested sequencing (4-6 week plan)
-
-| Week | Work | Output |
-|---|---|---|
-| 1 | Tier 1 #1 — MinHash LSH dedup + datasketch extra + tests | `compute_minhash`, parity test, `--dedup-method` flag |
-| 2 | Tier 1 #2 — Markdown splitter + token-aware composition + tests | `_chunk_markdown`, `--strategy markdown`, heading-preservation test |
-| 3 | Tier 1 #3 — Code/secrets scan + extra + ingest `--secrets-mask` + tests | `secrets_summary`, detect-secrets integration, mask roundtrip test |
-| 4 | Tier 1 #4 + #5 — Quality filter + DOCX table preservation + tests | `quality_summary`, markdown-table output, fixture tests |
-| 5 | Tier 2 #6 — Presidio adapter (if scope allows) + Tier 2 #7 Croissant metadata | `--pii-engine presidio`, `--croissant` flag |
-| 6 | Docs + roadmap + smoke + tag prep | Guides, CHANGELOG, releases.md, `v0.5.2rc1` |
-
-Tier 3 items (composite mask, wizard audit-first) either join Weeks 5-6 if scope permits, or move to a Phase 12.5 backlog file.
-
----
diff --git a/docs/roadmap/phase-14-pipeline-chains.md b/docs/roadmap/phase-14-pipeline-chains.md
index 6a07f346..8afbe86f 100644
--- a/docs/roadmap/phase-14-pipeline-chains.md
+++ b/docs/roadmap/phase-14-pipeline-chains.md
@@ -70,7 +70,7 @@
 - `--dry-run` validates all stages' configs before any GPU allocation.
 
 ### Delivery:
-- Target release: `v0.6.0` (reslotted from earlier `v0.5.x` placeholders; Phase 14 is grouped with the Phase 13 Pro CLI tier per the v0.5.5 closure cycle's deferred-callout policy in `docs/usermanuals/{en,tr}/deployment/model-merging.md` and the [phase-12-6-closure-cycle.md](phase-12-6-closure-cycle.md) summary).
+- Target release: `v0.6.0` (reslotted from earlier `v0.5.x` placeholders; Phase 14 is grouped with the Phase 13 Pro CLI tier per the v0.5.5 closure cycle's deferred-callout policy in `docs/usermanuals/{en,tr}/deployment/model-merging.md` and the [phase-12-6-closure-cycle.md](completed-phases.md) summary).
 - No hard blockers; the v0.5.5 closure cycle has merged. Phase 14 starts after the v0.5.5 PyPI tag is published.
 
 ---
diff --git a/docs/roadmap/releases.md b/docs/roadmap/releases.md
index 182a6139..1ff7e0b9 100644
--- a/docs/roadmap/releases.md
+++ b/docs/roadmap/releases.md
@@ -42,7 +42,7 @@
 
 **Status:** Released — published to PyPI on 2026-04-26 ([release notes](https://github.com/cemililik/ForgeLM/releases/tag/v0.4.0)).
 
-Odak: [Phase 10](phase-10-post-training.md). Full post-training handoff: inference, chat, GGUF export, VRAM fit-check, deployment config generation.
+Odak: [Phase 10](completed-phases.md). Full post-training handoff: inference, chat, GGUF export, VRAM fit-check, deployment config generation.
 
 ### Features:
 1. [x] **`forgelm/inference.py`** — Shared generation primitives: `load_model`, `generate`, `generate_stream` (streaming via background thread, with timeout-based deadlock guard), `logit_stats`, `adaptive_sample`. Supports transformers + peft (merge-and-unload) + unsloth backends.
@@ -60,7 +60,7 @@ Odak: [Phase 10](phase-10-post-training.md). Full post-training handoff: inferen
 
 ## v0.4.5 — "Quickstart Layer" (2026-04-26)
 
-**Status:** Released — published to PyPI on 2026-04-26 ([release notes](https://github.com/cemililik/ForgeLM/releases/tag/v0.4.5)). Focus: [Phase 10.5](phase-10-5-quickstart.md) (Quickstart). One-command bundled templates, sample datasets, opinionated defaults — primary community growth driver.
+**Status:** Released — published to PyPI on 2026-04-26 ([release notes](https://github.com/cemililik/ForgeLM/releases/tag/v0.4.5)). Focus: [Phase 10.5](completed-phases.md) (Quickstart). One-command bundled templates, sample datasets, opinionated defaults — primary community growth driver.
 
 ### Features:
 1. [x] **`forgelm/quickstart.py`** — Template registry (`@dataclass(frozen=True) Template`), `auto_select_model()` GPU-aware downsizing (≥10 GB VRAM → primary model; otherwise fallback ≤2B), `run_quickstart()` end-to-end orchestrator that copies the bundled seed dataset, substitutes `model.name_or_path` and `data.dataset_name_or_path`, and writes a `configs/<template>-YYYYMMDDHHMMSS.yaml` the existing trainer accepts unchanged.
diff --git a/docs/standards/documentation.md b/docs/standards/documentation.md
index 03cd2f5c..b2207165 100644
--- a/docs/standards/documentation.md
+++ b/docs/standards/documentation.md
@@ -33,7 +33,7 @@ docs/
 | End user deploying in a regulated org | `qms/` | `qms/sop_model_training.md` |
 | Contributor writing code | `standards/` | this file |
 | Contributor understanding "why" | `design/` | `design/wizard_mode.md` |
-| Planner tracking work | `roadmap/` | `roadmap/phase-10-post-training.md` |
+| Planner tracking work | `roadmap/` | `roadmap/completed-phases.md` |
 
 If a doc doesn't fit any of these, it probably doesn't belong in `docs/`. Long thinking / drafts / PR-cycle audit notes / external-repo comparisons live under gitignored working-memory directories (`docs/marketing/`, `docs/analysis/`) and **must not be linked from public docs or production code** — see "Working-memory directories" below.
 
diff --git a/docs/standards/release.md b/docs/standards/release.md
index 8de24990..0a91e0e7 100644
--- a/docs/standards/release.md
+++ b/docs/standards/release.md
@@ -284,7 +284,7 @@ The closure-cycle bundle is the largest single release in ForgeLM history (38 fa
 
 1. **`pyproject.toml`** — bump `version = "0.5.1rc1"` → `"0.5.5"` (single source of truth).
 2. **`forgelm/_version.py`** — review whether `__api_version__` needs a MINOR bump for the new Library API symbols (`ForgeTrainer`, `run_audit`, `verify_*`, `gdpr_purge`, `reverse_pii_query`, ...) added across Wave 2b + 3. Per the `__api_version__` rules at the top of this standard: yes, every new public symbol added to `forgelm.__all__` since the previous tag is a MINOR bump.
-3. **`CHANGELOG.md`** — move all `[Unreleased]` entries into a new `[0.5.5] — YYYY-MM-DD` section. Cross-reference each entry to its faz number (e.g. "Library API — Wave 2b / Faz 19") so reviewers can map back to the [phase-12-6-closure-cycle.md](../roadmap/phase-12-6-closure-cycle.md) inventory.
+3. **`CHANGELOG.md`** — move all `[Unreleased]` entries into a new `[0.5.5] — YYYY-MM-DD` section. Cross-reference each entry to its faz number (e.g. "Library API — Wave 2b / Faz 19") so reviewers can map back to the [completed-phases.md](../roadmap/completed-phases.md) inventory.
 4. **Tag** — `git tag -s v0.5.5 -m "v0.5.5 — Closure Cycle Bundle"`.
 5. **Push** — `git push origin main v0.5.5`. The tag push is the contract; `publish.yml` fires automatically.
 6. **Wait for matrix** — the cross-OS matrix runs 12 combos (3 OS × 4 Python). Each combo emits a per-(OS, Python) CycloneDX 1.5 SBOM (12 SBOM artifacts per release tag) — that is the full supply-chain output of the release pipeline. `pip-audit` is **not** run by `publish.yml`; vulnerability gating runs daily on `main` via [`.github/workflows/nightly.yml`](../../.github/workflows/nightly.yml) (the `pip-audit-gate` job calling `tools/check_pip_audit.py`), so every commit reaching a tag has already been audited within the last 24 hours. Total matrix runtime ~25-40 minutes.
diff --git a/forgelm/ingestion.py b/forgelm/ingestion.py
index 7de62430..d5520481 100644
--- a/forgelm/ingestion.py
+++ b/forgelm/ingestion.py
@@ -516,7 +516,7 @@ def _chunk_paragraph(text: str, max_chunk_size: int) -> Iterable[str]:
 
 def _chunk_semantic(text: str, chunk_size: int) -> Iterable[str]:
     # Embedding-based semantic chunking was deliberately deferred past
-    # Phase 12 (see docs/roadmap/phase-12-data-curation-maturity.md — the
+    # Phase 12 (see docs/roadmap/completed-phases.md — the
     # "deferred to Phase 13+" entry on embedding-based semantic dedup)
     # because a runtime embedding-model dependency conflicts with the
     # air-gapped Annex IV reproducibility guarantee. The closure plan
@@ -526,7 +526,7 @@ def _chunk_semantic(text: str, chunk_size: int) -> Iterable[str]:
     # F-PR29-A6-05-issue-link.
     raise NotImplementedError(
         "Semantic chunking requires an embedding model and is deferred past "
-        "Phase 12 (see docs/roadmap/phase-12-data-curation-maturity.md — "
+        "Phase 12 (see docs/roadmap/completed-phases.md — "
         "embedding-based semantic dedup deferred to Phase 13+ for Annex IV "
         "reproducibility); tracked under F-PR29-A6-05-issue-link in "
         "docs/roadmap/risks-and-decisions.md. Use 'sliding' or 'paragraph' "
diff --git a/tests/test_phase12_5.py b/tests/test_phase12_5.py
index 344a4f83..6890e4d6 100644
--- a/tests/test_phase12_5.py
+++ b/tests/test_phase12_5.py
@@ -1,7 +1,7 @@
 """Phase 12.5 — data curation polish backlog.
 
 Covers the four follow-up items from
-:mod:`docs/roadmap/phase-12-5-backlog.md`:
+:mod:`docs/roadmap/completed-phases.md`:
 
 1. ``forgelm ingest --all-mask`` composite shorthand (this file).
 2. Wizard "audit first" entry point (this file).
diff --git a/tools/bench_simhash.py b/tools/bench_simhash.py
index c0a0cb1f..5cab94d3 100644
--- a/tools/bench_simhash.py
+++ b/tools/bench_simhash.py
@@ -15,7 +15,7 @@
     python tools/bench_simhash.py
 
 Results are written to stdout; copy the table back into
-``docs/roadmap/phase-11-5-backlog.md`` if it has shifted materially after
+``docs/roadmap/completed-phases.md`` if it has shifted materially after
 a backend / dependency / Python version change.
 
 The corpus generators below are **fully deterministic**: they walk

From e080da6f34f72fa1d813b3b54c7859b0392c5dc5 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Sun, 10 May 2026 23:16:48 +0300
Subject: [PATCH 2/7] =?UTF-8?q?fix(roadmap):=20PR=20#44=20review=20absorpt?=
 =?UTF-8?q?ion=20=E2=80=94=20placeholder=20+=20Turkish=20drift=20cleanup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR #44 review absorption: gemini-code-assist + sourcery-ai flagged
five medium issues introduced by the consolidation script's
intermediate placeholders + Turkish-term drift in the now-canonical
English-only completed-phases.md archive.

Fixed (5):

- completed-phases.md:722  "renamed to (see relevant Phase section
  above/below)" → "renamed to its current filename slug" (the
  filename history sentence is now grammatical and self-contained)
- completed-phases.md:932  "(analogous to Phase 11.5 → (see relevant
  Phase section above/below))" → resolves to the in-document anchor
  "[Phase 11.5 section above](#phase-115-ingestion-audit-polish)"
- completed-phases.md:1133 "[(see relevant Phase section above/below)]
  (#section-below)" → "[Phase 12 — Data Curation Maturity]
  (#phase-12-data-curation-maturity)"
- completed-phases.md (Phase 12.6 closure-cycle section) "fazlar"
  / "Faz 33" / "Faz 30" / "Faz inventory" → "tasks" / "Task 33" /
  "Task 30" / "Task inventory". Closure-cycle had 38 numbered tasks
  internally; "task" reads naturally and avoids overlap with the
  outer "Phase 12.6" heading.
- completed-phases.md (Phase 10/11/12 sections) — three orphaned
  Turkish "Not: Bu dosya tek bir planlanan fazı detaylandırır..."
  intro lines absorbed from the deleted phase files. Removed
  (the claim is no longer true after consolidation); the Phase 12
  lineage note is preserved in English ("Phase 11 + 11.5 built the
  ingestion / audit lineage ...").

Also fixed:

- docs/roadmap.md:13  "37 content fazlar + 1 release tag" →
  "37 content phases + 1 release tag"
- docs/roadmap.md:36  "Phase 12.6 / Faz dual-axis note" → "Phase
  12.6 task / sub-task dual-axis note"; "(Faz 1-38)" → "(Tasks 1-38)"
- CHANGELOG.md (v0.5.5 [0.5.5] section) "**`forgelm/_http.safe_post`**
  (Faz 7 carry-over)" → "**`forgelm/_http.safe_post`**" (drop the
  internal-only Wave/Faz parenthetical; the surrounding paragraph
  already explains the carry-over)

Skipped:

- *gemini-code-assist on docs/roadmap.md TR mirror "fazlar"* — N/A,
  docs/roadmap-tr.md is the Turkish mirror and "fazlar" is the
  correct Turkish term there.
- *CHANGELOG.md:1118 v0.5.0 section "(Faz 12)"* — historical entry,
  out of scope for the v0.5.5 cleanup the user authorized.

Verified: all 6 doc CI guards green (anchor 266 files, parity 45
pairs, cli-help 439 invocations, wizard-defaults 3/8,
no-analysis-refs, dry-run).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                     |  2 +-
 docs/roadmap.md                  |  4 +--
 docs/roadmap/completed-phases.md | 45 ++++++++++++++------------------
 3 files changed, 23 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a0973cb0..a45394f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -412,7 +412,7 @@ collectors / BYOD / IO concerns.
   refusal, secret-mask error path, TLS verify). Used by
   `forgelm doctor` and any future probe / telemetry / registry ping
   that needs an outbound read.
-- **`forgelm/_http.safe_post`** (Faz 7 carry-over) — single boundary
+- **`forgelm/_http.safe_post`** — single boundary
   for outbound HTTP with SSRF guard, redirect refusal, scheme policy,
   timeout floor, TLS pinning, secret-mask error reasons. Migrated
   webhook + judge + synthetic call sites.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index a3e5675f..c42d07fe 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -10,7 +10,7 @@
 | ✅ Done | [Phase 10 — Post-Training Completion](roadmap/completed-phases.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — shipped `v0.4.0` |
 | ✅ Done | [Phase 10.5 — Quickstart Layer & Onboarding](roadmap/completed-phases.md) | `forgelm quickstart <template>`, 5 bundled templates with seed datasets — shipped `v0.4.5` |
 | ✅ Done | [Phase 11 + 11.5 + 12 + 12.5 — Document Ingestion & Data Curation Pipeline](roadmap/releases.md#v050-document-ingestion-data-curation-pipeline) | `forgelm ingest`, `forgelm audit`, PII regex + simhash dedup, LSH banding, streaming reader, PII severity tiers, wizard ingest+audit, MinHash LSH dedup, markdown splitter, code/secrets scan, quality heuristics, DOCX table preservation, `--all-mask`, Croissant 1.0, Presidio NER — shipped `v0.5.0` (PyPI 2026-04-30) |
-| ✅ Done | [Phase 12.6 — Closure Cycle (37 content fazlar + 1 release tag = 38 entries across 5 waves)](roadmap/completed-phases.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommands, compliance verification toolbelt, bilingual mirror sweep + 4 CI guards, supply-chain security, cross-OS release matrix — bundled into `v0.5.5` (PyPI 2026-05-10) |
+| ✅ Done | [Phase 12.6 — Closure Cycle (37 content phases + 1 release tag = 38 entries across 5 waves)](roadmap/completed-phases.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommands, compliance verification toolbelt, bilingual mirror sweep + 4 CI guards, supply-chain security, cross-OS release matrix — bundled into `v0.5.5` (PyPI 2026-05-10) |
 | ✅ Done | Phase 22 — CLI wizard parity with the in-browser surface | `forgelm --wizard` runs the same 9-step flow as the web wizard (welcome → use-case → model → strategy → trainer → dataset → training-params → compliance → evaluation), with idempotent re-run via `--wizard-start-from <yaml>`, schema-driven defaults SOT, distinct `EXIT_WIZARD_CANCELLED = 5` exit code, state persistence under `$XDG_CACHE_HOME`, and validate-on-exit — bundled into `v0.5.5` (PyPI 2026-05-10) |
 | ✅ Done | Site documentation correction sweep | All visible YAML / artefact-path / CLI / schema claims on `site/*.html` now validate against the live `forgelm/` surface. Hero YAML demo rewritten with real Pydantic field names, compliance artefact tree redrawn against the on-disk layout, ghost YAML keys + CLI flags removed, wording aligned with live behaviour. Six-language i18n (en / tr / de / fr / es / zh) now at full parity (731 keys each) — bundled into `v0.5.5` (PyPI 2026-05-10) |
 | 📋 Planned | [Phase 14 — Multi-Stage Pipeline Chains](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO chained config, pipeline provenance artifacts → `v0.6.0` |
@@ -33,7 +33,7 @@ Originally planned as four sequential PyPI tags (`v0.5.0` / `v0.5.1` / `v0.5.2`
 
 **Current state:** 19 phases (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12, 12.5, 12.6, 22) shipped on PyPI under `v0.5.5`.  2 phases (13, 14) planned post-release.
 
-> **Phase 12.6 / Faz dual-axis note:** Phase 12.6 is itself a 38-task closure cycle (Faz 1-38) tracked at [`roadmap/completed-phases.md`](roadmap/completed-phases.md); per-wave PR descriptions carry the closure-task delta.
+> **Phase 12.6 task / sub-task dual-axis note:** Phase 12.6 is itself a 38-task closure cycle (Tasks 1-38) tracked at [`roadmap/completed-phases.md`](roadmap/completed-phases.md); per-wave PR descriptions carry the closure-task delta.
 
 ## Quick summary of what's planned
 
diff --git a/docs/roadmap/completed-phases.md b/docs/roadmap/completed-phases.md
index 0228df16..e275e72b 100644
--- a/docs/roadmap/completed-phases.md
+++ b/docs/roadmap/completed-phases.md
@@ -642,8 +642,6 @@ graph TD
 
 ## Phase 10: Post-Training Completion
 
-> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md).
-
 **Goal:** Close the "trained, now what?" gap. After a fine-tune finishes, users should be able to sanity-check, export, and hand the model to a serving runtime (Ollama, vLLM, TGI) without leaving ForgeLM.
 **Estimated Effort:** Medium (2-3 months)
 **Priority:** High — single biggest post-9 UX gap; foundation for Phase 12 (quickstart)
@@ -719,7 +717,7 @@ graph TD
 > **Status:** ✅ **DONE** — shipped as `v0.4.5` on 2026-04-26 (PyPI). Module: [`forgelm/quickstart.py`](../../forgelm/quickstart.py); five bundled templates under [`forgelm/templates/`](../../forgelm/templates/); CLI: `forgelm quickstart <template>`; tests: [`tests/test_quickstart.py`](../../tests/test_quickstart.py); CI smoke in [nightly.yml](../../.github/workflows/nightly.yml).
 
 > **Note:** This file details a single phase. For a summary of all phases, see [../roadmap.md](../roadmap.md).
-> **Filename history:** Originally `phase-12-quickstart.md` (the slot Quickstart held in early planning); renamed to (see relevant Phase section above/below) in the v0.5.2 cycle so the filename matches the current phase number. The Phase 12 slot now belongs to [Data Curation Maturity](#phase-12-data-curation-maturity).
+> **Filename history:** Originally `phase-12-quickstart.md` (the slot Quickstart held in early planning); renamed to its current filename slug in the v0.5.2 cycle so the filename matches the current phase number. The Phase 12 slot now belongs to [Data Curation Maturity](#phase-12-data-curation-maturity).
 
 **Goal:** Make "my first fine-tune" a 10-minute experience. One command, one model in the end, zero YAML writing. Without sacrificing the CI/CD-native core — quickstart generates a YAML the user can later customize.
 **Estimated Effort:** Medium (1-2 months) — **Actual: 1 week**
@@ -783,9 +781,6 @@ graph TD
 > [`docs/guides/data_audit.md`](../guides/data_audit.md). Follow-up
 > work tracked in [Phase 11.5 backlog](#phase-115-ingestion-audit-polish).
 >
-> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların
-> özeti için [../roadmap.md](../roadmap.md).
-
 **Goal:** Turn raw domain documents (PDF, DOCX, EPUB, TXT, plus structured sources) into training-ready JSONL, with automatic data quality reports that plug into EU AI Act Article 10 data governance.
 **Estimated Effort:** Medium (1-2 months) — **Actual: 1 day**
 **Priority:** High — enterprise onboarding accelerator; bridges ingestion → training → compliance audit in one tool.
@@ -929,9 +924,9 @@ suite because it is wall-clock-noisy.
 > and 12.5 — see [releases.md](releases.md#v050-document-ingestion-data-curation-pipeline).
 > Version-label references below preserve the historical planning trail.
 >
-> **Status:** ✅ **Tier 1 DONE** — landed on `development` for the (originally) `v0.5.2` cycle. All five must-have tasks shipped: MinHash LSH dedup option (`[ingestion-scale]` extra via `datasketch`), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`[ingestion-secrets]` extra via `detect-secrets` with regex fallback), heuristic quality filter (`--quality-filter`), DOCX/Markdown table preservation. Tier 2 (Presidio adapter, Croissant metadata) and Tier 3 (`--all-mask` composite, wizard "audit first" hook) are deferred to a follow-up **Phase 12.5** backlog file (analogous to Phase 11.5 → (see relevant Phase section above/below)). Modules: [`forgelm/data_audit.py`](../../forgelm/data_audit/), [`forgelm/ingestion.py`](../../forgelm/ingestion.py), [`forgelm/cli.py`](../../forgelm/cli/); tests: [`tests/test_data_audit_phase12.py`](../../tests/test_data_audit_phase12.py), [`tests/test_ingestion_phase12.py`](../../tests/test_ingestion_phase12.py); CLI tests added in [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py).
+> **Status:** ✅ **Tier 1 DONE** — landed on `development` for the (originally) `v0.5.2` cycle. All five must-have tasks shipped: MinHash LSH dedup option (`[ingestion-scale]` extra via `datasketch`), markdown-aware splitter (`--strategy markdown`), code/secrets leakage tagger (`[ingestion-secrets]` extra via `detect-secrets` with regex fallback), heuristic quality filter (`--quality-filter`), DOCX/Markdown table preservation. Tier 2 (Presidio adapter, Croissant metadata) and Tier 3 (`--all-mask` composite, wizard "audit first" hook) are deferred to a follow-up **Phase 12.5** backlog file (analogous to [Phase 11.5 section above](#phase-115-ingestion-audit-polish)). Modules: [`forgelm/data_audit.py`](../../forgelm/data_audit/), [`forgelm/ingestion.py`](../../forgelm/ingestion.py), [`forgelm/cli.py`](../../forgelm/cli/); tests: [`tests/test_data_audit_phase12.py`](../../tests/test_data_audit_phase12.py), [`tests/test_ingestion_phase12.py`](../../tests/test_ingestion_phase12.py); CLI tests added in [`tests/test_cli_subcommands.py`](../../tests/test_cli_subcommands.py).
 
-> **Not:** Bu dosya tek bir planlanan fazı detaylandırır. Tüm fazların özeti için [../roadmap.md](../roadmap.md). Phase 11 + 11.5 built the ingestion / audit lineage (Phase 11 → `v0.5.0`, Phase 11.5 → `v0.5.1`); this phase moves the same lineage from **enterprise-acceptable** to **enterprise-competitive**.
+> **Note:** Phase 11 + 11.5 built the ingestion / audit lineage (Phase 11 → `v0.5.0`, Phase 11.5 → `v0.5.1`); this phase moves the same lineage from **enterprise-acceptable** to **enterprise-competitive**.
 
 **Goal:** Mature ForgeLM's `forgelm ingest` + `forgelm audit` layer along three axes — **scale** (LSH-based near-duplicate detection beyond ~50K rows, large-corpus throughput), **security** (code/secret leakage scanning + optional ML-based PII), and **quality** (markdown-aware chunking + heuristic quality filters + table structure preservation). The competitive review that followed Phase 11.5 (see `docs/roadmap/phase-11-5-backlog.md` "Measured speedups" section + the 2026-04-27 ingestion-comparison synthesis) lists the exact gaps this phase closes.
 
@@ -1134,22 +1129,22 @@ The "Won't-do" list at the bottom of [(see Phase 12 — Data Curation Maturity s
 
 ---
 
-## Phase 12.6 — Closure Cycle (38 fazlar across 5 waves)
+## Phase 12.6 — Closure Cycle (38 tasks across 5 waves)
 
-> **Status:** ✅ Done — Faz 33 release publish remains as POST-WAVE.
+> **Status:** ✅ Done — Task 33 release publish remains as POST-WAVE.
 > **Bundled into:** [v0.5.5 release](releases.md#v055-closure-cycle-bundle-phase-22-wizard-site-documentation-sweep-2026-05-10).
-> **Source review:** v0.5.0 master code review (175 findings: 8 Critical + 67 Major + 60 Minor + 40 Nit) — distilled into the Faz 1-38 task list below.
+> **Source review:** v0.5.0 master code review (175 findings: 8 Critical + 67 Major + 60 Minor + 40 Nit) — distilled into the Tasks 1-38 task list below.
 > **Target:** ★★★★★ across all 8 quality dimensions before v0.5.5 PyPI publish.
 
 ### Why this exists as a single phase entry
 
-The v0.5.0 master code review surfaced **175 findings** plus **4 user-added scope items** (Library API support, ISO 27001 / SOC 2 alignment, GDPR right-to-erasure full implementation, Article 14 real staging). Rather than stretch these across 5 sequential patch releases, the maintainer chose **Path B — full Faz 1-38 sweep into a single v0.5.5 tag**:
+The v0.5.0 master code review surfaced **175 findings** plus **4 user-added scope items** (Library API support, ISO 27001 / SOC 2 alignment, GDPR right-to-erasure full implementation, Article 14 real staging). Rather than stretch these across 5 sequential patch releases, the maintainer chose **Path B — full Tasks 1-38 sweep into a single v0.5.5 tag**:
 
 - Bisectable PR-per-faz history
 - One coherent surface (every faz feeds the same release candidate)
 - 5/5 quality bar reached before publish, not after
 
-The 38 fazlar were merged across **5 integration waves** (Wave 0/1 through Wave 5). Each wave landed via a dedicated PR onto `development`, then into `main`. This file is the index that maps every faz to its wave, integration PR, and merge SHA.
+The 38 tasks were merged across **5 integration waves** (Wave 0/1 through Wave 5). Each wave landed via a dedicated PR onto `development`, then into `main`. This file is the index that maps every faz to its wave, integration PR, and merge SHA.
 
 ### Scope (in / out)
 
@@ -1178,11 +1173,11 @@ The 38 fazlar were merged across **5 integration waves** (Wave 0/1 through Wave
 | **Wave 3** | `closure/wave3-integration` | PR #31 → `development` | `b87c872` | 2026-05-05 | 1298 → 1374 (+76) |
 | **Wave 4** | `closure/wave4-integration` | PR #33 → `development` | `01e40ba` | 2026-05-06 | 1374 → 1411 (+37) |
 | **Wave 5** | `closure/wave5-integration` | PR #34 → `development` merged `8f9f951` | `8f9f951` | 2026-05-06 | 1411 → ~1442 (+31) |
-| **Faz 33** (POST-WAVE) | release commit | tag `v0.5.5` → `main` | (post-Wave-5) | TBD | n/a |
+| **Task 33** (POST-WAVE) | release commit | tag `v0.5.5` → `main` | (post-Wave-5) | TBD | n/a |
 
-### Faz inventory (38 entries)
+### Task inventory (38 entries)
 
-| # | Faz | Wave | Status |
+| # | Task | Wave | Status |
 |---|---|---|---|
 | 1 | Site & doc honesty + count drift sweep | Wave 0 (PR #19) | ✅ |
 | 2 | CI gates & standards drift cleanup | Wave 0 (PR #19) | ✅ |
@@ -1223,39 +1218,39 @@ The 38 fazlar were merged across **5 integration waves** (Wave 0/1 through Wave
 | 37 | `forgelm approvals` listing subcommand (GH-007) | Wave 2a (PR #28) | ✅ |
 | 38 | `forgelm reverse-pii` GDPR Article 15 subcommand (GH-014) | Wave 3 (PR #31) | ✅ |
 
-**Total:** 38 fazlar / ~52 PRs (multi-PR series counted separately).
+**Total:** 38 tasks / ~52 PRs (multi-PR series counted separately).
 
 ### Wave-by-wave outcomes
 
 #### Wave 0 / 1 (PR #19, PR #21)
 
-Foundation + the bulk of the master-review backlog — fazlar 1-15, 25, 27, 29, 31, 32. Site honesty fixes, CI gates, audit log forensic completeness, performance pass, the two big package splits (`data_audit/` 5-PR series, `cli/` 6-PR series).
+Foundation + the bulk of the master-review backlog — tasks 1-15, 25, 27, 29, 31, 32. Site honesty fixes, CI gates, audit log forensic completeness, performance pass, the two big package splits (`data_audit/` 5-PR series, `cli/` 6-PR series).
 
 #### Wave 2a (PR #28, 2026-05-04)
 
-5 fazlar: 17 (`audit --workers N`), 18 (Library API design), 20 (GDPR design), 34 (`doctor`), 37 (`approvals`).
+5 tasks: 17 (`audit --workers N`), 18 (Library API design), 20 (GDPR design), 34 (`doctor`), 37 (`approvals`).
 
 #### Wave 2b (PR #30, 2026-05-05, merge `b05edb5`)
 
-5 fazlar: 16 (Pydantic `description=` migration), 19 (Library API implementation), 21 (GDPR erasure implementation), 35 (air-gap pre-cache), 36 (compliance verification toolbelt). Suite 1160 → 1298 (+138). 6 absorption rounds + 4-agent final review + 4 followup absorption commits.
+5 tasks: 16 (Pydantic `description=` migration), 19 (Library API implementation), 21 (GDPR erasure implementation), 35 (air-gap pre-cache), 36 (compliance verification toolbelt). Suite 1160 → 1298 (+138). 6 absorption rounds + 4-agent final review + 4 followup absorption commits.
 
 #### Wave 3 (PR #31, 2026-05-05, merge `b87c872`)
 
-3 fazlar: 24 (bilingual TR mirror sweep + `tools/check_bilingual_parity.py`), 28 (curated Tier 1+2 cleanup), 38 (`reverse-pii`). Suite 1298 → 1374 (+76). Behaviour changes: high-risk + unacceptable + safety-disabled now `ConfigError` (F-compliance-110); webhook timeout 5s → 10s default (F-compliance-106).
+3 tasks: 24 (bilingual TR mirror sweep + `tools/check_bilingual_parity.py`), 28 (curated Tier 1+2 cleanup), 38 (`reverse-pii`). Suite 1298 → 1374 (+76). Behaviour changes: high-risk + unacceptable + safety-disabled now `ConfigError` (F-compliance-110); webhook timeout 5s → 10s default (F-compliance-106).
 
 #### Wave 4 (PR #33, 2026-05-06, merge `01e40ba`)
 
-4 fazlar: 22 + 23 (ISO 27001 / SOC 2 alignment design + implementation), 26 (QMS bilingual mirror + `tools/check_anchor_resolution.py` + `compliance_summary.md` rewrite), 30 partial (Tier 1 ghost-feature drift + stat blocks). Suite 1374 → 1411 (+37: 16 supply-chain + 21 anchor checker). Bilingual parity scope 9/9 → 23/23 pairs.
+4 tasks: 22 + 23 (ISO 27001 / SOC 2 alignment design + implementation), 26 (QMS bilingual mirror + `tools/check_anchor_resolution.py` + `compliance_summary.md` rewrite), 30 partial (Tier 1 ghost-feature drift + stat blocks). Suite 1374 → 1411 (+37: 16 supply-chain + 21 anchor checker). Bilingual parity scope 9/9 → 23/23 pairs.
 
 #### Wave 5 (PR #34 merged `8f9f951`, 2026-05-06)
 
-Faz 30 full sweep: residual ghost-feature drift (GH-011 benchmarks, GH-016 `--export-bundle`, GH-018 deploy-targets `kserve`/`triton`, GH-020 ingest flag drift); Task A doc-triplet completion (~12 features × {guide, reference, usermanual} × {EN, TR} ≈ 50 new files — landed in commit `2a32842`); Task J `tools/check_cli_help_consistency.py` (commit `c7bedc9`); Task N anchor-checker `--strict` flip + 36-baseline cleanup (commit `fbb082d`); Tasks B/C `_meta.yaml` + `build_usermanuals.py` rebuild; Task D site/* finalization; Tasks E/F/G README + CONTRIBUTING + CLAUDE + roadmap + standards final pass; Tasks H/I/K/L/M parity strict + site-claim CI + config regen + locale policy + diagrams.
+Task 30 full sweep: residual ghost-feature drift (GH-011 benchmarks, GH-016 `--export-bundle`, GH-018 deploy-targets `kserve`/`triton`, GH-020 ingest flag drift); Task A doc-triplet completion (~12 features × {guide, reference, usermanual} × {EN, TR} ≈ 50 new files — landed in commit `2a32842`); Task J `tools/check_cli_help_consistency.py` (commit `c7bedc9`); Task N anchor-checker `--strict` flip + 36-baseline cleanup (commit `fbb082d`); Tasks B/C `_meta.yaml` + `build_usermanuals.py` rebuild; Task D site/* finalization; Tasks E/F/G README + CONTRIBUTING + CLAUDE + roadmap + standards final pass; Tasks H/I/K/L/M parity strict + site-claim CI + config regen + locale policy + diagrams.
 
-#### Faz 33 (POST-WAVE)
+#### Task 33 (POST-WAVE)
 
 The actual v0.5.5 PyPI publish:
 
-1. `pyproject.toml` `version = "0.5.5"` — already bumped during Wave 5 Task D (`4610dc6`) so `check_site_claims.py --strict` can pin the site → code version parity. Faz 33 only confirms it remains `0.5.5` and adds the date to the `[0.5.5]` CHANGELOG section.
+1. `pyproject.toml` `version = "0.5.5"` — already bumped during Wave 5 Task D (`4610dc6`) so `check_site_claims.py --strict` can pin the site → code version parity. Task 33 only confirms it remains `0.5.5` and adds the date to the `[0.5.5]` CHANGELOG section.
 2. CHANGELOG `[Unreleased]` → `[0.5.5] — YYYY-MM-DD`
 3. `git tag -s v0.5.5 -m "v0.5.5 — Closure Cycle Bundle"`
 4. `git push origin main v0.5.5`

From 5fbbbd4f4adaaa5ffbdb9d5bf09706e8b782d8c8 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Sun, 10 May 2026 23:34:50 +0300
Subject: [PATCH 3/7] =?UTF-8?q?fix(release):=20v0.5.7=20=E2=80=94=20SFT=20?=
 =?UTF-8?q?trainer=20trl-modernisation=20TypeError?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes a runtime TypeError that prevented every SFT training run from
starting on modern trl (0.13+ and the 1.x line). The max_seq_length
parameter was renamed to max_length on SFTConfig in trl 0.13 and the
old name removed; v0.5.6 still passed max_seq_length unconditionally,
so forgelm --config <yaml> crashed with:

  TypeError: SFTConfig.__init__() got an unexpected keyword argument
  'max_seq_length'

on any environment that pulled a current trl wheel — notably the
Colab default `pip install forgelm` path.

Fix: forgelm/trainer.py::_get_training_args_for_type's SFT branch now
inspects SFTConfig.__init__'s signature at runtime and picks the
correct parameter name. trl 0.13+ receives max_length; trl 0.12.x
(still within pyproject's `trl>=0.12.0,<2.0.0` floor) keeps receiving
max_seq_length. No code change for DPO / SimPO / KTO / ORPO / GRPO
trainers — those *Config parameters were not affected by the rename.

Three new regression tests in tests/test_trainer_sft_config.py pin
the modern-trl path, the legacy-trl path, and that packing /
dataset_text_field continue to be propagated.

Other release-prep updates:
- pyproject.toml: 0.5.6 → 0.5.7
- forgelm/_version.py: rationale comment updated
- CHANGELOG.md: [0.5.7] entry inserted above [0.5.6]
- docs/roadmap/releases.md: v0.5.7 entry inserted above v0.5.6
- notebooks/*.ipynb: install pins bumped 0.5.6 → 0.5.7 (10 files)

Verified: ruff format/check clean, all 3 doc CI guards green
(anchor 266 files, parity 45 pairs, no-analysis-refs).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                               |  27 +++++
 docs/roadmap/releases.md                   |  20 ++++
 forgelm/_version.py                        |  10 +-
 forgelm/trainer.py                         |  12 +-
 notebooks/data_curation.ipynb              |   4 +-
 notebooks/dpo_alignment.ipynb              |   2 +-
 notebooks/galore_memory_optimization.ipynb |   2 +-
 notebooks/grpo_reasoning.ipynb             |   2 +-
 notebooks/kto_binary_feedback.ipynb        |   2 +-
 notebooks/multi_dataset.ipynb              |   2 +-
 notebooks/post_training_workflow.ipynb     |   4 +-
 notebooks/quickstart_sft.ipynb             |   2 +-
 notebooks/safety_evaluation.ipynb          |   2 +-
 notebooks/synthetic_data_training.ipynb    |   2 +-
 pyproject.toml                             |   2 +-
 tests/test_trainer_sft_config.py           | 133 +++++++++++++++++++++
 16 files changed, 208 insertions(+), 20 deletions(-)
 create mode 100644 tests/test_trainer_sft_config.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a45394f8..78720f94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,33 @@ All notable changes to ForgeLM are documented here.
 
 ## [Unreleased]
 
+## [0.5.7] — 2026-05-10
+
+Patch release. Fixes a runtime `TypeError` in the SFT trainer that
+prevented every SFT training run from starting on modern `trl`
+versions (0.13 and the 1.x line). The `max_seq_length` parameter was
+renamed to `max_length` on `SFTConfig` in trl 0.13 and the old name
+removed; the v0.5.6 release was still passing `max_seq_length`
+unconditionally, so `forgelm --config <yaml>` would crash with
+`TypeError: SFTConfig.__init__() got an unexpected keyword argument
+'max_seq_length'` on any environment that pulled a current trl wheel
+(notably the Colab default `pip install forgelm` path).
+
+### Fixed
+
+- **`forgelm/trainer.py::_get_training_args_for_type`** — the SFT
+  branch now inspects `SFTConfig.__init__`'s signature at runtime and
+  picks the correct sequence-length-cap parameter name. trl 0.13+
+  (including the 1.x line) receives `max_length`; trl 0.12.x — still
+  within the `pyproject.toml` floor `trl>=0.12.0,<2.0.0` — keeps
+  receiving `max_seq_length`. No code change for DPO / SimPO / KTO /
+  ORPO / GRPO trainers (their `*Config` parameters were not affected
+  by the rename).
+- **`tests/test_trainer_sft_config.py`** (new) — three regression
+  tests pin the modern-trl path (`max_length`), the legacy-trl path
+  (`max_seq_length`), and that `packing` / `dataset_text_field`
+  continue to be propagated.
+
 ## [0.5.6] — 2026-05-10
 
 **Status:** Released to PyPI 2026-05-10 via the cross-OS publish
diff --git a/docs/roadmap/releases.md b/docs/roadmap/releases.md
index 1ff7e0b9..3077826a 100644
--- a/docs/roadmap/releases.md
+++ b/docs/roadmap/releases.md
@@ -128,6 +128,26 @@ Odak: [Phase 10](completed-phases.md). Full post-training handoff: inference, ch
 
 ---
 
+## v0.5.7 — "SFT trainer trl-modernisation fix" (2026-05-10)
+
+**Status:** Released to PyPI 2026-05-10. Patch on top of v0.5.6. GitHub Release: [v0.5.7](https://github.com/cemililik/ForgeLM/releases/tag/v0.5.7).
+
+### Summary
+
+Fixes a `TypeError` in the SFT trainer that prevented every SFT training run from starting on modern `trl` (0.13+ and the 1.x line). The `max_seq_length` parameter was renamed to `max_length` on `SFTConfig` upstream; v0.5.6 still passed the old name unconditionally, so `forgelm --config <yaml>` crashed at trainer-args build time on any environment that pulled a current trl wheel — notably the Colab default `pip install forgelm` path.
+
+### Highlights
+
+- **Runtime signature detection** — `_get_training_args_for_type` now inspects `SFTConfig.__init__` and picks `max_length` (trl 0.13+) or `max_seq_length` (trl 0.12.x) at runtime, so both ends of the supported range (`trl>=0.12.0,<2.0.0`) work without intervention.
+- **Three new regression tests** in `tests/test_trainer_sft_config.py` pin the modern-trl path, the legacy-trl path, and that `packing` / `dataset_text_field` continue to be propagated.
+- **No effect on DPO / SimPO / KTO / ORPO / GRPO trainers** — those `*Config` parameter sets were not affected by the trl 0.13 rename.
+
+### Full changelog
+
+See [CHANGELOG.md `[0.5.7]`](../../CHANGELOG.md#057--2026-05-10).
+
+---
+
 ## v0.5.6 — "Intel Mac install fix" (2026-05-10)
 
 **Status:** Released to PyPI 2026-05-10. Patch on top of v0.5.5. GitHub Release: [v0.5.6](https://github.com/cemililik/ForgeLM/releases/tag/v0.5.6).
diff --git a/forgelm/_version.py b/forgelm/_version.py
index 9c38ad0a..d442df63 100644
--- a/forgelm/_version.py
+++ b/forgelm/_version.py
@@ -35,12 +35,10 @@
 #
 # Anchored at 1.0.0 with the v0.5.5 release (first PyPI publish of
 # the formal Phase 19 library-API surface — 30 stable symbols in
-# ``forgelm.__all__``).  v0.5.6 reverts the v0.5.5 torch min bump
-# (`torch>=2.3` was inaccurate — no v2.3-specific API is referenced
-# in production code; the Intel Mac PyPI wheel cap at torch 2.2.2
-# was making `pip install forgelm` silently downgrade existing
-# users to v0.5.0).  No Python API surface change in v0.5.6, so
-# ``__api_version__`` stays at 1.0.0.
+# ``forgelm.__all__``).  v0.5.6 reverted the v0.5.5 torch min bump;
+# v0.5.7 fixes a runtime ``SFTConfig.max_seq_length`` TypeError on
+# modern trl (rename to ``max_length`` in trl 0.13+).  Neither patch
+# changes the Python API surface, so ``__api_version__`` stays at 1.0.0.
 __api_version__ = "1.0.0"
 
 __all__ = ["__version__", "__api_version__"]
diff --git a/forgelm/trainer.py b/forgelm/trainer.py
index d6a64bca..b1677001 100644
--- a/forgelm/trainer.py
+++ b/forgelm/trainer.py
@@ -425,11 +425,21 @@ def _get_training_args_for_type(self):
         kwargs = self._get_common_training_kwargs()
 
         if tt == "sft":
+            import inspect
+
             from trl import SFTConfig
 
             kwargs["packing"] = bool(getattr(self.config.training, "packing", False))
             kwargs["dataset_text_field"] = "text"
-            kwargs["max_seq_length"] = self.config.model.max_length
+            # Sequence-length cap parameter was renamed in trl 0.13:
+            #   trl 0.12.x: ``SFTConfig(max_seq_length=...)``
+            #   trl 0.13+ / 1.x: ``SFTConfig(max_length=...)`` — old name removed
+            # ``pyproject.toml`` pins ``trl>=0.12.0,<2.0.0``, so detect at runtime.
+            sft_params = inspect.signature(SFTConfig).parameters
+            if "max_length" in sft_params:
+                kwargs["max_length"] = self.config.model.max_length
+            elif "max_seq_length" in sft_params:
+                kwargs["max_seq_length"] = self.config.model.max_length
             return SFTConfig(**kwargs)
 
         elif tt == "orpo":
diff --git a/notebooks/data_curation.ipynb b/notebooks/data_curation.ipynb
index ca75f66b..300610d7 100644
--- a/notebooks/data_curation.ipynb
+++ b/notebooks/data_curation.ipynb
@@ -21,7 +21,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM with the ingestion extra (PDF/DOCX/EPUB/Markdown parsers + langdetect)\n# Pinned to v0.5.6 (the v0.5.5 closure-cycle bundle ships Phases 11+11.5+12+12.5\n# (markdown splitter, secrets tagger, MinHash dedup option, quality filter,\n# Croissant card, optional Presidio adapter, --all-mask shorthand).\n!pip install -q --no-cache-dir 'forgelm[ingestion]==0.5.6'\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM with the ingestion extra (PDF/DOCX/EPUB/Markdown parsers + langdetect)\n# Pinned to v0.5.7 (the v0.5.5 closure-cycle bundle ships Phases 11+11.5+12+12.5\n# (markdown splitter, secrets tagger, MinHash dedup option, quality filter,\n# Croissant card, optional Presidio adapter, --all-mask shorthand).\n!pip install -q --no-cache-dir 'forgelm[ingestion]==0.5.7'\n!forgelm --version"
   },
   {
    "cell_type": "markdown",
@@ -331,7 +331,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Install the optional [ingestion-scale] extra so the install hint baked\n# into ``forgelm.data_audit._require_datasketch`` matches the recipe used\n# here. This pulls ``datasketch>=1.6.0,<2.0.0`` along with any future\n# scale-tier deps the extra absorbs.\n!pip install -q 'forgelm[ingestion-scale]==0.5.6'\n!forgelm audit ./curated/policies.jsonl \\\n    --output ./audit_minhash/ \\\n    --dedup-method minhash \\\n    --jaccard-threshold 0.85"
+   "source": "# Install the optional [ingestion-scale] extra so the install hint baked\n# into ``forgelm.data_audit._require_datasketch`` matches the recipe used\n# here. This pulls ``datasketch>=1.6.0,<2.0.0`` along with any future\n# scale-tier deps the extra absorbs.\n!pip install -q 'forgelm[ingestion-scale]==0.5.7'\n!forgelm audit ./curated/policies.jsonl \\\n    --output ./audit_minhash/ \\\n    --dedup-method minhash \\\n    --jaccard-threshold 0.85"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/dpo_alignment.ipynb b/notebooks/dpo_alignment.ipynb
index 39f1f860..45bff883 100644
--- a/notebooks/dpo_alignment.ipynb
+++ b/notebooks/dpo_alignment.ipynb
@@ -18,7 +18,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/galore_memory_optimization.ipynb b/notebooks/galore_memory_optimization.ipynb
index 8cc4e533..15456b86 100644
--- a/notebooks/galore_memory_optimization.ipynb
+++ b/notebooks/galore_memory_optimization.ipynb
@@ -23,7 +23,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM + GaLore\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6' bitsandbytes\n!pip install -q galore-torch  # GaLore optimizer\n!pip uninstall -y wandb -q\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM + GaLore\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7' bitsandbytes\n!pip install -q galore-torch  # GaLore optimizer\n!pip uninstall -y wandb -q\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/grpo_reasoning.ipynb b/notebooks/grpo_reasoning.ipynb
index 9c375ecf..9c834649 100644
--- a/notebooks/grpo_reasoning.ipynb
+++ b/notebooks/grpo_reasoning.ipynb
@@ -18,7 +18,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/kto_binary_feedback.ipynb b/notebooks/kto_binary_feedback.ipynb
index a1a1ea0c..c5970d5a 100644
--- a/notebooks/kto_binary_feedback.ipynb
+++ b/notebooks/kto_binary_feedback.ipynb
@@ -18,7 +18,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/multi_dataset.ipynb b/notebooks/multi_dataset.ipynb
index 5f3aefeb..1d7d4b5a 100644
--- a/notebooks/multi_dataset.ipynb
+++ b/notebooks/multi_dataset.ipynb
@@ -18,7 +18,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/post_training_workflow.ipynb b/notebooks/post_training_workflow.ipynb
index 28ae1865..d7a6e14d 100644
--- a/notebooks/post_training_workflow.ipynb
+++ b/notebooks/post_training_workflow.ipynb
@@ -36,7 +36,7 @@
    "outputs": [],
    "source": [
     "# Install ForgeLM (skip on Colab if quickstart_sft already ran in this session)\n",
-    "!pip install -q --no-cache-dir 'forgelm==0.5.6' bitsandbytes\n",
+    "!pip install -q --no-cache-dir 'forgelm==0.5.7' bitsandbytes\n",
     "!forgelm --version"
    ]
   },
@@ -199,7 +199,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!pip install -q 'forgelm[export]==0.5.6'  # adds llama-cpp-python>=0.2.90"
+    "!pip install -q 'forgelm[export]==0.5.7'  # adds llama-cpp-python>=0.2.90"
    ]
   },
   {
diff --git a/notebooks/quickstart_sft.ipynb b/notebooks/quickstart_sft.ipynb
index fc29c93b..380651b7 100644
--- a/notebooks/quickstart_sft.ipynb
+++ b/notebooks/quickstart_sft.ipynb
@@ -24,7 +24,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM (the [qlora] extra pulls in bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6'\n!pip uninstall -y wandb -q  # Remove conflicting wandb (not needed)\n\n# Verify installation\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM (the [qlora] extra pulls in bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7'\n!pip uninstall -y wandb -q  # Remove conflicting wandb (not needed)\n\n# Verify installation\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/safety_evaluation.ipynb b/notebooks/safety_evaluation.ipynb
index 3f6ac058..47c8f1e7 100644
--- a/notebooks/safety_evaluation.ipynb
+++ b/notebooks/safety_evaluation.ipynb
@@ -20,7 +20,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/notebooks/synthetic_data_training.ipynb b/notebooks/synthetic_data_training.ipynb
index 5c7462a5..d11f56c0 100644
--- a/notebooks/synthetic_data_training.ipynb
+++ b/notebooks/synthetic_data_training.ipynb
@@ -23,7 +23,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.6; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.6' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
+   "source": "# Step 1: Install ForgeLM (with bitsandbytes for 4-bit quantization)\n# Pinned to v0.5.7; bump on each release\n!pip install -q --no-cache-dir 'forgelm[qlora]==0.5.7' bitsandbytes\n!pip uninstall -y wandb -q\n!forgelm --version"
   },
   {
    "cell_type": "code",
diff --git a/pyproject.toml b/pyproject.toml
index eb0a6980..83d14d32 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "forgelm"
-version = "0.5.6"
+version = "0.5.7"
 description = "Config-driven LLM fine-tuning with safety evaluation, EU AI Act compliance, 6 alignment methods, and one-command bundled quickstart templates."
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/tests/test_trainer_sft_config.py b/tests/test_trainer_sft_config.py
new file mode 100644
index 00000000..67da51df
--- /dev/null
+++ b/tests/test_trainer_sft_config.py
@@ -0,0 +1,133 @@
+"""Tests for SFT ``SFTConfig`` kwarg construction across trl versions.
+
+Regression guard: trl 0.13 renamed the sequence-length cap from
+``max_seq_length`` to ``max_length`` on ``SFTConfig`` and removed the old
+name. Passing the old kwarg raises ``TypeError`` at trainer args build
+time and aborts training on every modern trl install.
+
+``pyproject.toml`` pins ``trl>=0.12.0,<2.0.0``, so the trainer must
+detect at runtime which parameter the installed ``SFTConfig`` accepts.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+torch_available = True
+try:
+    import torch  # noqa: F401
+except ImportError:
+    torch_available = False
+
+
+def _make_sft_config(tmp_path):
+    from forgelm.config import ForgeConfig
+
+    return ForgeConfig(
+        **{
+            "model": {"name_or_path": "org/model", "max_length": 2048},
+            "lora": {},
+            "training": {
+                "trainer_type": "sft",
+                "output_dir": str(tmp_path),
+            },
+            "data": {"dataset_name_or_path": "org/dataset"},
+        }
+    )
+
+
+def _seed_trainer(tmp_path):
+    """Build a bare trainer skeleton without invoking heavy init."""
+    from forgelm.trainer import ForgeTrainer
+
+    config = _make_sft_config(tmp_path)
+    trainer = ForgeTrainer.__new__(ForgeTrainer)
+    trainer.model = MagicMock()
+    trainer.tokenizer = MagicMock()
+    trainer.config = config
+    trainer.dataset = {"train": list(range(10))}
+    trainer.checkpoint_dir = str(tmp_path)
+    trainer.run_name = "sft_kwarg_test"
+    trainer.notifier = MagicMock()
+    trainer.audit = MagicMock()
+    return trainer
+
+
+@pytest.mark.skipif(not torch_available, reason="torch not installed")
+def test_sft_config_uses_max_length_on_modern_trl(tmp_path):
+    """trl 0.13+ removed ``max_seq_length``; the trainer must use
+    ``max_length`` instead."""
+
+    captured_kwargs: dict = {}
+
+    class FakeModernSFTConfig:
+        def __init__(self, *, max_length=None, packing=False, dataset_text_field=None, **other):
+            captured_kwargs["max_length"] = max_length
+            captured_kwargs["packing"] = packing
+            captured_kwargs["dataset_text_field"] = dataset_text_field
+            captured_kwargs.update(other)
+
+    trainer = _seed_trainer(tmp_path)
+
+    with patch("trl.SFTConfig", FakeModernSFTConfig):
+        trainer._get_training_args_for_type()
+
+    assert captured_kwargs["max_length"] == 2048, (
+        "Modern trl `SFTConfig(max_length=...)` must receive the model's "
+        f"max_length (got: {captured_kwargs.get('max_length')!r})"
+    )
+    assert "max_seq_length" not in captured_kwargs, (
+        "Legacy `max_seq_length` kwarg must NOT be passed to a modern SFTConfig — trl 0.13+ raises TypeError on it."
+    )
+    assert captured_kwargs["dataset_text_field"] == "text"
+
+
+@pytest.mark.skipif(not torch_available, reason="torch not installed")
+def test_sft_config_uses_max_seq_length_on_legacy_trl(tmp_path):
+    """trl 0.12.x: ``SFTConfig`` accepts ``max_seq_length`` only. The
+    trainer must fall back to that name when the modern ``max_length``
+    parameter is unavailable."""
+
+    captured_kwargs: dict = {}
+
+    class FakeLegacySFTConfig:
+        def __init__(self, *, max_seq_length=None, packing=False, dataset_text_field=None, **other):
+            captured_kwargs["max_seq_length"] = max_seq_length
+            captured_kwargs["packing"] = packing
+            captured_kwargs["dataset_text_field"] = dataset_text_field
+            captured_kwargs.update(other)
+
+    trainer = _seed_trainer(tmp_path)
+
+    with patch("trl.SFTConfig", FakeLegacySFTConfig):
+        trainer._get_training_args_for_type()
+
+    assert captured_kwargs["max_seq_length"] == 2048
+    assert "max_length" not in captured_kwargs, (
+        "Modern `max_length` kwarg must NOT be passed to legacy trl 0.12.x SFTConfig."
+    )
+
+
+@pytest.mark.skipif(not torch_available, reason="torch not installed")
+def test_sft_config_passes_packing_and_dataset_text_field(tmp_path):
+    """Regression: ``packing`` and ``dataset_text_field`` must keep being
+    propagated alongside the sequence-length cap."""
+
+    captured_kwargs: dict = {}
+
+    class FakeSFTConfig:
+        def __init__(self, *, max_length=None, packing=False, dataset_text_field=None, **other):
+            captured_kwargs["max_length"] = max_length
+            captured_kwargs["packing"] = packing
+            captured_kwargs["dataset_text_field"] = dataset_text_field
+
+    trainer = _seed_trainer(tmp_path)
+    trainer.config.training.packing = True
+
+    with patch("trl.SFTConfig", FakeSFTConfig):
+        trainer._get_training_args_for_type()
+
+    assert captured_kwargs["packing"] is True
+    assert captured_kwargs["dataset_text_field"] == "text"

From bb655701dba8a88f9068fcf45d45ee00d30e1cb9 Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Mon, 11 May 2026 01:26:33 +0300
Subject: [PATCH 4/7] =?UTF-8?q?fix(release):=20v0.5.7=20=E2=80=94=20Intel?=
 =?UTF-8?q?=20Mac=20NumPy=202=20ABI=20mismatch=20+=20numpy.torch=5Fabi=20d?=
 =?UTF-8?q?octor=20probe?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The v0.5.6 torch revert (>=2.3 → >=2.2) restored Intel Mac (x86_64)
installability but exposed a transitive ABI mismatch: torch 2.2 was
compiled against NumPy 1.x, so any host that pip-resolves numpy>=2
silently degrades torch's numpy bridge with `_ARRAY_API not found`.
Intel Mac is the canonical victim — PyTorch Foundation no longer
publishes torch >= 2.3 wheels for x86_64 Darwin, so pip caps at
2.2.x and any modern numpy on the box mismatches.

- pyproject.toml: add `numpy<2; sys_platform == 'darwin' and
  platform_machine == 'x86_64'` so pip caps numpy at 1.x on the
  only platform that is wheel-locked to torch 2.2. Other platforms
  keep numpy unconstrained — torch 2.3+ on Linux / Apple Silicon /
  Windows is binary-compatible with NumPy 2.x.
- forgelm/cli/subcommands/_doctor.py: new `numpy.torch_abi` probe
  detects the (torch < 2.3) × (numpy >= 2) combination and emits a
  structured `fail` with a `pip install 'numpy<2'` remediation hint
  instead of leaving operators chasing torch's stderr UserWarning.
  Probe imports torch / numpy with warnings suppressed and tolerates
  prerelease + local-version suffixes via a regex MAJOR.MINOR parse.
- tests/test_doctor.py: 6 new TestNumpyTorchAbiCheck cases — fail
  path, two pass paths, no-numpy / no-torch graceful skips, and a
  prerelease/local-version regression case.
- CHANGELOG.md: v0.5.7 entry extended with the new Added (probe) +
  Fixed (pyproject pin) bullets; v0.5.7 release notes preface
  expanded to call out both the SFT trl fix and the NumPy ABI fix.
- docs/usermanuals/{en,tr}/reference/json-output.md: probe-name
  example list updated to include `numpy.torch_abi`; H2/H3/H4 spine
  unchanged so bilingual parity guard stays clean.

Verified live on Intel Mac: `python3 -m forgelm.cli doctor` now
reports `[x fail] numpy.torch_abi  torch 2.2.2 (compiled against
NumPy 1.x) is paired with numpy 2.4.4. ...` — exit code 1, ready
to gate CI consumers via --output-format json.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                 |  29 +++++
 docs/usermanuals/en/reference/json-output.md |   2 +-
 docs/usermanuals/tr/reference/json-output.md |   2 +-
 forgelm/cli/subcommands/_doctor.py           |  88 +++++++++++++++
 pyproject.toml                               |   8 ++
 tests/test_doctor.py                         | 111 +++++++++++++++++++
 6 files changed, 238 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78720f94..add0cfc3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,28 @@ unconditionally, so `forgelm --config <yaml>` would crash with
 'max_seq_length'` on any environment that pulled a current trl wheel
 (notably the Colab default `pip install forgelm` path).
 
+Also closes the NumPy 2.x ↔ torch 2.2 binary-ABI mismatch that the
+v0.5.6 Intel Mac torch revert exposed. With `torch>=2.2.0` as the
+floor and no upper-pin on numpy, pip resolved `numpy>=2` on Intel Mac
+hosts; torch 2.2 was compiled against NumPy 1.x and silently
+degraded its numpy bridge with `_ARRAY_API not found`. v0.5.7 adds a
+platform-scoped marker pin (`numpy<2; sys_platform == 'darwin' and
+platform_machine == 'x86_64'`) plus a new doctor probe that surfaces
+the mismatch as a structured `fail` instead of a stderr-only
+UserWarning.
+
+### Added
+
+- **`forgelm doctor` — `numpy.torch_abi` probe.** New diagnostic
+  inspects torch + numpy major-version pairing and emits a `fail`
+  with a `pip install 'numpy<2'` remediation hint when a torch < 2.3
+  install is paired with NumPy ≥ 2 (the canonical Intel Mac install
+  failure mode). Probe imports torch / numpy with warnings suppressed
+  so the probe itself does not pollute stderr with the very
+  `_ARRAY_API not found` warning it is trying to detect. Surfaces in
+  the `forgelm doctor --output-format json` envelope so CI consumers
+  catch the issue programmatically.
+
 ### Fixed
 
 - **`forgelm/trainer.py::_get_training_args_for_type`** — the SFT
@@ -30,6 +52,13 @@ unconditionally, so `forgelm --config <yaml>` would crash with
   tests pin the modern-trl path (`max_length`), the legacy-trl path
   (`max_seq_length`), and that `packing` / `dataset_text_field`
   continue to be propagated.
+- **`pyproject.toml` — Intel Mac (x86_64) NumPy 2 ABI mismatch.**
+  Added `numpy<2; sys_platform == 'darwin' and platform_machine ==
+  'x86_64'` so pip's resolver caps numpy at the 1.x line on the only
+  platform that is wheel-locked to torch 2.2.x. Other platforms keep
+  numpy unconstrained — torch 2.3+ on Linux / Apple Silicon / Windows
+  is binary-compatible with NumPy 2.x. Affected `pip install forgelm`
+  users on Intel Mac since the v0.5.6 torch revert.
 
 ## [0.5.6] — 2026-05-10
 
diff --git a/docs/usermanuals/en/reference/json-output.md b/docs/usermanuals/en/reference/json-output.md
index 1e68d6a8..351afb83 100644
--- a/docs/usermanuals/en/reference/json-output.md
+++ b/docs/usermanuals/en/reference/json-output.md
@@ -40,7 +40,7 @@ Environment check. See [Doctor command](#/getting-started/first-run).
 | Key | Type | Notes |
 |---|---|---|
 | `success` | bool | `true` when no probe `fail` AND no probe crash; `false` otherwise. |
-| `checks` | list[object] | One entry per probe in execution order. Probe names are stable (e.g. `python.version`, `torch.cuda`, `gpu.inventory`, `extras.qlora`, `hf_hub.reachable`, `hf_hub.offline_cache`, `disk.workspace`, `operator.identity`). |
+| `checks` | list[object] | One entry per probe in execution order. Probe names are stable (e.g. `python.version`, `torch.cuda`, `numpy.torch_abi`, `gpu.inventory`, `extras.qlora`, `hf_hub.reachable`, `hf_hub.offline_cache`, `disk.workspace`, `operator.identity`). |
 | `checks[].name` | str | Probe name. Stable across versions; new probes append rather than rename. |
 | `checks[].status` | str | One of `pass`, `warn`, `fail`, `crashed`. |
 | `checks[].detail` | str | Operator-facing one-line description of the result. |
diff --git a/docs/usermanuals/tr/reference/json-output.md b/docs/usermanuals/tr/reference/json-output.md
index c60d361f..face543a 100644
--- a/docs/usermanuals/tr/reference/json-output.md
+++ b/docs/usermanuals/tr/reference/json-output.md
@@ -40,7 +40,7 @@ Ortam kontrolü. Bkz. [Doctor komutu](#/getting-started/first-run).
 | Anahtar | Tip | Notlar |
 |---|---|---|
 | `success` | bool | Hiçbir probe `fail` değilse VE hiçbir probe crash etmediyse `true`; aksi halde `false`. |
-| `checks` | list[object] | Çalıştırma sırasıyla probe başına bir entry. Probe adları stabildir (örn. `python.version`, `torch.cuda`, `gpu.inventory`, `extras.qlora`, `hf_hub.reachable`, `hf_hub.offline_cache`, `disk.workspace`, `operator.identity`). |
+| `checks` | list[object] | Çalıştırma sırasıyla probe başına bir entry. Probe adları stabildir (örn. `python.version`, `torch.cuda`, `numpy.torch_abi`, `gpu.inventory`, `extras.qlora`, `hf_hub.reachable`, `hf_hub.offline_cache`, `disk.workspace`, `operator.identity`). |
 | `checks[].name` | str | Probe adı. Sürümler arası stabil; yeni probe'lar yeniden adlandırma yerine eklenir. |
 | `checks[].status` | str | `pass`, `warn`, `fail`, `crashed`'tan biri. |
 | `checks[].detail` | str | Sonuç için operatör-yüzlü tek satırlık açıklama. |
diff --git a/forgelm/cli/subcommands/_doctor.py b/forgelm/cli/subcommands/_doctor.py
index 2f3a8d14..f082f39e 100644
--- a/forgelm/cli/subcommands/_doctor.py
+++ b/forgelm/cli/subcommands/_doctor.py
@@ -63,6 +63,7 @@
 _PROBE_PYTHON_VERSION = "python.version"
 _PROBE_TORCH_INSTALLED = "torch.installed"
 _PROBE_TORCH_CUDA = "torch.cuda"
+_PROBE_NUMPY_TORCH_ABI = "numpy.torch_abi"
 _PROBE_GPU_INVENTORY = "gpu.inventory"
 _PROBE_HF_HUB_REACHABLE = "hf_hub.reachable"
 _PROBE_HF_HUB_OFFLINE_CACHE = "hf_hub.offline_cache"
@@ -209,6 +210,91 @@ def _check_torch_cuda() -> _CheckResult:
     )
 
 
+def _check_numpy_torch_abi() -> _CheckResult:
+    """Detect a torch <-> numpy binary-ABI mismatch.
+
+    PyTorch wheels are compiled against a specific NumPy major version:
+    torch < 2.3 was built against NumPy 1.x and silently degrades when
+    paired with NumPy 2.x (the well-known ``_ARRAY_API not found``
+    UserWarning emitted from torch's C++ tensor-numpy bridge).  This
+    typically bites Intel Mac (x86_64) hosts where PyTorch Foundation
+    no longer publishes torch >= 2.3 wheels, so pip's resolver caps at
+    torch 2.2.x and any newer numpy on the box mismatches.
+
+    Best-effort probe: torch / numpy are imported with warnings
+    suppressed so the probe itself does not pollute stderr with the
+    very ``UserWarning`` it is trying to detect.
+    """
+    import re
+    import warnings
+
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            import torch
+    except ImportError:
+        # The dedicated torch.cuda probe already surfaces a missing
+        # torch as fail; do not double-report here.
+        return _CheckResult(
+            name=_PROBE_NUMPY_TORCH_ABI,
+            status=_STATUS_PASS,
+            detail="torch is not installed; ABI compatibility check skipped.",
+            extras={"skipped": True, "reason": "torch_missing"},
+        )
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            import numpy
+    except ImportError:
+        # numpy is an *optional* fast-path for the simhash backend
+        # (see forgelm/data_audit/_optional.py::_HAS_NUMPY) — its
+        # absence is not a doctor failure.
+        return _CheckResult(
+            name=_PROBE_NUMPY_TORCH_ABI,
+            status=_STATUS_PASS,
+            detail="numpy is not installed; ABI compatibility check skipped.",
+            extras={"skipped": True, "reason": "numpy_missing"},
+        )
+
+    def _major_minor(version: str) -> Tuple[int, int]:
+        # Tolerates prerelease ("2.2.0a0") and local-version ("2.2.0+cpu")
+        # suffixes by extracting the leading numeric MAJOR.MINOR pair only.
+        match = re.match(r"^(\d+)\.(\d+)", version)
+        if not match:
+            return (0, 0)
+        return (int(match.group(1)), int(match.group(2)))
+
+    torch_mm = _major_minor(torch.__version__)
+    numpy_mm = _major_minor(numpy.__version__)
+    extras: Dict[str, Any] = {
+        "torch_version": torch.__version__,
+        "numpy_version": numpy.__version__,
+    }
+
+    # The known incompatibility window: torch < 2.3 was built against
+    # NumPy 1.x and silently degrades when paired with NumPy 2.x.
+    if torch_mm < (2, 3) and numpy_mm >= (2, 0):
+        return _CheckResult(
+            name=_PROBE_NUMPY_TORCH_ABI,
+            status=_STATUS_FAIL,
+            detail=(
+                f"torch {torch.__version__} (compiled against NumPy 1.x) is "
+                f"paired with numpy {numpy.__version__}. This triggers an "
+                "`_ARRAY_API not found` ABI mismatch and silently degrades "
+                "the numpy bridge inside torch. Fix with: pip install 'numpy<2' "
+                "(or upgrade to torch>=2.3 if your platform has wheels for it)."
+            ),
+            extras=extras,
+        )
+
+    return _CheckResult(
+        name=_PROBE_NUMPY_TORCH_ABI,
+        status=_STATUS_PASS,
+        detail=f"torch {torch.__version__} + numpy {numpy.__version__} are ABI-compatible.",
+        extras=extras,
+    )
+
+
 def _check_gpu_inventory() -> _CheckResult:
     """Enumerate visible GPUs + per-device VRAM.
 
@@ -786,6 +872,7 @@ def _build_check_plan(*, offline: bool) -> List[Tuple[str, Callable[[], _CheckRe
     plan: List[Tuple[str, Callable[[], _CheckResult]]] = [
         (_PROBE_PYTHON_VERSION, _check_python_version),
         (_PROBE_TORCH_CUDA, _check_torch_cuda),
+        (_PROBE_NUMPY_TORCH_ABI, _check_numpy_torch_abi),
         (_PROBE_GPU_INVENTORY, _check_gpu_inventory),
     ]
     for extra_name, module, purpose in _OPTIONAL_EXTRAS:
@@ -988,6 +1075,7 @@ def _run_doctor_cmd(args, output_format: str) -> None:
     "_CheckResult",
     "_check_python_version",
     "_check_torch_cuda",
+    "_check_numpy_torch_abi",
     "_check_gpu_inventory",
     "_check_optional_extra",
     "_check_hf_hub_reachable",
diff --git a/pyproject.toml b/pyproject.toml
index 83d14d32..d2f570cb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -40,6 +40,14 @@ classifiers = [
 
 dependencies = [
   "torch>=2.2.0,<3.0.0",
+  # Intel Mac (x86_64) is wheel-locked to torch 2.2.x — PyTorch Foundation
+  # stopped publishing >=2.3 wheels for x86_64 Darwin. torch 2.2 was
+  # compiled against NumPy 1.x; without this marker pip pulls numpy>=2 and
+  # triggers an ABI mismatch (`_ARRAY_API not found`) that silently
+  # degrades the numpy bridge inside torch. Other platforms keep numpy
+  # unconstrained — torch 2.3+ on Linux / Apple Silicon / Windows is
+  # binary-compatible with NumPy 2.x.
+  "numpy<2; sys_platform == 'darwin' and platform_machine == 'x86_64'",
   "transformers>=4.38.0,<5.0.0",
   "peft>=0.9.0,<1.0.0",
   "datasets>=2.21.0,<5.0.0",
diff --git a/tests/test_doctor.py b/tests/test_doctor.py
index 0a4f0b64..838ac131 100644
--- a/tests/test_doctor.py
+++ b/tests/test_doctor.py
@@ -113,6 +113,117 @@ def test_torch_cuda_passes(self) -> None:
         assert "12.4" in result.detail
 
 
+class TestNumpyTorchAbiCheck:
+    """Catches the torch < 2.3 + NumPy >= 2 binary-ABI mismatch.
+
+    The bug surfaces as the ``_ARRAY_API not found`` UserWarning emitted
+    from torch's C++ tensor-numpy bridge.  Intel Mac (x86_64) hosts are
+    the canonical victim — PyTorch Foundation no longer publishes
+    torch >= 2.3 wheels for that platform, so pip caps at torch 2.2.x
+    and any modern numpy on the box silently degrades the bridge.
+    """
+
+    def test_torch_22_with_numpy_2_fails(self) -> None:
+        from forgelm.cli.subcommands._doctor import _check_numpy_torch_abi
+
+        fake_torch = MagicMock()
+        fake_torch.__version__ = "2.2.2"
+        fake_numpy = MagicMock()
+        fake_numpy.__version__ = "2.0.1"
+        with patch.dict("sys.modules", {"torch": fake_torch, "numpy": fake_numpy}):
+            result = _check_numpy_torch_abi()
+        assert result.status == "fail"
+        assert "2.2.2" in result.detail
+        assert "2.0.1" in result.detail
+        assert "numpy<2" in result.detail  # remediation hint
+        assert result.extras["torch_version"] == "2.2.2"
+        assert result.extras["numpy_version"] == "2.0.1"
+
+    def test_torch_23_with_numpy_2_passes(self) -> None:
+        from forgelm.cli.subcommands._doctor import _check_numpy_torch_abi
+
+        fake_torch = MagicMock()
+        fake_torch.__version__ = "2.3.0"
+        fake_numpy = MagicMock()
+        fake_numpy.__version__ = "2.0.1"
+        with patch.dict("sys.modules", {"torch": fake_torch, "numpy": fake_numpy}):
+            result = _check_numpy_torch_abi()
+        assert result.status == "pass"
+        assert "ABI-compatible" in result.detail
+
+    def test_torch_22_with_numpy_1_passes(self) -> None:
+        from forgelm.cli.subcommands._doctor import _check_numpy_torch_abi
+
+        fake_torch = MagicMock()
+        fake_torch.__version__ = "2.2.2"
+        fake_numpy = MagicMock()
+        fake_numpy.__version__ = "1.26.4"
+        with patch.dict("sys.modules", {"torch": fake_torch, "numpy": fake_numpy}):
+            result = _check_numpy_torch_abi()
+        assert result.status == "pass"
+
+    def test_no_numpy_skips_gracefully(self) -> None:
+        """numpy is an optional fast-path for the simhash backend; its
+        absence is not a doctor failure."""
+        import builtins
+
+        from forgelm.cli.subcommands import _doctor
+
+        fake_torch = MagicMock()
+        fake_torch.__version__ = "2.2.2"
+        original_import = builtins.__import__
+
+        def _block_numpy(name, *args, **kwargs):
+            if name == "numpy":
+                raise ImportError("No module named 'numpy'")
+            return original_import(name, *args, **kwargs)
+
+        # Drop any cached numpy so the patched __import__ actually fires.
+        with patch.dict("sys.modules", {"torch": fake_torch}, clear=False):
+            sys.modules.pop("numpy", None)
+            with patch.object(builtins, "__import__", _block_numpy):
+                result = _doctor._check_numpy_torch_abi()
+        assert result.status == "pass"
+        assert result.extras.get("skipped") is True
+        assert result.extras.get("reason") == "numpy_missing"
+
+    def test_no_torch_skips_gracefully(self) -> None:
+        """torch.cuda probe already surfaces a missing torch as fail; the
+        ABI probe must not double-report."""
+        import builtins
+
+        from forgelm.cli.subcommands import _doctor
+
+        original_import = builtins.__import__
+
+        def _block_torch(name, *args, **kwargs):
+            if name == "torch":
+                raise ImportError("No module named 'torch'")
+            return original_import(name, *args, **kwargs)
+
+        # Drop any cached torch so the patched __import__ actually fires.
+        sys.modules.pop("torch", None)
+        with patch.object(builtins, "__import__", _block_torch):
+            result = _doctor._check_numpy_torch_abi()
+        assert result.status == "pass"
+        assert result.extras.get("skipped") is True
+        assert result.extras.get("reason") == "torch_missing"
+
+    def test_handles_prerelease_version_strings(self) -> None:
+        """Tolerate prerelease ('2.2.0a0') and local-version ('2.2.0+cpu')
+        suffixes — common on dev installs."""
+        from forgelm.cli.subcommands._doctor import _check_numpy_torch_abi
+
+        fake_torch = MagicMock()
+        fake_torch.__version__ = "2.2.0+cpu"
+        fake_numpy = MagicMock()
+        fake_numpy.__version__ = "2.0.0rc1"
+        with patch.dict("sys.modules", {"torch": fake_torch, "numpy": fake_numpy}):
+            result = _check_numpy_torch_abi()
+        # 2.2 + 2.0 still triggers the fail path despite the version suffixes.
+        assert result.status == "fail"
+
+
 class TestGpuInventoryCheck:
     def test_no_torch_fails(self) -> None:
         import builtins

From 525f237791a46822870103c74f2f5d57a4dc275f Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Mon, 11 May 2026 01:27:14 +0300
Subject: [PATCH 5/7] =?UTF-8?q?fix(roadmap):=20PR=20#44=20review=20absorpt?=
 =?UTF-8?q?ion=20=E2=80=94=20round=202?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified each finding against current code. Five valid; one nitpick
skipped with reason.

Fixed (5):

- docs/roadmap-tr.md:13  TR mirror "5 wave boyunca 38 faz" →
  "5 wave boyunca 37 içerik fazı + 1 sürüm etiketi = 38 kayıt"
  (semantic alignment with EN line 13's explicit task count).
- docs/roadmap-tr.md:36  added Turkish mirror of the EN
  "Phase 12.6 task / sub-task dual-axis note" — the TR roadmap was
  missing the line entirely after EN line 36's addition in commit
  e080da6.
- docs/roadmap/completed-phases.md:719  removed the orphaned
  "This file details a single phase" note inside the Phase 10.5
  section. The note is a leftover from when phase-10-5-quickstart.md
  was a standalone file; after consolidation, the archive is
  multi-phase, so the note was actively misleading. The Filename
  history paragraph below it is preserved (still accurate) and gains
  a "absorbed into this multi-phase archive in the v0.5.7 cycle"
  clarification.
- docs/roadmap/phase-14-pipeline-chains.md:73  link text
  "phase-12-6-closure-cycle.md" (stale filename) → "Phase 12.6
  closure cycle archive"; href now resolves to the in-document anchor
  "completed-phases.md#phase-126-closure-cycle-38-tasks-across-5-waves".
- docs/roadmap.md + docs/roadmap-tr.md "Latest release on PyPI" /
  "PyPI'deki son sürüm" lines updated from v0.5.5 to chain
  v0.5.7 → v0.5.6 → v0.5.5 with the "what each patch fixed" framing
  (Intel Mac install fix, SFT trainer trl-modernisation fix). The
  EN and TR copy stay in sync.

Skipped (1):

- *Nitpick on completed-phases.md:653-764 duplicate "####
  Tasks/Requirements/Delivery" headings.* Deferred — fixing would
  require renaming ~25 H4s across the absorbed Phase 10/10.5/11
  sections to "### Phase X — Tasks/Requirements/Delivery" patterns
  (and updating any internal cross-references). The repository's
  anchor-resolution gate already passes at strict mode and GitHub
  renders the duplicates fine; this is pure markdownlint cosmetic
  noise. Worth a separate refactor PR if/when a markdownlint-strict
  policy is adopted.

Verified: all 3 doc CI guards green (anchor 266 files, parity 45
pairs, no-analysis-refs).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/roadmap-tr.md                       | 6 ++++--
 docs/roadmap.md                          | 2 +-
 docs/roadmap/completed-phases.md         | 3 +--
 docs/roadmap/phase-14-pipeline-chains.md | 2 +-
 4 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/roadmap-tr.md b/docs/roadmap-tr.md
index 79213060..a5e4bbda 100644
--- a/docs/roadmap-tr.md
+++ b/docs/roadmap-tr.md
@@ -10,7 +10,7 @@
 | ✅ Tamam | [Faz 10 — Post-Training Tamamlama](roadmap/completed-phases.md) | `inference.py`, `chat`, `export` (GGUF), `--fit-check`, `deploy` — `v0.4.0` |
 | ✅ Tamam | [Faz 10.5 — Quickstart Katmanı ve Onboarding](roadmap/completed-phases.md) | `forgelm quickstart <template>`, 5 hazır template, seed veri setleri — `v0.4.5` |
 | ✅ Tamam | [Faz 11 + 11.5 + 12 + 12.5 — Doküman Yutma ve Veri Curation Pipeline'ı](roadmap/releases.md#v050-document-ingestion-data-curation-pipeline) | `forgelm ingest`, `forgelm audit`, PII regex + simhash dedup, LSH banding, streaming reader, PII şiddet katmanları, wizard ingest+audit, MinHash LSH dedup, markdown splitter, code/secrets tarama, kalite heuristic'leri, DOCX tablo koruması, `--all-mask`, Croissant 1.0, Presidio NER — `v0.5.0` (PyPI 2026-04-30) |
-| ✅ Tamam | [Faz 12.6 — Kapanış Döngüsü (5 wave boyunca 38 faz)](roadmap/completed-phases.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommand'leri, compliance verification toolbelt, bilingual mirror sweep + 4 CI guard, supply-chain security, cross-OS release matrix — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
+| ✅ Tamam | [Faz 12.6 — Kapanış Döngüsü (5 wave boyunca 37 içerik fazı + 1 sürüm etiketi = 38 kayıt)](roadmap/completed-phases.md) | Library API, GDPR purge + reverse-pii, ISO 27001 / SOC 2 alignment, doctor + cache subcommand'leri, compliance verification toolbelt, bilingual mirror sweep + 4 CI guard, supply-chain security, cross-OS release matrix — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
 | ✅ Tamam | Faz 22 — CLI sihirbazı tarayıcı yüzeyiyle eşdeğerlik | `forgelm --wizard` artık tarayıcı sihirbazıyla aynı 9-adımlı akışı çalıştırıyor (welcome → use-case → model → strategy → trainer → dataset → training-params → compliance → evaluation), `--wizard-start-from <yaml>` ile idempotent yeniden çalıştırma, şema-güdümlü varsayılanlar SOT, ayrı `EXIT_WIZARD_CANCELLED = 5` exit kodu, `$XDG_CACHE_HOME` altında durum kalıcılığı ve çıkışta validate — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
 | ✅ Tamam | Site dokümantasyon düzeltme taraması | `site/*.html` üzerindeki tüm görünür YAML / artefakt-yolu / CLI / şema iddiaları artık live `forgelm/` yüzeyine karşı doğrulanıyor. Hero YAML demo'su gerçek Pydantic alan adlarıyla yeniden yazıldı, compliance artefakt ağacı disk düzenine göre yeniden çizildi, hayalet YAML anahtarları + CLI flag'leri kaldırıldı, ifadeler live davranışa hizalandı. Altı dilde i18n (en / tr / de / fr / es / zh) tam paritede (her biri 731 anahtar) — `v0.5.5` ile paketlendi (PyPI 2026-05-10) |
 | 📋 Planlandı | [Faz 14 — Çok Aşamalı Pipeline Zincirleri](roadmap/phase-14-pipeline-chains.md) | SFT → DPO → GRPO config zinciri, pipeline kaynak izleri → `v0.6.0` |
@@ -27,12 +27,14 @@
 
 Başlangıçta dört ardışık PyPI tag'i (`v0.5.0` / `v0.5.1` / `v0.5.2` / `v0.5.3`) olarak planlandı, dört faz tek tutarlı yüzey (yut → cila → olgunlaş → cila) oluşturduğu için tek kapsamlı `v0.5.0` release'inde birleştirildi.
 
-**PyPI'deki son sürüm:** `v0.5.5` — "Kapanış Döngüsü Paketi + Faz 22 Sihirbaz + Site Dokümantasyon Taraması" (2026-05-10).  Şunları paketler: **Faz 12.6** (Library API + GDPR purge / reverse-pii + ISO 27001 / SOC 2 alignment + doctor / cache / safety-eval / verify-* subcommand'leri + cross-OS release matrix + supply-chain security baseline; [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) follow-up'ını kapsar), **Faz 22** (CLI sihirbazı tarayıcı yüzeyiyle eşdeğerlik + `--wizard-start-from` ile idempotent yeniden çalıştırma + şema-güdümlü varsayılanlar SOT + ayrı `EXIT_WIZARD_CANCELLED = 5` exit kodu) ve `site/*.html` üzerindeki tüm görünür YAML / artefakt-yolu / CLI / şema iddialarını live kod yüzeyine hizalayan ve altı-dil i18n paritesini eski haline getiren bir **site dokümantasyon düzeltme taraması**.
+**PyPI'deki son sürüm:** `v0.5.7` — "SFT trainer trl-modernizasyon düzeltmesi" (2026-05-10), `v0.5.6` (Intel Mac kurulum düzeltmesi) ve `v0.5.5` "Kapanış Döngüsü Paketi + Faz 22 Sihirbaz + Site Dokümantasyon Taraması" (2026-05-10) üzerine gelen bir takip patch'i.  v0.5.5 şunları paketler: **Faz 12.6** (Library API + GDPR purge / reverse-pii + ISO 27001 / SOC 2 alignment + doctor / cache / safety-eval / verify-* subcommand'leri + cross-OS release matrix + supply-chain security baseline; [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14) follow-up'ını kapsar), **Faz 22** (CLI sihirbazı tarayıcı yüzeyiyle eşdeğerlik + `--wizard-start-from` ile idempotent yeniden çalıştırma + şema-güdümlü varsayılanlar SOT + ayrı `EXIT_WIZARD_CANCELLED = 5` exit kodu) ve `site/*.html` üzerindeki tüm görünür YAML / artefakt-yolu / CLI / şema iddialarını live kod yüzeyine hizalayan ve altı-dil i18n paritesini eski haline getiren bir **site dokümantasyon düzeltme taraması**.  v0.5.6, v0.5.5'teki `torch>=2.3` tabanını `torch>=2.2`'ye düşürerek Intel Mac (x86_64) kurulabilirliğini geri kazandırır.  v0.5.7, trl 0.13'ün `SFTConfig.max_seq_length` → `SFTConfig.max_length` yeniden adlandırmasından kaynaklanan SFT trainer runtime `TypeError` hatasını düzeltir.
 
 **Daha öncesi:** `v0.5.0` — Doküman Yutma + Veri Curation Pipeline'ı (2026-04-30); `v0.4.5` — Quickstart Katmanı (2026-04-26); `v0.4.0` — Post-Training Tamamlama (2026-04-26).
 
 **Güncel durum:** PyPI'da `v0.5.5` altında 19 faz (1, 2, 2.5, 3, 4, 5, 5.5, 6, 7, 8, 9, 10, 10.5, 11, 11.5, 12, 12.5, 12.6, 22) yayınlandı.  Sürüm sonrası 2 faz (13, 14) planlandı.
 
+> **Faz 12.6 görev / alt-görev iki eksenli not:** Faz 12.6 kendi içinde 38 görevlik bir kapanış döngüsüdür (Görev 1-38) ve [`roadmap/completed-phases.md`](roadmap/completed-phases.md) dosyasında izlenir; her wave'in PR açıklaması o wave'in kapsadığı görev delta'sını taşır.
+
 ## Planlanan işlerin özeti
 
 ```mermaid
diff --git a/docs/roadmap.md b/docs/roadmap.md
index c42d07fe..e4f64211 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -27,7 +27,7 @@
 
 Originally planned as four sequential PyPI tags (`v0.5.0` / `v0.5.1` / `v0.5.2` / `v0.5.3`), consolidated into one comprehensive `v0.5.0` release because the four phases form one coherent surface (ingest → polish → mature → polish) hard to use in parts.
 
-**Latest release on PyPI:** `v0.5.5` — "Closure Cycle Bundle + Phase 22 Wizard + Site Documentation Sweep" (2026-05-10).  Bundles **Phase 12.6** (Library API + GDPR purge / reverse-pii + ISO 27001 / SOC 2 alignment + doctor / cache / safety-eval / verify-* subcommands + cross-OS release matrix + supply-chain security baseline; folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14)), **Phase 22** (CLI wizard parity with the in-browser surface + idempotent `--wizard-start-from` re-run + schema-driven defaults SOT + distinct `EXIT_WIZARD_CANCELLED = 5` exit code), and a **site documentation correction sweep** that brings every visible YAML / artefact-path / CLI / schema claim on `site/*.html` in line with the live code surface and restores six-language i18n parity.
+**Latest release on PyPI:** `v0.5.7` — "SFT trainer trl-modernisation fix" (2026-05-10), a follow-up patch on top of `v0.5.6` (Intel Mac install fix) and the headline `v0.5.5` "Closure Cycle Bundle + Phase 22 Wizard + Site Documentation Sweep" (2026-05-10).  v0.5.5 bundled **Phase 12.6** (Library API + GDPR purge / reverse-pii + ISO 27001 / SOC 2 alignment + doctor / cache / safety-eval / verify-* subcommands + cross-OS release matrix + supply-chain security baseline; folds in [#14 webhook SSRF hardening](https://github.com/cemililik/ForgeLM/issues/14)), **Phase 22** (CLI wizard parity with the in-browser surface + idempotent `--wizard-start-from` re-run + schema-driven defaults SOT + distinct `EXIT_WIZARD_CANCELLED = 5` exit code), and a **site documentation correction sweep** that brings every visible YAML / artefact-path / CLI / schema claim on `site/*.html` in line with the live code surface and restores six-language i18n parity.  v0.5.6 reverted the v0.5.5 `torch>=2.3` floor back to `torch>=2.2` to restore Intel Mac (x86_64) installability.  v0.5.7 fixes a runtime `TypeError` in the SFT trainer caused by trl 0.13 renaming `SFTConfig.max_seq_length` → `SFTConfig.max_length`.
 
 **Earlier:** `v0.5.0` — Document Ingestion + Data Curation Pipeline (2026-04-30); `v0.4.5` — Quickstart Layer (2026-04-26); `v0.4.0` — Post-Training Completion (2026-04-26).
 
diff --git a/docs/roadmap/completed-phases.md b/docs/roadmap/completed-phases.md
index e275e72b..ccbbe255 100644
--- a/docs/roadmap/completed-phases.md
+++ b/docs/roadmap/completed-phases.md
@@ -716,8 +716,7 @@ graph TD
 
 > **Status:** ✅ **DONE** — shipped as `v0.4.5` on 2026-04-26 (PyPI). Module: [`forgelm/quickstart.py`](../../forgelm/quickstart.py); five bundled templates under [`forgelm/templates/`](../../forgelm/templates/); CLI: `forgelm quickstart <template>`; tests: [`tests/test_quickstart.py`](../../tests/test_quickstart.py); CI smoke in [nightly.yml](../../.github/workflows/nightly.yml).
 
-> **Note:** This file details a single phase. For a summary of all phases, see [../roadmap.md](../roadmap.md).
-> **Filename history:** Originally `phase-12-quickstart.md` (the slot Quickstart held in early planning); renamed to its current filename slug in the v0.5.2 cycle so the filename matches the current phase number. The Phase 12 slot now belongs to [Data Curation Maturity](#phase-12-data-curation-maturity).
+> **Filename history:** Originally tracked under `phase-12-quickstart.md` (the slot Quickstart held in early planning); renamed to `phase-10-5-quickstart.md` in the v0.5.2 cycle so the filename matched the current phase number, then absorbed into this multi-phase archive in the v0.5.7 cycle. The Phase 12 slot now belongs to [Data Curation Maturity](#phase-12-data-curation-maturity).
 
 **Goal:** Make "my first fine-tune" a 10-minute experience. One command, one model in the end, zero YAML writing. Without sacrificing the CI/CD-native core — quickstart generates a YAML the user can later customize.
 **Estimated Effort:** Medium (1-2 months) — **Actual: 1 week**
diff --git a/docs/roadmap/phase-14-pipeline-chains.md b/docs/roadmap/phase-14-pipeline-chains.md
index 8afbe86f..b37bb763 100644
--- a/docs/roadmap/phase-14-pipeline-chains.md
+++ b/docs/roadmap/phase-14-pipeline-chains.md
@@ -70,7 +70,7 @@
 - `--dry-run` validates all stages' configs before any GPU allocation.
 
 ### Delivery:
-- Target release: `v0.6.0` (reslotted from earlier `v0.5.x` placeholders; Phase 14 is grouped with the Phase 13 Pro CLI tier per the v0.5.5 closure cycle's deferred-callout policy in `docs/usermanuals/{en,tr}/deployment/model-merging.md` and the [phase-12-6-closure-cycle.md](completed-phases.md) summary).
+- Target release: `v0.6.0` (reslotted from earlier `v0.5.x` placeholders; Phase 14 is grouped with the Phase 13 Pro CLI tier per the v0.5.5 closure cycle's deferred-callout policy in `docs/usermanuals/{en,tr}/deployment/model-merging.md` and the [Phase 12.6 closure cycle archive](completed-phases.md#phase-126-closure-cycle-38-tasks-across-5-waves)).
 - No hard blockers; the v0.5.5 closure cycle has merged. Phase 14 starts after the v0.5.5 PyPI tag is published.
 
 ---

From f205f426099619c9fb9bef7cf7902026289feb5f Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Mon, 11 May 2026 02:48:43 +0300
Subject: [PATCH 6/7] =?UTF-8?q?fix(release):=20PR=20#44=20review=20absorpt?=
 =?UTF-8?q?ion=20=E2=80=94=20round=203?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three concerns from the round-3 cross-review of v0.5.7's review-cycle
follow-ups: a hard-fail upgrade to the SFT signature-detection branch,
a training-pipeline preflight that turns the NumPy 2 / torch 2.2 ABI
mismatch into a single-line actionable error instead of a cryptic
mid-training `NameError: name '_C' is not defined`, and a pre-existing
test-pollution cascade that hid 35 unrelated failures behind a
half-loaded `torch._C` whenever the full suite ran.

- `forgelm/trainer.py::_get_training_args_for_type` SFT branch now
  raises `ValueError` when neither `max_length` nor `max_seq_length`
  is on `SFTConfig`'s signature; warn-and-continue was a silent-loss
  hole against an explicit YAML setting.
- New `forgelm/cli/_abi_check.py` carries the shared verdict +
  remediation string; the doctor probe and the new
  `_preflight_numpy_torch_abi` in `forgelm/cli/_training.py` both
  consume it. Preflight is a no-op on healthy platforms.
- `tests/test_doctor.py` + `tests/test_quickstart_compat.py` swap
  bare `sys.modules.pop("torch"/"numpy")` for `monkeypatch.delitem`
  so the stranded modules no longer poison every later
  `from trl import SFTConfig` in the same pytest session.
- Roadmap stale-ref cleanup: completed-phases.md and
  risks-and-decisions.md no longer cite the deleted phase-11-5-backlog.md
  and phase-12-data-curation-maturity.md files; three leftover "faz"
  strings in the Phase 12.6 section now read "task".

Verified: 1648 passed, 14 skipped, 0 failed (project floor 40% met
at 73.81% coverage); ruff format + ruff check + all five doc guards
(anchor-resolution, no-analysis-refs, bilingual-parity, CLI help,
wizard-defaults) green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                        |  46 ++++++++
 docs/roadmap/completed-phases.md    |   8 +-
 docs/roadmap/risks-and-decisions.md |   2 +-
 forgelm/_version.py                 |   6 +-
 forgelm/cli/_abi_check.py           | 105 +++++++++++++++++
 forgelm/cli/_training.py            |  43 +++++++
 forgelm/cli/subcommands/_doctor.py  |  78 +++++--------
 forgelm/trainer.py                  |  18 ++-
 tests/test_abi_check.py             | 175 ++++++++++++++++++++++++++++
 tests/test_doctor.py                |  40 ++++---
 tests/test_quickstart_compat.py     |  17 ++-
 tests/test_trainer_sft_config.py    |  89 ++++++++++++--
 12 files changed, 543 insertions(+), 84 deletions(-)
 create mode 100644 forgelm/cli/_abi_check.py
 create mode 100644 tests/test_abi_check.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index add0cfc3..f75476d0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,52 @@ All notable changes to ForgeLM are documented here.
 
 ## [Unreleased]
 
+Review-absorption round 3 follow-up to v0.5.7. No public surface change,
+but training-pipeline UX, doctor robustness, and roadmap hygiene
+improve.
+
+### Added
+
+- **Early-fail ABI preflight in the training pipeline.** A new shared
+  helper at `forgelm/cli/_abi_check.py` runs the same numpy/torch
+  pairing check as `forgelm doctor`'s `numpy.torch_abi` probe, and
+  `forgelm/cli/_training.py::_run_training_pipeline` now calls it
+  before importing the heavy stack. An operator who hits a residual
+  Intel Mac NumPy 2 mismatch (drifted env, out-of-band
+  `pip install -U numpy`) now sees a single-line error with the exact
+  remediation command (`pip install 'numpy<2'`) instead of a cryptic
+  `NameError: name '_C' is not defined` from torch mid-training. The
+  PEP 508 marker in `pyproject.toml` remains the primary fix for
+  fresh installs; the preflight is the second line of defense.
+
+### Fixed
+
+- **`forgelm/trainer.py::_get_training_args_for_type`** — SFT branch
+  now raises `ValueError` (not warn-and-continue) when neither
+  `max_length` nor `max_seq_length` is exposed on `SFTConfig`. Silent
+  drop of an explicit `model.max_length` YAML setting would violate
+  `docs/standards/error-handling.md` "no silent failures" — error
+  message lists the actually-detected parameters for forensics.
+- **`tests/test_doctor.py` + `tests/test_quickstart_compat.py`** —
+  three pre-existing tests that popped `sys.modules['torch']` /
+  `sys.modules['numpy']` without restoring them now use
+  `monkeypatch.delitem` for tracked teardown. The stranded modules
+  half-initialised every subsequent `import torch` in the pytest
+  session (`torch._C` never re-bound), causing every downstream
+  `from trl import SFTConfig` and a long tail of merging / moe /
+  quickstart / wizard / judge / safety tests to fail in the full
+  suite even though they passed in isolation. Pure test-only fix; no
+  production behaviour change.
+- **`forgelm/cli/subcommands/_doctor.py::_check_numpy_torch_abi`** —
+  refactored to call into the shared `_abi_check.py` helper rather
+  than duplicating the version-parsing + threshold logic. Docstring
+  tightened to honestly note that torch's C++ `_ARRAY_API not found`
+  message is outside Python's warnings machinery and `fprintf(stderr,
+  …)`-based suppression would require fd-level redirection (which is
+  unsafe in a long-lived CLI process). Module-level `re` / `warnings`
+  imports promoted from function-local since the shared helper now
+  owns them.
+
 ## [0.5.7] — 2026-05-10
 
 Patch release. Fixes a runtime `TypeError` in the SFT trainer that
diff --git a/docs/roadmap/completed-phases.md b/docs/roadmap/completed-phases.md
index ccbbe255..2789ac3a 100644
--- a/docs/roadmap/completed-phases.md
+++ b/docs/roadmap/completed-phases.md
@@ -927,7 +927,7 @@ suite because it is wall-clock-noisy.
 
 > **Note:** Phase 11 + 11.5 built the ingestion / audit lineage (Phase 11 → `v0.5.0`, Phase 11.5 → `v0.5.1`); this phase moves the same lineage from **enterprise-acceptable** to **enterprise-competitive**.
 
-**Goal:** Mature ForgeLM's `forgelm ingest` + `forgelm audit` layer along three axes — **scale** (LSH-based near-duplicate detection beyond ~50K rows, large-corpus throughput), **security** (code/secret leakage scanning + optional ML-based PII), and **quality** (markdown-aware chunking + heuristic quality filters + table structure preservation). The competitive review that followed Phase 11.5 (see `docs/roadmap/phase-11-5-backlog.md` "Measured speedups" section + the 2026-04-27 ingestion-comparison synthesis) lists the exact gaps this phase closes.
+**Goal:** Mature ForgeLM's `forgelm ingest` + `forgelm audit` layer along three axes — **scale** (LSH-based near-duplicate detection beyond ~50K rows, large-corpus throughput), **security** (code/secret leakage scanning + optional ML-based PII), and **quality** (markdown-aware chunking + heuristic quality filters + table structure preservation). The competitive review that followed Phase 11.5 (see [Phase 11.5 section above](#phase-115-ingestion-audit-polish), "Measured speedups" subsection, plus the 2026-04-27 ingestion-comparison synthesis) lists the exact gaps this phase closes.
 
 **Estimated Effort:** Medium (4-6 weeks) — **Actual: ~1 day** (single-author implementation, leveraging the streaming aggregator + tier-mapped pattern from Phase 11.5).
 **Priority:** High — answers the enterprise demand surfaced after the `v0.5.0` PyPI launch; sequences naturally with Phase 14 (Multi-Stage Pipeline Chains), which is reslotted to `v0.5.3`.
@@ -1139,11 +1139,11 @@ The "Won't-do" list at the bottom of [(see Phase 12 — Data Curation Maturity s
 
 The v0.5.0 master code review surfaced **175 findings** plus **4 user-added scope items** (Library API support, ISO 27001 / SOC 2 alignment, GDPR right-to-erasure full implementation, Article 14 real staging). Rather than stretch these across 5 sequential patch releases, the maintainer chose **Path B — full Tasks 1-38 sweep into a single v0.5.5 tag**:
 
-- Bisectable PR-per-faz history
-- One coherent surface (every faz feeds the same release candidate)
+- Bisectable PR-per-task history
+- One coherent surface (every task feeds the same release candidate)
 - 5/5 quality bar reached before publish, not after
 
-The 38 tasks were merged across **5 integration waves** (Wave 0/1 through Wave 5). Each wave landed via a dedicated PR onto `development`, then into `main`. This file is the index that maps every faz to its wave, integration PR, and merge SHA.
+The 38 tasks were merged across **5 integration waves** (Wave 0/1 through Wave 5). Each wave landed via a dedicated PR onto `development`, then into `main`. This file is the index that maps every task to its wave, integration PR, and merge SHA.
 
 ### Scope (in / out)
 
diff --git a/docs/roadmap/risks-and-decisions.md b/docs/roadmap/risks-and-decisions.md
index 1a62b9f3..4c6a0f72 100644
--- a/docs/roadmap/risks-and-decisions.md
+++ b/docs/roadmap/risks-and-decisions.md
@@ -95,7 +95,7 @@
 | **F-PR29-A6-15-followup** — Bare `# NOSONAR` rule-code sweep | Low | Lint / Style | ~30 BLE001 sites in `forgelm/` use bare `# NOSONAR` without the rule code. Wave 2-4 added the NOSONAR-discipline section to `coding.md` (rule code + rationale required). Sweep all bare-NOSONAR sites and append `python:S<id>` per the new policy. Mechanical refactor; no behaviour change. | ~2 h | TBD |
 | **F-PR29-A5-anchor-slugifier** — anchor-resolution checker GFM divergence | Low | Tooling | Wave 2-7 surfaced two anchor-slugger divergences vs GitHub-flavored Markdown in `tools/check_anchor_resolution.py`: (i) multi-dash collapse (local checker collapses `-+` → `-`; GFM preserves), (ii) duplicate-heading disambiguation (GFM appends `-1`/`-2`; local stores in `set`). Two fixed locally as workarounds in `safety_compliance-tr.md`; align checker's slugifier with GFM in v0.6.x. | ~2 h | TBD |
 | **F-PR29-A2-13-design-doc-paths** — `library-api-design.md` `forgelm/api.py` references | Low | Docs | Wave 2-13 added a Status callout in §5.1 noting impl diverged from design (3-segment vs 2-segment `__api_version__`), but ~7 downstream sentences still reference `forgelm/api.py` as the version-home module (the file does not exist; `forgelm/_version.py` is canonical). Sweep `__api_version__` location refs in design doc to point at `_version.py` for full historical-vs-current clarity. Doc-only. | ~30 min | TBD |
-| **F-PR29-A6-05-issue-link** — open GitHub issue tracking semantic-chunking deferral | Low | Docs / Tracking | `forgelm/ingestion.py:_chunk_semantic` raises `NotImplementedError` referencing this row. Open a GitHub issue at https://github.com/cemililik/ForgeLM/issues describing the embedding-based semantic-chunking deferral (per `docs/roadmap/phase-12-data-curation-maturity.md` "deferred to Phase 13+ for Annex IV reproducibility"); update the message in `ingestion.py:_chunk_semantic` to reference the real issue number. | ~5 min | TBD |
+| **F-PR29-A6-05-issue-link** — open GitHub issue tracking semantic-chunking deferral | Low | Docs / Tracking | `forgelm/ingestion.py:_chunk_semantic` raises `NotImplementedError` referencing this row. Open a GitHub issue at https://github.com/cemililik/ForgeLM/issues describing the embedding-based semantic-chunking deferral (per [completed-phases.md "Phase 12 — Data Curation Maturity"](completed-phases.md#phase-12-data-curation-maturity), "deferred to Phase 13+ for Annex IV reproducibility"); update the message in `ingestion.py:_chunk_semantic` to reference the real issue number. | ~5 min | TBD |
 | **F-PR29-A6-lock-file** — `requirements.lock` for development environments | Low | Supply-chain | SonarCloud `text:S8565` flags `pyproject.toml` for missing `uv.lock` / `poetry.lock`. ForgeLM uses pip + setuptools (not uv / poetry), and bounded-range `[project.dependencies]` + nightly `pip-audit` + per-OS CycloneDX SBOMs cover the supply-chain determinism story. A pip-tools workflow producing `requirements.lock` (input: `pyproject.toml` extras; output: pinned hash-locked txt) would be a strict improvement for development environment reproducibility — track here for v0.6.x; SonarCloud finding suppressed via `# NOSONAR text:S8565` at `pyproject.toml:1`. | ~2 h | TBD |
 
 **Removal contract.** A row is removed from this table only when:
diff --git a/forgelm/_version.py b/forgelm/_version.py
index d442df63..d0c17647 100644
--- a/forgelm/_version.py
+++ b/forgelm/_version.py
@@ -37,8 +37,10 @@
 # the formal Phase 19 library-API surface — 30 stable symbols in
 # ``forgelm.__all__``).  v0.5.6 reverted the v0.5.5 torch min bump;
 # v0.5.7 fixes a runtime ``SFTConfig.max_seq_length`` TypeError on
-# modern trl (rename to ``max_length`` in trl 0.13+).  Neither patch
-# changes the Python API surface, so ``__api_version__`` stays at 1.0.0.
+# modern trl (rename to ``max_length`` in trl 0.13+) plus the Intel
+# Mac NumPy 2 ABI mismatch (numpy<2 marker + ``numpy.torch_abi``
+# doctor probe).  None of these patches change the Python API
+# surface, so ``__api_version__`` stays at 1.0.0.
 __api_version__ = "1.0.0"
 
 __all__ = ["__version__", "__api_version__"]
diff --git a/forgelm/cli/_abi_check.py b/forgelm/cli/_abi_check.py
new file mode 100644
index 00000000..d004caaa
--- /dev/null
+++ b/forgelm/cli/_abi_check.py
@@ -0,0 +1,105 @@
+"""Shared torch / NumPy ABI compatibility probe.
+
+Used in two places with two different contracts:
+
+- :mod:`forgelm.cli.subcommands._doctor` wraps the verdict in a
+  ``_CheckResult`` for the ``numpy.torch_abi`` probe (informational
+  diagnostic — pass / fail with details).
+- :mod:`forgelm.cli._training` calls it as an **early-fail gate** before
+  the training pipeline imports torch heavily.  Detecting the mismatch
+  here means the operator sees an actionable remediation message
+  ("``pip install 'numpy<2'``") instead of a cryptic
+  ``NameError: name '_C' is not defined`` mid-training.
+
+The check itself: torch < 2.3 was compiled against NumPy 1.x and silently
+degrades when paired with NumPy 2.x (the well-known ``_ARRAY_API not
+found`` UserWarning from torch's C++ tensor-numpy bridge).  Intel Mac
+(x86_64) is the platform where this routinely bites — PyTorch Foundation
+no longer publishes torch >= 2.3 wheels for that target.  v0.5.7 ships a
+PEP 508 marker in ``pyproject.toml`` that pins ``numpy<2`` on Intel Mac
+for fresh installs; this preflight catches the residual cases (env
+manually drifted; user installed torch out-of-band).
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+from typing import Optional, Tuple
+
+# Status vocabulary.  Centralised so a future rename cannot drift across
+# doctor + training callers.
+ABI_OK = "compatible"
+ABI_BROKEN = "incompatible"
+ABI_SKIPPED_TORCH = "skipped_torch_missing"
+ABI_SKIPPED_NUMPY = "skipped_numpy_missing"
+
+
+def _major_minor(version: str) -> Tuple[int, int]:
+    """Extract the leading (MAJOR, MINOR) tuple from a version string.
+
+    Tolerates prerelease ("2.2.0a0") and local-version ("2.2.0+cpu")
+    suffixes by matching only the leading ``\\d+\\.\\d+`` pair.
+    Returns ``(0, 0)`` on a totally unparseable string — callers that
+    care about the forensic distinction (the doctor probe) wrap with
+    their own debug-logging call.
+    """
+    match = re.match(r"^(\d+)\.(\d+)", version)
+    if not match:
+        return (0, 0)
+    return (int(match.group(1)), int(match.group(2)))
+
+
+def compute_numpy_torch_abi_status() -> Tuple[str, Optional[str], Optional[str]]:
+    """Return the ABI verdict + version strings.
+
+    Three-tuple ``(status, torch_version, numpy_version)``:
+
+    - ``status`` is one of :data:`ABI_OK`, :data:`ABI_BROKEN`,
+      :data:`ABI_SKIPPED_TORCH`, :data:`ABI_SKIPPED_NUMPY`.
+    - ``torch_version`` / ``numpy_version`` are ``None`` when the
+      corresponding library is not installed.
+
+    torch + numpy are imported with Python warnings suppressed so this
+    probe does not emit a duplicate ``UserWarning``.  Note: the
+    underlying ``_ARRAY_API not found`` message ships from torch's C++
+    side via ``fprintf(stderr, …)`` and is outside Python's warnings
+    machinery — see the doctor probe docstring for the full caveat.
+    """
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            import torch
+    except ImportError:
+        return (ABI_SKIPPED_TORCH, None, None)
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            import numpy
+    except ImportError:
+        return (ABI_SKIPPED_NUMPY, torch.__version__, None)
+
+    torch_mm = _major_minor(torch.__version__)
+    numpy_mm = _major_minor(numpy.__version__)
+    # The known incompatibility window: torch < 2.3 was built against
+    # NumPy 1.x and silently degrades when paired with NumPy 2.x.
+    if torch_mm < (2, 3) and numpy_mm >= (2, 0):
+        return (ABI_BROKEN, torch.__version__, numpy.__version__)
+    return (ABI_OK, torch.__version__, numpy.__version__)
+
+
+def format_abi_remediation(torch_version: str, numpy_version: str) -> str:
+    """Human-readable remediation hint for an incompatible ABI.
+
+    Kept identical to the doctor probe's ``detail`` line so the
+    operator sees the same fix instructions whether they hit the
+    training preflight or ran ``forgelm doctor`` first.
+    """
+    return (
+        f"torch {torch_version} (compiled against NumPy 1.x) is paired with "
+        f"numpy {numpy_version}. This triggers an `_ARRAY_API not found` "
+        "ABI mismatch and silently degrades the numpy bridge inside torch. "
+        "Fix with: pip install 'numpy<2' (or upgrade to torch>=2.3 if your "
+        "platform has wheels for it). Run `forgelm doctor` for the full "
+        "environment diagnostic."
+    )
diff --git a/forgelm/cli/_training.py b/forgelm/cli/_training.py
index 53e66265..ab470c01 100644
--- a/forgelm/cli/_training.py
+++ b/forgelm/cli/_training.py
@@ -29,8 +29,51 @@ def _report_training_error(
     sys.exit(exit_code)
 
 
+def _preflight_numpy_torch_abi(json_output: bool) -> None:
+    """Fail fast on a known torch / NumPy ABI mismatch.
+
+    The v0.5.7 ``pyproject.toml`` PEP 508 marker pins ``numpy<2`` on
+    Intel Mac (the platform where ``torch<2.3`` + ``numpy>=2`` produces
+    the cryptic ``_ARRAY_API not found`` / ``NameError: _C not defined``
+    failure mode), but the marker only fires on fresh installs and
+    ``pip install -U`` re-resolves.  A user who upgraded numpy
+    out-of-band after installing ForgeLM ends up with a silently broken
+    torch — and previously hit the failure deep inside training with no
+    actionable error.
+
+    This preflight runs the same probe as ``forgelm doctor``'s
+    ``numpy.torch_abi`` check and aborts with the exact remediation
+    command if the mismatch is present.  No-op on healthy platforms
+    (Linux, Apple Silicon, fresh-install Intel Mac), so zero false
+    positives.
+    """
+    from ._abi_check import ABI_BROKEN, compute_numpy_torch_abi_status, format_abi_remediation
+
+    status, torch_version, numpy_version = compute_numpy_torch_abi_status()
+    if status != ABI_BROKEN:
+        return
+    remediation = format_abi_remediation(torch_version, numpy_version)
+    _report_training_error(
+        json_output,
+        payload={
+            "success": False,
+            "error": "numpy_torch_abi_mismatch",
+            "torch_version": torch_version,
+            "numpy_version": numpy_version,
+            "remediation": remediation,
+        },
+        log_msg=f"Aborting before training: {remediation}",
+        exit_code=EXIT_TRAINING_ERROR,
+    )
+
+
 def _run_training_pipeline(config, args, json_output: bool) -> None:
     """Run the full training pipeline (model load → data → trainer.train → cleanup)."""
+    # Preflight: detect Intel-Mac-style torch/NumPy ABI mismatch BEFORE
+    # the heavy imports below would surface it as a cryptic NameError
+    # mid-pipeline.  No-op on healthy platforms.
+    _preflight_numpy_torch_abi(json_output)
+
     # Defer heavy imports so `--help`, `--version`, and `--dry-run` stay lightweight.
     # ImportError here means a required optional extra is missing — surface as install hint.
     try:
diff --git a/forgelm/cli/subcommands/_doctor.py b/forgelm/cli/subcommands/_doctor.py
index f082f39e..63511c03 100644
--- a/forgelm/cli/subcommands/_doctor.py
+++ b/forgelm/cli/subcommands/_doctor.py
@@ -213,26 +213,30 @@ def _check_torch_cuda() -> _CheckResult:
 def _check_numpy_torch_abi() -> _CheckResult:
     """Detect a torch <-> numpy binary-ABI mismatch.
 
-    PyTorch wheels are compiled against a specific NumPy major version:
-    torch < 2.3 was built against NumPy 1.x and silently degrades when
-    paired with NumPy 2.x (the well-known ``_ARRAY_API not found``
-    UserWarning emitted from torch's C++ tensor-numpy bridge).  This
-    typically bites Intel Mac (x86_64) hosts where PyTorch Foundation
-    no longer publishes torch >= 2.3 wheels, so pip's resolver caps at
-    torch 2.2.x and any newer numpy on the box mismatches.
-
-    Best-effort probe: torch / numpy are imported with warnings
-    suppressed so the probe itself does not pollute stderr with the
-    very ``UserWarning`` it is trying to detect.
+    Thin doctor-side wrapper over
+    :func:`forgelm.cli._abi_check.compute_numpy_torch_abi_status`; the
+    same helper is also called as a fail-fast preflight from
+    :mod:`forgelm.cli._training` so an operator who skips ``forgelm
+    doctor`` and jumps straight to training still gets the actionable
+    remediation message rather than a cryptic
+    ``NameError: name '_C' is not defined`` from torch mid-run.
+
+    See :mod:`forgelm.cli._abi_check` for the underlying logic + the
+    full stderr-suppression caveat (torch's C++ ``_ARRAY_API not
+    found`` line is outside Python's warnings machinery).
     """
-    import re
-    import warnings
+    from .._abi_check import (
+        ABI_BROKEN,
+        ABI_OK,
+        ABI_SKIPPED_NUMPY,
+        ABI_SKIPPED_TORCH,
+        compute_numpy_torch_abi_status,
+        format_abi_remediation,
+    )
 
-    try:
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            import torch
-    except ImportError:
+    status, torch_version, numpy_version = compute_numpy_torch_abi_status()
+
+    if status == ABI_SKIPPED_TORCH:
         # The dedicated torch.cuda probe already surfaces a missing
         # torch as fail; do not double-report here.
         return _CheckResult(
@@ -241,11 +245,7 @@ def _check_numpy_torch_abi() -> _CheckResult:
             detail="torch is not installed; ABI compatibility check skipped.",
             extras={"skipped": True, "reason": "torch_missing"},
         )
-    try:
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            import numpy
-    except ImportError:
+    if status == ABI_SKIPPED_NUMPY:
         # numpy is an *optional* fast-path for the simhash backend
         # (see forgelm/data_audit/_optional.py::_HAS_NUMPY) — its
         # absence is not a doctor failure.
@@ -256,41 +256,25 @@ def _check_numpy_torch_abi() -> _CheckResult:
             extras={"skipped": True, "reason": "numpy_missing"},
         )
 
-    def _major_minor(version: str) -> Tuple[int, int]:
-        # Tolerates prerelease ("2.2.0a0") and local-version ("2.2.0+cpu")
-        # suffixes by extracting the leading numeric MAJOR.MINOR pair only.
-        match = re.match(r"^(\d+)\.(\d+)", version)
-        if not match:
-            return (0, 0)
-        return (int(match.group(1)), int(match.group(2)))
-
-    torch_mm = _major_minor(torch.__version__)
-    numpy_mm = _major_minor(numpy.__version__)
     extras: Dict[str, Any] = {
-        "torch_version": torch.__version__,
-        "numpy_version": numpy.__version__,
+        "torch_version": torch_version,
+        "numpy_version": numpy_version,
     }
-
-    # The known incompatibility window: torch < 2.3 was built against
-    # NumPy 1.x and silently degrades when paired with NumPy 2.x.
-    if torch_mm < (2, 3) and numpy_mm >= (2, 0):
+    if status == ABI_BROKEN:
+        # ``format_abi_remediation`` is the canonical fix-instructions
+        # string — shared so the training preflight emits the same hint.
         return _CheckResult(
             name=_PROBE_NUMPY_TORCH_ABI,
             status=_STATUS_FAIL,
-            detail=(
-                f"torch {torch.__version__} (compiled against NumPy 1.x) is "
-                f"paired with numpy {numpy.__version__}. This triggers an "
-                "`_ARRAY_API not found` ABI mismatch and silently degrades "
-                "the numpy bridge inside torch. Fix with: pip install 'numpy<2' "
-                "(or upgrade to torch>=2.3 if your platform has wheels for it)."
-            ),
+            detail=format_abi_remediation(torch_version, numpy_version),
             extras=extras,
         )
 
+    assert status == ABI_OK, f"unexpected ABI status {status!r}"
     return _CheckResult(
         name=_PROBE_NUMPY_TORCH_ABI,
         status=_STATUS_PASS,
-        detail=f"torch {torch.__version__} + numpy {numpy.__version__} are ABI-compatible.",
+        detail=f"torch {torch_version} + numpy {numpy_version} are ABI-compatible.",
         extras=extras,
     )
 
diff --git a/forgelm/trainer.py b/forgelm/trainer.py
index b1677001..544a5cb8 100644
--- a/forgelm/trainer.py
+++ b/forgelm/trainer.py
@@ -1,3 +1,4 @@
+import inspect
 import logging
 import math
 import os
@@ -425,8 +426,6 @@ def _get_training_args_for_type(self):
         kwargs = self._get_common_training_kwargs()
 
         if tt == "sft":
-            import inspect
-
             from trl import SFTConfig
 
             kwargs["packing"] = bool(getattr(self.config.training, "packing", False))
@@ -435,11 +434,26 @@ def _get_training_args_for_type(self):
             #   trl 0.12.x: ``SFTConfig(max_seq_length=...)``
             #   trl 0.13+ / 1.x: ``SFTConfig(max_length=...)`` — old name removed
             # ``pyproject.toml`` pins ``trl>=0.12.0,<2.0.0``, so detect at runtime.
+            # Hard-fail (don't warn-and-continue) if neither name is exposed:
+            # silently dropping ``model.max_length`` would let TRL pick its
+            # default and produce a model trained against an unintended
+            # context window — exactly the "no silent failures" rule in
+            # docs/standards/error-handling.md.
             sft_params = inspect.signature(SFTConfig).parameters
             if "max_length" in sft_params:
                 kwargs["max_length"] = self.config.model.max_length
             elif "max_seq_length" in sft_params:
                 kwargs["max_seq_length"] = self.config.model.max_length
+            else:
+                import trl as _trl
+
+                raise ValueError(
+                    f"SFTConfig in trl {getattr(_trl, '__version__', '?')} exposes neither "
+                    "`max_length` nor `max_seq_length` as a named parameter; cannot apply "
+                    f"the sequence-length cap from config (model.max_length={self.config.model.max_length}). "
+                    f"Detected parameters: {sorted(sft_params)}. Pin trl to a known-compatible "
+                    "version or file an issue referencing this error."
+                )
             return SFTConfig(**kwargs)
 
         elif tt == "orpo":
diff --git a/tests/test_abi_check.py b/tests/test_abi_check.py
new file mode 100644
index 00000000..d511fe23
--- /dev/null
+++ b/tests/test_abi_check.py
@@ -0,0 +1,175 @@
+"""Tests for the shared torch/NumPy ABI compatibility probe.
+
+The probe lives at ``forgelm.cli._abi_check`` and is exercised by two
+call sites:
+
+- The doctor probe (``forgelm doctor`` -> ``numpy.torch_abi``) — covered
+  in ``tests/test_doctor.py``.
+- The training-pipeline preflight (``forgelm.cli._training`` ->
+  ``_preflight_numpy_torch_abi``) — covered here.
+
+The preflight is the second line of defense after the PEP 508 marker in
+``pyproject.toml`` (``numpy<2; platform_system == "Darwin" and
+platform_machine == "x86_64"``).  The marker auto-fixes fresh installs
+and ``pip install -U`` re-resolves; the preflight catches residual
+drift (out-of-band ``pip install numpy>=2`` after a working install).
+
+Note on mocking strategy: we deliberately monkeypatch ``__version__``
+on the real torch / numpy modules instead of substituting fake modules
+into ``sys.modules``.  Replacing ``sys.modules["torch"]`` with a stand-in
+breaks TRL's lazy-module loader for any subsequent test in the same
+process (``trl.SFTConfig`` triggers a deferred ``torch._C`` lookup that
+fails on the stand-in) — exactly the test pollution we are trying to
+avoid in the first place.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import patch
+
+import pytest
+
+from forgelm.cli import _abi_check, _training
+
+
+class TestMajorMinor:
+    """Version-string -> (MAJOR, MINOR) parser tolerates real-world labels."""
+
+    def test_plain_version(self):
+        assert _abi_check._major_minor("2.4.4") == (2, 4)
+
+    def test_prerelease_suffix(self):
+        assert _abi_check._major_minor("2.2.0a0") == (2, 2)
+
+    def test_local_version_suffix(self):
+        # "+cpu", "+cu118", etc. are PyTorch's standard local-version tags.
+        assert _abi_check._major_minor("2.2.0+cpu") == (2, 2)
+        assert _abi_check._major_minor("2.1.0+cu118") == (2, 1)
+
+    def test_unparseable_returns_zero(self):
+        # Defensive fallback: any totally-broken string maps to (0, 0).
+        assert _abi_check._major_minor("garbage") == (0, 0)
+        assert _abi_check._major_minor("") == (0, 0)
+
+
+class TestComputeStatus:
+    """Branch coverage for the verdict triple, via ``__version__`` swaps.
+
+    Real torch + numpy stay in ``sys.modules``; only the ``__version__``
+    strings move.  This is critical: substituting fake modules would
+    poison TRL's lazy-import cache for every later test in the suite.
+    """
+
+    def test_compatible_modern_numpy(self, monkeypatch):
+        import numpy
+        import torch
+
+        monkeypatch.setattr(torch, "__version__", "2.4.0")
+        monkeypatch.setattr(numpy, "__version__", "2.0.0")
+        status, torch_v, numpy_v = _abi_check.compute_numpy_torch_abi_status()
+        assert status == _abi_check.ABI_OK
+        assert torch_v == "2.4.0"
+        assert numpy_v == "2.0.0"
+
+    def test_compatible_legacy_numpy(self, monkeypatch):
+        # The known-good Intel Mac pairing: torch 2.2.x (NumPy-1 ABI) + numpy 1.x.
+        import numpy
+        import torch
+
+        monkeypatch.setattr(torch, "__version__", "2.2.0")
+        monkeypatch.setattr(numpy, "__version__", "1.26.4")
+        status, _, _ = _abi_check.compute_numpy_torch_abi_status()
+        assert status == _abi_check.ABI_OK
+
+    def test_broken_intel_mac_pairing(self, monkeypatch):
+        # The exact v0.5.7 target case: torch 2.2.x (NumPy-1 ABI) + numpy 2.x.
+        import numpy
+        import torch
+
+        monkeypatch.setattr(torch, "__version__", "2.2.2")
+        monkeypatch.setattr(numpy, "__version__", "2.4.4")
+        status, torch_v, numpy_v = _abi_check.compute_numpy_torch_abi_status()
+        assert status == _abi_check.ABI_BROKEN
+        assert torch_v == "2.2.2"
+        assert numpy_v == "2.4.4"
+
+    def test_boundary_torch_23_with_numpy_2(self, monkeypatch):
+        # torch 2.3 was the first wheel built against NumPy 2 ABI —
+        # the mismatch window is `torch < 2.3 AND numpy >= 2`, so
+        # torch 2.3.0 + numpy 2.x must NOT trip the probe.  Regression
+        # guard: a future review that "tightens" the threshold to <=2.3
+        # would cause every healthy modern install to fail-fast.
+        import numpy
+        import torch
+
+        monkeypatch.setattr(torch, "__version__", "2.3.0")
+        monkeypatch.setattr(numpy, "__version__", "2.0.0")
+        status, _, _ = _abi_check.compute_numpy_torch_abi_status()
+        assert status == _abi_check.ABI_OK
+
+
+class TestRemediation:
+    """The shared remediation hint must carry the exact pip command."""
+
+    def test_includes_pip_install(self):
+        msg = _abi_check.format_abi_remediation("2.2.2", "2.4.4")
+        assert "pip install 'numpy<2'" in msg
+        assert "2.2.2" in msg
+        assert "2.4.4" in msg
+
+    def test_mentions_doctor(self):
+        # Operator who hit this from training should be steered toward
+        # `forgelm doctor` for the full environment diagnostic.
+        msg = _abi_check.format_abi_remediation("2.2.2", "2.4.4")
+        assert "forgelm doctor" in msg
+
+
+class TestPreflightAbortsOnBroken:
+    """Training preflight short-circuits the pipeline on a broken ABI."""
+
+    def test_abort_with_log_message_on_broken(self, caplog):
+        broken = (_abi_check.ABI_BROKEN, "2.2.2", "2.4.4")
+        with patch.object(_abi_check, "compute_numpy_torch_abi_status", return_value=broken):
+            with caplog.at_level("ERROR"), pytest.raises(SystemExit) as exc_info:
+                _training._preflight_numpy_torch_abi(json_output=False)
+        # Exit-code contract: training-pipeline preflight failure maps
+        # to EXIT_TRAINING_ERROR (= 2 in the public table).
+        assert exc_info.value.code == 2
+        # The remediation hint must be in the operator-visible log.
+        assert "pip install 'numpy<2'" in caplog.text
+
+    def test_abort_emits_structured_json_envelope(self, capsys):
+        broken = (_abi_check.ABI_BROKEN, "2.2.2", "2.4.4")
+        with patch.object(_abi_check, "compute_numpy_torch_abi_status", return_value=broken):
+            with pytest.raises(SystemExit):
+                _training._preflight_numpy_torch_abi(json_output=True)
+        captured = capsys.readouterr()
+        envelope = json.loads(captured.out)
+        # The JSON envelope is the machine-readable contract for CI/CD
+        # consumers; lock the key set so a future field rename can't
+        # silently break their parser.
+        assert envelope["success"] is False
+        assert envelope["error"] == "numpy_torch_abi_mismatch"
+        assert envelope["torch_version"] == "2.2.2"
+        assert envelope["numpy_version"] == "2.4.4"
+        assert "pip install 'numpy<2'" in envelope["remediation"]
+
+
+class TestPreflightPassesOnHealthy:
+    """The preflight is a no-op on every non-broken status."""
+
+    @pytest.mark.parametrize(
+        "status",
+        [
+            _abi_check.ABI_OK,
+            _abi_check.ABI_SKIPPED_TORCH,
+            _abi_check.ABI_SKIPPED_NUMPY,
+        ],
+    )
+    def test_no_op_for(self, status):
+        # Returning normally (no SystemExit) is the contract — training
+        # continues into the heavy-import block.
+        result = (status, "2.4.0", "1.26.4")
+        with patch.object(_abi_check, "compute_numpy_torch_abi_status", return_value=result):
+            _training._preflight_numpy_torch_abi(json_output=False)
diff --git a/tests/test_doctor.py b/tests/test_doctor.py
index 838ac131..f0410b16 100644
--- a/tests/test_doctor.py
+++ b/tests/test_doctor.py
@@ -162,9 +162,17 @@ def test_torch_22_with_numpy_1_passes(self) -> None:
             result = _check_numpy_torch_abi()
         assert result.status == "pass"
 
-    def test_no_numpy_skips_gracefully(self) -> None:
+    def test_no_numpy_skips_gracefully(self, monkeypatch) -> None:
         """numpy is an optional fast-path for the simhash backend; its
-        absence is not a doctor failure."""
+        absence is not a doctor failure.
+
+        Uses ``monkeypatch.delitem`` so the popped ``sys.modules['numpy']``
+        is auto-restored on test teardown — a plain ``sys.modules.pop``
+        leaves numpy un-cached, and a later test that re-imports torch
+        will partially re-initialise it (no ``torch._C`` binding) and
+        every downstream ``from trl import SFTConfig`` then fails with
+        ``NameError: name '_C' is not defined``.
+        """
         import builtins
 
         from forgelm.cli.subcommands import _doctor
@@ -178,18 +186,25 @@ def _block_numpy(name, *args, **kwargs):
                 raise ImportError("No module named 'numpy'")
             return original_import(name, *args, **kwargs)
 
-        # Drop any cached numpy so the patched __import__ actually fires.
-        with patch.dict("sys.modules", {"torch": fake_torch}, clear=False):
-            sys.modules.pop("numpy", None)
-            with patch.object(builtins, "__import__", _block_numpy):
-                result = _doctor._check_numpy_torch_abi()
+        # Both swaps are tracked by monkeypatch so the original modules
+        # come back automatically; nothing leaks into the next test.
+        monkeypatch.setitem(sys.modules, "torch", fake_torch)
+        monkeypatch.delitem(sys.modules, "numpy", raising=False)
+        monkeypatch.setattr(builtins, "__import__", _block_numpy)
+        result = _doctor._check_numpy_torch_abi()
         assert result.status == "pass"
         assert result.extras.get("skipped") is True
         assert result.extras.get("reason") == "numpy_missing"
 
-    def test_no_torch_skips_gracefully(self) -> None:
+    def test_no_torch_skips_gracefully(self, monkeypatch) -> None:
         """torch.cuda probe already surfaces a missing torch as fail; the
-        ABI probe must not double-report."""
+        ABI probe must not double-report.
+
+        ``monkeypatch.delitem`` keeps ``sys.modules['torch']`` restored
+        on teardown — see ``test_no_numpy_skips_gracefully`` for the
+        full pollution-cascade rationale (a stranded torch entry
+        breaks every subsequent TRL-loading test in the suite).
+        """
         import builtins
 
         from forgelm.cli.subcommands import _doctor
@@ -201,10 +216,9 @@ def _block_torch(name, *args, **kwargs):
                 raise ImportError("No module named 'torch'")
             return original_import(name, *args, **kwargs)
 
-        # Drop any cached torch so the patched __import__ actually fires.
-        sys.modules.pop("torch", None)
-        with patch.object(builtins, "__import__", _block_torch):
-            result = _doctor._check_numpy_torch_abi()
+        monkeypatch.delitem(sys.modules, "torch", raising=False)
+        monkeypatch.setattr(builtins, "__import__", _block_torch)
+        result = _doctor._check_numpy_torch_abi()
         assert result.status == "pass"
         assert result.extras.get("skipped") is True
         assert result.extras.get("reason") == "torch_missing"
diff --git a/tests/test_quickstart_compat.py b/tests/test_quickstart_compat.py
index 38144018..1d610c3f 100644
--- a/tests/test_quickstart_compat.py
+++ b/tests/test_quickstart_compat.py
@@ -97,7 +97,14 @@ def test_detect_vram_device_count_zero_returns_none(self):
         with patch.dict(sys.modules, {"torch": fake_torch}):
             assert _detect_available_vram_gb() is None
 
-    def test_detect_vram_handles_torch_missing(self):
+    def test_detect_vram_handles_torch_missing(self, monkeypatch):
+        # Why monkeypatch.delitem (and not `sys.modules.pop`):  popping
+        # torch without restoring it leaves the module re-import in a
+        # half-initialised state for every later test in the same
+        # pytest session — torch._C ends up unbound, and every
+        # downstream `from trl import SFTConfig` then explodes with
+        # `NameError: name '_C' is not defined`.  monkeypatch tracks
+        # the deletion and restores the original torch on teardown.
         real_import = builtins.__import__
 
         def fake_import(name, *args, **kwargs):
@@ -105,11 +112,9 @@ def fake_import(name, *args, **kwargs):
                 raise ImportError("no torch in this env")
             return real_import(name, *args, **kwargs)
 
-        # Drop any cached torch module so the local `import torch` re-resolves.
-        with patch.dict(sys.modules, {}, clear=False):
-            sys.modules.pop("torch", None)
-            with patch.object(builtins, "__import__", side_effect=fake_import):
-                assert _detect_available_vram_gb() is None
+        monkeypatch.delitem(sys.modules, "torch", raising=False)
+        monkeypatch.setattr(builtins, "__import__", fake_import)
+        assert _detect_available_vram_gb() is None
 
 
 # ---------------------------------------------------------------------------
diff --git a/tests/test_trainer_sft_config.py b/tests/test_trainer_sft_config.py
index 67da51df..daa2e3c1 100644
--- a/tests/test_trainer_sft_config.py
+++ b/tests/test_trainer_sft_config.py
@@ -15,12 +15,6 @@
 
 import pytest
 
-torch_available = True
-try:
-    import torch  # noqa: F401
-except ImportError:
-    torch_available = False
-
 
 def _make_sft_config(tmp_path):
     from forgelm.config import ForgeConfig
@@ -55,7 +49,6 @@ def _seed_trainer(tmp_path):
     return trainer
 
 
-@pytest.mark.skipif(not torch_available, reason="torch not installed")
 def test_sft_config_uses_max_length_on_modern_trl(tmp_path):
     """trl 0.13+ removed ``max_seq_length``; the trainer must use
     ``max_length`` instead."""
@@ -84,7 +77,6 @@ def __init__(self, *, max_length=None, packing=False, dataset_text_field=None, *
     assert captured_kwargs["dataset_text_field"] == "text"
 
 
-@pytest.mark.skipif(not torch_available, reason="torch not installed")
 def test_sft_config_uses_max_seq_length_on_legacy_trl(tmp_path):
     """trl 0.12.x: ``SFTConfig`` accepts ``max_seq_length`` only. The
     trainer must fall back to that name when the modern ``max_length``
@@ -110,7 +102,6 @@ def __init__(self, *, max_seq_length=None, packing=False, dataset_text_field=Non
     )
 
 
-@pytest.mark.skipif(not torch_available, reason="torch not installed")
 def test_sft_config_passes_packing_and_dataset_text_field(tmp_path):
     """Regression: ``packing`` and ``dataset_text_field`` must keep being
     propagated alongside the sequence-length cap."""
@@ -131,3 +122,83 @@ def __init__(self, *, max_length=None, packing=False, dataset_text_field=None, *
 
     assert captured_kwargs["packing"] is True
     assert captured_kwargs["dataset_text_field"] == "text"
+
+
+def test_sft_config_prefers_max_length_when_both_present(tmp_path):
+    """Transitional alias release: if a trl version exposes BOTH
+    ``max_length`` and ``max_seq_length`` (deprecated-alias window), the
+    trainer must prefer the modern ``max_length`` and never duplicate the
+    cap onto the legacy kwarg."""
+
+    captured_kwargs: dict = {}
+
+    class FakeBothSFTConfig:
+        def __init__(
+            self,
+            *,
+            max_length=None,
+            max_seq_length=None,
+            packing=False,
+            dataset_text_field=None,
+            **other,
+        ):
+            captured_kwargs["max_length"] = max_length
+            captured_kwargs["max_seq_length"] = max_seq_length
+            captured_kwargs["packing"] = packing
+            captured_kwargs["dataset_text_field"] = dataset_text_field
+
+    trainer = _seed_trainer(tmp_path)
+
+    with patch("trl.SFTConfig", FakeBothSFTConfig):
+        trainer._get_training_args_for_type()
+
+    assert captured_kwargs["max_length"] == 2048, (
+        "When both names are exposed, the trainer must drive the modern "
+        f"`max_length` kwarg (got: {captured_kwargs.get('max_length')!r})."
+    )
+    assert captured_kwargs["max_seq_length"] is None, (
+        "Legacy `max_seq_length` must NOT be set when `max_length` is also "
+        "available — passing both risks the *Config raising a duplicate-spec error."
+    )
+
+
+def test_sft_config_raises_when_neither_seqlen_param_exposed(tmp_path):
+    """Future-proofing: if trl renames the sequence-length kwarg yet
+    again (or hides it behind ``**kwargs``), the trainer must raise
+    rather than silently drop ``model.max_length``. Silent loss of an
+    explicit YAML setting violates the 'no silent failures' rule in
+    docs/standards/error-handling.md."""
+
+    class FakeFutureSFTConfig:
+        def __init__(self, *, packing=False, dataset_text_field=None, **other):
+            # Note: no `max_length` and no `max_seq_length` as named
+            # parameters — they would be swallowed into **other if passed.
+            pass
+
+    trainer = _seed_trainer(tmp_path)
+
+    with patch("trl.SFTConfig", FakeFutureSFTConfig):
+        with pytest.raises(ValueError, match="max_length.*max_seq_length"):
+            trainer._get_training_args_for_type()
+
+
+def test_sft_config_raises_when_seqlen_only_in_kwargs(tmp_path):
+    """``inspect.signature(SFTConfig).parameters`` only surfaces *named*
+    parameters; if a future trl release moves ``max_length`` behind a
+    catch-all ``**kwargs`` (or aliases it via a decorator), the named-
+    parameter detection will miss it and the trainer must hard-fail
+    rather than letting TRL pick its default sequence-length cap."""
+
+    class FakeKwargsOnlySFTConfig:
+        def __init__(self, **kwargs):
+            # `max_length` is only accepted via **kwargs — not as a named
+            # parameter. ``inspect.signature(...).parameters`` will
+            # expose the VAR_KEYWORD entry but neither
+            # "max_length" nor "max_seq_length" by name.
+            pass
+
+    trainer = _seed_trainer(tmp_path)
+
+    with patch("trl.SFTConfig", FakeKwargsOnlySFTConfig):
+        with pytest.raises(ValueError, match="max_length.*max_seq_length"):
+            trainer._get_training_args_for_type()

From baf5b5561d720ca69e395b0dac73f25a4089d2bd Mon Sep 17 00:00:00 2001
From: Cemil ILIK <cemililik@outlook.com>
Date: Mon, 11 May 2026 08:39:42 +0300
Subject: [PATCH 7/7] =?UTF-8?q?fix(release):=20PR=20#44=20review=20absorpt?=
 =?UTF-8?q?ion=20=E2=80=94=20round=204?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-4 cross-review of f205f42 turned up one MAJOR (marker spelling
drift in a test docstring) and a handful of MINOR/NIT items.  No
public surface change; all changes are honesty / robustness / CI guard
additions plus the documentation gap the previous round left open.

MAJOR
- `tests/test_abi_check.py` docstring now quotes the PEP 508 marker
  text actually shipped in `pyproject.toml`
  (`sys_platform == 'darwin'`) rather than the equivalent-but-
  different `platform_system == "Darwin"` form.  A future reviewer
  chasing the marker chain via the test docstring would otherwise
  conclude the marker had drifted.

MINOR / NIT
- `forgelm/trainer.py` SFT else-raise reads the trl version off
  `SFTConfig.__module__` rather than a duplicate `import trl as _trl`;
  `sys` promoted to module-top.
- `forgelm/cli/_abi_check.py::compute_numpy_torch_abi_status` short-
  circuits to ABI_OK when either `_major_minor` returns (0, 0).
  Corporate forks with non-semver tags (e.g. `foo-bar` torch) would
  otherwise hit `< (2, 3)` against any healthy numpy ≥ 2 and trigger
  a false-positive ABI_BROKEN.  Two new tests cover both sides.
- `forgelm/cli/_abi_check.py::format_abi_remediation` raises
  ValueError on a None version (precondition guard against future
  call-site drift that would emit "torch None ..." strings).
- `forgelm/cli/subcommands/_doctor.py` swaps the bare `assert
  status == ABI_OK` for a `RuntimeError` (asserts strip under
  `python -O`).  The six-symbol `_abi_check` import promoted from
  function-local to module-top.
- New CI guard `tools/check_no_unguarded_sys_modules_pop.py` fails
  on any `sys.modules.pop("torch"|"numpy"|"trl"|"transformers"|
  "peft"|"datasets")` or `del sys.modules[...]` without
  `monkeypatch.delitem` — the round-3 fix pattern.  Wired into both
  the self-review gauntlet (`CLAUDE.md`, now 10 checks) and
  `.github/workflows/ci.yml`.
- `pytest-randomly>=3.15.0,<4.0.0` added to the `[dev]` extra so
  order-dependent regressions surface in CI rather than waiting for
  a Python micro-bump to shuffle collection.  Suite re-verified
  under shuffled order (1651 passed, 14 skipped, 0 failed).
- Training preflight's 5-key JSON envelope (`success`, `error`,
  `torch_version`, `numpy_version`, `remediation`) now documented in
  `docs/usermanuals/{en,tr}/reference/json-output.md` so CI consumers
  can branch on the stable `"error": "numpy_torch_abi_mismatch"` token.
- One leftover `(Faz 12)` in the v0.5.2 CHANGELOG entry rewritten to
  `(Phase 12)` (English-only-in-CHANGELOG cleanup, pre-existing drift).

Verified: 1651 passed, 14 skipped, 0 failed under pytest-randomly
shuffled order; ruff format + ruff check + all ten doc guards
(anchor-resolution, no-analysis-refs, bilingual-parity, CLI help,
wizard-defaults, no-unguarded-sys-modules-pop, …) green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ci.yml                     |  11 ++
 CHANGELOG.md                                 |  54 +++++++-
 CLAUDE.md                                    |   9 +-
 docs/usermanuals/en/reference/json-output.md |  24 ++++
 docs/usermanuals/tr/reference/json-output.md |  24 ++++
 forgelm/cli/_abi_check.py                    |  28 ++++
 forgelm/cli/subcommands/_doctor.py           |  25 ++--
 forgelm/trainer.py                           |  12 +-
 pyproject.toml                               |   6 +
 tests/test_abi_check.py                      |  40 +++++-
 tools/check_no_unguarded_sys_modules_pop.py  | 131 +++++++++++++++++++
 11 files changed, 340 insertions(+), 24 deletions(-)
 create mode 100644 tools/check_no_unguarded_sys_modules_pop.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6e33adfc..bf070e0a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -228,6 +228,17 @@ jobs:
         # for local feedback during a docs PR.
         run: python3 tools/check_cli_help_consistency.py --strict
 
+      - name: Unguarded sys.modules.pop guard
+        # v0.5.7 round-4 absorption: the v0.5.7 round-3 review traced
+        # 35 spurious full-suite failures to three test sites that
+        # popped torch / numpy from sys.modules without restoring
+        # them, half-loading torch._C for every later test in the
+        # pytest session.  This guard fails CI on any new
+        # ``sys.modules.pop("<heavy-module>")`` /
+        # ``del sys.modules["<heavy-module>"]`` site, steering authors
+        # to ``monkeypatch.delitem`` (auto-restores on teardown).
+        run: python3 tools/check_no_unguarded_sys_modules_pop.py
+
       - name: License check
         run: |
           test -f LICENSE || (echo "LICENSE file missing" && exit 1)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f75476d0..6a4d5500 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,9 @@ All notable changes to ForgeLM are documented here.
 
 ## [Unreleased]
 
-Review-absorption round 3 follow-up to v0.5.7. No public surface change,
-but training-pipeline UX, doctor robustness, and roadmap hygiene
-improve.
+Review-absorption rounds 3 + 4 follow-up to v0.5.7. No public surface
+change, but training-pipeline UX, doctor robustness, and test-isolation
+guarantees improve.
 
 ### Added
 
@@ -20,7 +20,23 @@ improve.
   remediation command (`pip install 'numpy<2'`) instead of a cryptic
   `NameError: name '_C' is not defined` from torch mid-training. The
   PEP 508 marker in `pyproject.toml` remains the primary fix for
-  fresh installs; the preflight is the second line of defense.
+  fresh installs; the preflight is the second line of defense. The
+  preflight's JSON envelope is now documented in
+  [`docs/usermanuals/{en,tr}/reference/json-output.md`](docs/usermanuals/en/reference/json-output.md)
+  so CI consumers can branch on the stable `"error":
+  "numpy_torch_abi_mismatch"` token.
+- **`tools/check_no_unguarded_sys_modules_pop.py`** — new CI guard
+  fails on `sys.modules.pop("torch"|"numpy"|"trl"|…)` or
+  `del sys.modules["…"]` without `monkeypatch.delitem` for tracked
+  teardown. Wired into the self-review gauntlet
+  ([`CLAUDE.md`](CLAUDE.md)) and `.github/workflows/ci.yml`. Round-3
+  traced 35 spurious full-suite failures to this pattern; the guard
+  makes the regression impossible to silently re-introduce.
+- **`pytest-randomly` added to `[dev]` extra.** Shuffles test order
+  per session so order-dependent bugs (the exact failure mode round-3
+  fixed) surface in CI instead of waiting for a Python micro-bump or
+  runner change. Reproduce a specific shuffle with
+  `pytest --randomly-seed=<n>`.
 
 ### Fixed
 
@@ -29,7 +45,9 @@ improve.
   `max_length` nor `max_seq_length` is exposed on `SFTConfig`. Silent
   drop of an explicit `model.max_length` YAML setting would violate
   `docs/standards/error-handling.md` "no silent failures" — error
-  message lists the actually-detected parameters for forensics.
+  message lists the actually-detected parameters for forensics. The
+  trl version is probed off `SFTConfig.__module__` rather than a
+  duplicate `import trl` (round-4 cleanup).
 - **`tests/test_doctor.py` + `tests/test_quickstart_compat.py`** —
   three pre-existing tests that popped `sys.modules['torch']` /
   `sys.modules['numpy']` without restoring them now use
@@ -48,7 +66,29 @@ improve.
   …)`-based suppression would require fd-level redirection (which is
   unsafe in a long-lived CLI process). Module-level `re` / `warnings`
   imports promoted from function-local since the shared helper now
-  owns them.
+  owns them. The exhaustive-enum guard at the end of the function now
+  raises `RuntimeError` instead of `assert` so `python -O` doesn't
+  strip the check.
+- **`forgelm/cli/_abi_check.py::compute_numpy_torch_abi_status`** —
+  fail-safe short-circuit added for `(0, 0)` version-parse fallback
+  on either side. A corporate fork with a non-semver torch tag (e.g.
+  `foo-bar`) would otherwise have its `_major_minor` collapse to
+  `(0, 0)`, trip `< (2, 3)`, and trigger a false-positive
+  `ABI_BROKEN` against any healthy numpy ≥ 2. Now: if either parses
+  to `(0, 0)`, treat as `ABI_OK` ("version unknown, do not
+  classify"). `format_abi_remediation` also gained an explicit
+  precondition check so a future call-site drift can't silently
+  emit `"torch None …"` strings.
+
+### Internal
+
+- Test docstring in [`tests/test_abi_check.py`](tests/test_abi_check.py)
+  now quotes the actual PEP 508 marker from `pyproject.toml`
+  (`sys_platform == 'darwin'`) instead of the equivalent-but-different
+  `platform_system == "Darwin"` form, so future reviewers chasing the
+  marker chain don't conclude it has drifted.
+- One leftover `(Faz 12)` in the v0.5.2 CHANGELOG entry rewritten to
+  `(Phase 12)` — English-only-in-code-and-CHANGELOG cleanup.
 
 ## [0.5.7] — 2026-05-10
 
@@ -1217,7 +1257,7 @@ Second-round review of the Phase 12 commit surfaced 22 findings spanning correct
 - **`_row_quality_flags` typed `Optional[str]`** — The function already accepted `None` at runtime; the signature now reflects that and the test's `# type: ignore[arg-type]` suppression is gone.
 - **Cognitive-complexity refactors** — `_row_quality_flags` (CCN 22 → ≤ 10 via per-check helpers `_check_low_alpha_ratio` / `_check_low_punct_endings` / `_check_abnormal_mean_word_length` / `_check_short_paragraphs` / `_check_repeated_lines`); `find_near_duplicates_minhash` (CCN 21 → ≤ 10 via `_build_minhash_lsh` + `_emit_minhash_pair`); `audit_dataset` (CCN 21 → ≤ 12 via `_fold_outcome_into_summary` + `_build_quality_summary` + `_build_near_duplicate_summary`).
 - **Regex / lint code-smells** — `[A-Za-z0-9_]` → `\w` in the GitHub PAT pattern; `[ ]{0,3}` → ` {0,3}` (single-char class collapsed) in markdown patterns; `\s` → `[ \t]` in heading pattern (mitigates the polynomial-backtracking concern SonarCloud flagged); duplicate `"chunk_tokens must be positive"` / `"max_chunk_size must be positive"` literal strings extracted to module constants `_CHUNK_TOKENS_POSITIVE_MSG` / `_CHUNK_SIZE_POSITIVE_MSG`; `_MARKDOWN_OVERLAP_UNSUPPORTED_MSG` constant for the new validator; comprehension `["| " + " | ".join(c for c in row) + " |"]` simplified to `["| " + " | ".join(row) + " |"]`.
-- **Documentation parity** — `docs/guides/data_audit.md` quality-filter bullet list and JSON example now include `repeated_lines` and a note about code-fence stripping. `docs/guides/ingestion-tr.md` mirrors the EN guide's chunking-strategies table (markdown row added) and gains a new "secrets/credential masking (Faz 12)" section. `CHANGELOG`'s Phase 12 entry no longer overstates the `[ingestion-secrets]` extra: the regex set is the sole detection backend in v0.5.2, and the `detect-secrets` package is reserved for a follow-up release. `README` separates "From PyPI" and "From a local clone" install blocks so copy-paste users don't hit `-e .` confusion.
+- **Documentation parity** — `docs/guides/data_audit.md` quality-filter bullet list and JSON example now include `repeated_lines` and a note about code-fence stripping. `docs/guides/ingestion-tr.md` mirrors the EN guide's chunking-strategies table (markdown row added) and gains a new "secrets/credential masking (Phase 12)" section. `CHANGELOG`'s Phase 12 entry no longer overstates the `[ingestion-secrets]` extra: the regex set is the sole detection backend in v0.5.2, and the `detect-secrets` package is reserved for a follow-up release. `README` separates "From PyPI" and "From a local clone" install blocks so copy-paste users don't hit `-e .` confusion.
 - **Test fixtures fragmented** — All hardcoded credential / JWT literals in `tests/test_data_audit_phase12.py`, `tests/test_ingestion_phase12.py`, and `tests/test_phase12_review_fixes.py` now built at runtime from inert string fragments (e.g. `"AKIA" + "IOSFODNN7" + "EXAMPLE"`). The regex still has to match the canonical shape, but no full literal credential lives in the source tree — silences gitleaks / trufflehog scans of the repo without changing behaviour.
 - **5 new round-2 regression tests** (`tests/test_phase12_review_fixes.py`) — `TestTildeFenceRecognised` (~~~-fenced code blocks block heading splits), `TestPrivateKeyFullBlock` (full PEM body redaction), `TestMarkdownOverlapValidation` (rejection on explicit non-zero overlap; default-overlap pass-through), `TestMinHashDistinctSemantic` (unique-sketches semantic).
 - **Notebook ruff format** — `notebooks/post_training_workflow.ipynb` reformatted to satisfy `ruff format --check` in CI; `notebooks/data_curation.ipynb` install line pinned to `forgelm[ingestion]==0.5.2` rather than the moving `main` branch.
diff --git a/CLAUDE.md b/CLAUDE.md
index 48fa566d..61f86fea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -154,10 +154,11 @@ Default workflow for a non-trivial change:
      python3 tools/check_anchor_resolution.py --strict && \
      python3 tools/check_cli_help_consistency.py --strict && \
      python3 tools/check_wizard_defaults_sync.py && \
-     python3 tools/check_no_analysis_refs.py
+     python3 tools/check_no_analysis_refs.py && \
+     python3 tools/check_no_unguarded_sys_modules_pop.py
    ```
 
-   All nine must pass. The first four are the historical gauntlet;
+   All ten must pass. The first four are the historical gauntlet;
    the three doc guards (Wave 3 / Wave 4 / Wave 5 additions) catch
    bilingual structural drift, broken markdown anchors, and CLI ↔ docs
    help-text drift before the PR opens. The wizard-defaults guard
@@ -166,6 +167,10 @@ Default workflow for a non-trivial change:
    (review-cycle 5) keeps the public tree from citing gitignored
    `docs/marketing/` or `docs/analysis/` paths — see
    `docs/standards/documentation.md` "Working-memory directories".
+   The unguarded-`sys.modules`-pop guard (v0.5.7 round-4) flags any
+   `sys.modules.pop("torch"|"numpy"|"trl"|…)` without
+   `monkeypatch.delitem` — the v0.5.7 round-3 review traced 35
+   spurious full-suite failures to that exact pattern.
 
 ## Etiquette when communicating with the user
 
diff --git a/docs/usermanuals/en/reference/json-output.md b/docs/usermanuals/en/reference/json-output.md
index 351afb83..eb29f5e3 100644
--- a/docs/usermanuals/en/reference/json-output.md
+++ b/docs/usermanuals/en/reference/json-output.md
@@ -49,6 +49,30 @@ Environment check. See [Doctor command](#/getting-started/first-run).
 
 **Exit code mapping:** `0` = all probes `pass` or `warn`; `1` = at least one `fail`; `2` = at least one `crashed` (probe raised; subsequent probes still ran).
 
+## `forgelm` (training) — preflight abort envelope
+
+The training pipeline (`forgelm --config <yaml> --output-format json`) runs a torch/NumPy ABI sanity check before importing the heavy stack. On a healthy environment the preflight is silent and training proceeds normally; on the known Intel Mac NumPy 2 / torch 2.2 mismatch the preflight aborts with the following envelope on **stdout** and exit code `2`:
+
+```json
+{
+  "success": false,
+  "error": "numpy_torch_abi_mismatch",
+  "torch_version": "2.2.2",
+  "numpy_version": "2.4.4",
+  "remediation": "torch 2.2.2 (compiled against NumPy 1.x) is paired with numpy 2.4.4. ... Fix with: pip install 'numpy<2' ..."
+}
+```
+
+| Key | Type | Notes |
+|---|---|---|
+| `success` | bool | Always `false` on this path; healthy preflight emits nothing and the pipeline continues. |
+| `error` | str | Stable token `"numpy_torch_abi_mismatch"`. CI consumers can branch on this exact value. |
+| `torch_version` | str | The version string `torch.__version__` reported at preflight time. |
+| `numpy_version` | str | The version string `numpy.__version__` reported at preflight time. |
+| `remediation` | str | Human-readable fix instructions ending with the exact `pip install 'numpy<2'` command. Identical text to the `forgelm doctor` `numpy.torch_abi` probe's `detail` field — same single source of truth. |
+
+**Exit code mapping:** preflight abort exits `2` (`EXIT_TRAINING_ERROR`, the runtime-error class). The same `forgelm doctor` `numpy.torch_abi` probe would have surfaced this as `status: "fail"` ahead of time; the preflight is the second line of defense for operators who skipped `doctor` and ran training directly.
+
 ## `forgelm approvals --pending`
 
 Lists pending Article 14 approval requests, newest-first.
diff --git a/docs/usermanuals/tr/reference/json-output.md b/docs/usermanuals/tr/reference/json-output.md
index face543a..b952b37c 100644
--- a/docs/usermanuals/tr/reference/json-output.md
+++ b/docs/usermanuals/tr/reference/json-output.md
@@ -49,6 +49,30 @@ Ortam kontrolü. Bkz. [Doctor komutu](#/getting-started/first-run).
 
 **Exit code mapping:** `0` = tüm probe'lar `pass` veya `warn`; `1` = en az bir `fail`; `2` = en az bir `crashed` (probe raise etti; sonraki probe'lar yine de çalıştı).
 
+## `forgelm` (eğitim) — preflight abort envelope
+
+Eğitim pipeline'ı (`forgelm --config <yaml> --output-format json`) ağır stack'i import etmeden önce bir torch/NumPy ABI sanity check çalıştırır. Sağlıklı bir ortamda preflight sessizdir ve eğitim normal şekilde devam eder; bilinen Intel Mac NumPy 2 / torch 2.2 mismatch'inde preflight şu envelope ile **stdout**'a basıp exit code `2` ile abort eder:
+
+```json
+{
+  "success": false,
+  "error": "numpy_torch_abi_mismatch",
+  "torch_version": "2.2.2",
+  "numpy_version": "2.4.4",
+  "remediation": "torch 2.2.2 (compiled against NumPy 1.x) is paired with numpy 2.4.4. ... Fix with: pip install 'numpy<2' ..."
+}
+```
+
+| Anahtar | Tip | Not |
+|---|---|---|
+| `success` | bool | Bu kod yolunda her zaman `false`; sağlıklı preflight hiçbir şey emit etmez ve pipeline devam eder. |
+| `error` | str | Stabil token `"numpy_torch_abi_mismatch"`. CI tüketicileri tam bu değer üzerinden branch'leyebilir. |
+| `torch_version` | str | Preflight anında `torch.__version__`'un raporladığı versiyon string'i. |
+| `numpy_version` | str | Preflight anında `numpy.__version__`'un raporladığı versiyon string'i. |
+| `remediation` | str | İnsan-okunabilir fix talimatı, tam `pip install 'numpy<2'` komutuyla biten. `forgelm doctor` `numpy.torch_abi` probe'unun `detail` alanıyla bire bir aynı metin — tek kaynak. |
+
+**Exit code mapping:** preflight abort, `2` (`EXIT_TRAINING_ERROR`, runtime-error sınıfı) ile çıkar. Aynı `forgelm doctor` `numpy.torch_abi` probe'u önceden `status: "fail"` olarak yüzeye çıkarırdı; preflight, `doctor`'ı skip edip eğitimi doğrudan çalıştıran operatörler için ikinci savunma hattıdır.
+
 ## `forgelm approvals --pending`
 
 Bekleyen Madde 14 onay isteklerini en yeniden başa doğru listeler.
diff --git a/forgelm/cli/_abi_check.py b/forgelm/cli/_abi_check.py
index d004caaa..48be7825 100644
--- a/forgelm/cli/_abi_check.py
+++ b/forgelm/cli/_abi_check.py
@@ -43,6 +43,14 @@ def _major_minor(version: str) -> Tuple[int, int]:
     Returns ``(0, 0)`` on a totally unparseable string — callers that
     care about the forensic distinction (the doctor probe) wrap with
     their own debug-logging call.
+
+    Note: a (0, 0) return must be treated as "version unknown, do not
+    classify" by callers; the threshold check in
+    :func:`compute_numpy_torch_abi_status` short-circuits to
+    :data:`ABI_OK` when either side fails to parse to avoid a false-
+    positive ``ABI_BROKEN`` on corporate forks with non-semver tags
+    (a torch fork tagged ``foo-bar`` would otherwise parse to (0, 0)
+    < (2, 3) and unconditionally trip the gate).
     """
     match = re.match(r"^(\d+)\.(\d+)", version)
     if not match:
@@ -81,6 +89,13 @@ def compute_numpy_torch_abi_status() -> Tuple[str, Optional[str], Optional[str]]
 
     torch_mm = _major_minor(torch.__version__)
     numpy_mm = _major_minor(numpy.__version__)
+    # Fail-safe: if either version string didn't parse (corporate forks,
+    # non-semver tags), don't classify.  The mismatch window
+    # ``torch_mm < (2, 3) AND numpy_mm >= (2, 0)`` is only meaningful
+    # when both tuples are real; a (0, 0) fallback comparing as
+    # "< (2, 3) True" would trip the gate on any unparseable build.
+    if torch_mm == (0, 0) or numpy_mm == (0, 0):
+        return (ABI_OK, torch.__version__, numpy.__version__)
     # The known incompatibility window: torch < 2.3 was built against
     # NumPy 1.x and silently degrades when paired with NumPy 2.x.
     if torch_mm < (2, 3) and numpy_mm >= (2, 0):
@@ -91,10 +106,23 @@ def compute_numpy_torch_abi_status() -> Tuple[str, Optional[str], Optional[str]]
 def format_abi_remediation(torch_version: str, numpy_version: str) -> str:
     """Human-readable remediation hint for an incompatible ABI.
 
+    Both version strings are required to be populated — callers are
+    expected to invoke this only after observing :data:`ABI_BROKEN`,
+    which guarantees both versions came back non-``None`` from
+    :func:`compute_numpy_torch_abi_status`.  An assertion guards
+    against future call sites that drift from this contract.
+
     Kept identical to the doctor probe's ``detail`` line so the
     operator sees the same fix instructions whether they hit the
     training preflight or ran ``forgelm doctor`` first.
     """
+    if torch_version is None or numpy_version is None:
+        raise ValueError(
+            "format_abi_remediation requires both torch_version and numpy_version; "
+            f"got torch_version={torch_version!r}, numpy_version={numpy_version!r}. "
+            "This helper is only meaningful after an ABI_BROKEN verdict — check the "
+            "call site for a misclassification."
+        )
     return (
         f"torch {torch_version} (compiled against NumPy 1.x) is paired with "
         f"numpy {numpy_version}. This triggers an `_ARRAY_API not found` "
diff --git a/forgelm/cli/subcommands/_doctor.py b/forgelm/cli/subcommands/_doctor.py
index 63511c03..299e1289 100644
--- a/forgelm/cli/subcommands/_doctor.py
+++ b/forgelm/cli/subcommands/_doctor.py
@@ -47,6 +47,14 @@
 from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Tuple
 
+from .._abi_check import (
+    ABI_BROKEN,
+    ABI_OK,
+    ABI_SKIPPED_NUMPY,
+    ABI_SKIPPED_TORCH,
+    compute_numpy_torch_abi_status,
+    format_abi_remediation,
+)
 from .._exit_codes import EXIT_CONFIG_ERROR, EXIT_SUCCESS, EXIT_TRAINING_ERROR
 from .._logging import logger
 
@@ -225,15 +233,6 @@ def _check_numpy_torch_abi() -> _CheckResult:
     full stderr-suppression caveat (torch's C++ ``_ARRAY_API not
     found`` line is outside Python's warnings machinery).
     """
-    from .._abi_check import (
-        ABI_BROKEN,
-        ABI_OK,
-        ABI_SKIPPED_NUMPY,
-        ABI_SKIPPED_TORCH,
-        compute_numpy_torch_abi_status,
-        format_abi_remediation,
-    )
-
     status, torch_version, numpy_version = compute_numpy_torch_abi_status()
 
     if status == ABI_SKIPPED_TORCH:
@@ -270,7 +269,13 @@ def _check_numpy_torch_abi() -> _CheckResult:
             extras=extras,
         )
 
-    assert status == ABI_OK, f"unexpected ABI status {status!r}"
+    if status != ABI_OK:
+        # The four ABI_* sentinels are exhaustive today; a fifth would
+        # have to land in ``_abi_check.py`` and be added to the dispatch
+        # above.  Raise (don't ``assert``) so a future drift still
+        # surfaces under ``python -O`` — bare asserts are stripped at
+        # optimization level 1.
+        raise RuntimeError(f"unexpected ABI status {status!r} from compute_numpy_torch_abi_status()")
     return _CheckResult(
         name=_PROBE_NUMPY_TORCH_ABI,
         status=_STATUS_PASS,
diff --git a/forgelm/trainer.py b/forgelm/trainer.py
index 544a5cb8..e614f07f 100644
--- a/forgelm/trainer.py
+++ b/forgelm/trainer.py
@@ -4,6 +4,7 @@
 import os
 import re
 import shutil
+import sys
 from typing import Any, Dict, Optional
 
 # NOTE: Heavy ML imports (torch, transformers.EarlyStoppingCallback, trl.SFTConfig/SFTTrainer)
@@ -445,10 +446,15 @@ def _get_training_args_for_type(self):
             elif "max_seq_length" in sft_params:
                 kwargs["max_seq_length"] = self.config.model.max_length
             else:
-                import trl as _trl
-
+                # Probe the trl version off the already-loaded module rather
+                # than re-importing — ``from trl import SFTConfig`` above
+                # left trl in ``sys.modules`` and ``SFTConfig.__module__``
+                # gives us the canonical package name without a redundant
+                # ``import trl`` line.
+                trl_module = sys.modules.get(SFTConfig.__module__.split(".", 1)[0])
+                trl_version = getattr(trl_module, "__version__", "?")
                 raise ValueError(
-                    f"SFTConfig in trl {getattr(_trl, '__version__', '?')} exposes neither "
+                    f"SFTConfig in trl {trl_version} exposes neither "
                     "`max_length` nor `max_seq_length` as a named parameter; cannot apply "
                     f"the sequence-length cap from config (model.max_length={self.config.model.max_length}). "
                     f"Detected parameters: {sorted(sft_params)}. Pin trl to a known-compatible "
diff --git a/pyproject.toml b/pyproject.toml
index d2f570cb..1aa4cde7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -144,6 +144,12 @@ chat = [
 dev = [
   "pytest>=8.0.0",
   "pytest-cov>=5.0.0",
+  # pytest-randomly shuffles test order per session so order-dependent
+  # bugs (e.g. the v0.5.7 round-3 sys.modules.pop pollution cascade)
+  # surface in CI instead of waiting for a Python micro-bump or runner
+  # change to flip collection order.  Run locally via
+  # ``pytest --randomly-seed=<n>`` to reproduce a failure.
+  "pytest-randomly>=3.15.0,<4.0.0",
   "ruff>=0.4.0",
 ]
 
diff --git a/tests/test_abi_check.py b/tests/test_abi_check.py
index d511fe23..e14e00bc 100644
--- a/tests/test_abi_check.py
+++ b/tests/test_abi_check.py
@@ -9,8 +9,8 @@
   ``_preflight_numpy_torch_abi``) — covered here.
 
 The preflight is the second line of defense after the PEP 508 marker in
-``pyproject.toml`` (``numpy<2; platform_system == "Darwin" and
-platform_machine == "x86_64"``).  The marker auto-fixes fresh installs
+``pyproject.toml`` (``numpy<2; sys_platform == 'darwin' and
+platform_machine == 'x86_64'``).  The marker auto-fixes fresh installs
 and ``pip install -U`` re-resolves; the preflight catches residual
 drift (out-of-band ``pip install numpy>=2`` after a working install).
 
@@ -108,6 +108,30 @@ def test_boundary_torch_23_with_numpy_2(self, monkeypatch):
         status, _, _ = _abi_check.compute_numpy_torch_abi_status()
         assert status == _abi_check.ABI_OK
 
+    def test_unparseable_torch_version_does_not_false_positive(self, monkeypatch):
+        # Corporate fork with a non-semver torch tag would otherwise
+        # parse to (0, 0), which compares as `< (2, 3)` and would
+        # trip ABI_BROKEN against any healthy numpy >= 2.  Round-4
+        # fail-safe: an unparseable version on either side maps to
+        # ABI_OK ("version unknown, do not classify") instead.
+        import numpy
+        import torch
+
+        monkeypatch.setattr(torch, "__version__", "foo-bar-not-semver")
+        monkeypatch.setattr(numpy, "__version__", "2.0.0")
+        status, _, _ = _abi_check.compute_numpy_torch_abi_status()
+        assert status == _abi_check.ABI_OK
+
+    def test_unparseable_numpy_version_does_not_false_positive(self, monkeypatch):
+        # Symmetric fail-safe on the numpy side.
+        import numpy
+        import torch
+
+        monkeypatch.setattr(torch, "__version__", "2.2.0")
+        monkeypatch.setattr(numpy, "__version__", "weird-vendor-tag")
+        status, _, _ = _abi_check.compute_numpy_torch_abi_status()
+        assert status == _abi_check.ABI_OK
+
 
 class TestRemediation:
     """The shared remediation hint must carry the exact pip command."""
@@ -124,6 +148,18 @@ def test_mentions_doctor(self):
         msg = _abi_check.format_abi_remediation("2.2.2", "2.4.4")
         assert "forgelm doctor" in msg
 
+    def test_none_version_raises_explicit_value_error(self):
+        # Precondition guard: the helper is only meaningful after an
+        # ABI_BROKEN verdict, which guarantees both versions are
+        # populated.  A None slipping through (e.g. a future caller
+        # mis-classifying ABI_SKIPPED_NUMPY) would otherwise produce a
+        # confusing "torch None ..." string in the operator-visible
+        # error path.
+        with pytest.raises(ValueError, match="format_abi_remediation requires"):
+            _abi_check.format_abi_remediation(None, "2.4.4")
+        with pytest.raises(ValueError, match="format_abi_remediation requires"):
+            _abi_check.format_abi_remediation("2.2.2", None)
+
 
 class TestPreflightAbortsOnBroken:
     """Training preflight short-circuits the pipeline on a broken ABI."""
diff --git a/tools/check_no_unguarded_sys_modules_pop.py b/tools/check_no_unguarded_sys_modules_pop.py
new file mode 100644
index 00000000..26fa2bc2
--- /dev/null
+++ b/tools/check_no_unguarded_sys_modules_pop.py
@@ -0,0 +1,131 @@
+"""CI guard — bare ``sys.modules.pop("torch"/"numpy"/...)`` is forbidden.
+
+Round-3 of the v0.5.7 review absorption traced 35 spurious full-suite test
+failures to three call sites that popped ``torch`` or ``numpy`` from
+``sys.modules`` without restoring them — the next ``import torch`` then
+half-loaded the module (``torch._C`` never re-bound) and every downstream
+``from trl import SFTConfig`` failed with ``NameError: name '_C' is not
+defined``.  The fix swapped all three for ``monkeypatch.delitem``, which
+auto-restores on test teardown.
+
+This guard exists so a future test author who didn't read those inline
+comments can't silently re-introduce the bug.  Failure modes the guard
+flags:
+
+- ``sys.modules.pop("torch")`` / ``sys.modules.pop("numpy")``
+- ``del sys.modules["torch"]`` / ``del sys.modules["numpy"]``
+- The same for ``trl``, ``transformers`` — heavyweight ML modules that
+  load C extensions and degrade similarly under partial re-import.
+
+What the guard does NOT flag:
+
+- ``monkeypatch.delitem(sys.modules, "torch")`` — the sanctioned pattern.
+- ``patch.dict(sys.modules, {"torch": fake_torch})`` — ``patch.dict``
+  restores on context exit; safe.
+- Production ``sys.modules`` writes (none today; production code never
+  needs to evict a module).
+
+Run via::
+
+    python3 tools/check_no_unguarded_sys_modules_pop.py
+
+Exit codes (per ``tools/`` contract — NOT the public 0/1/2/3/4 surface):
+
+- ``0`` — clean
+- ``1`` — at least one unguarded site found
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+# Modules whose unguarded eviction has been shown to corrupt the pytest
+# session.  Add to this set only when a new offender is empirically
+# observed — keeping the list narrow avoids flagging fixture code that
+# legitimately evicts a Python-pure helper module.
+_GUARDED_MODULES = ("torch", "numpy", "trl", "transformers", "peft", "datasets")
+
+_PATTERNS = [
+    # ``sys.modules.pop("torch", ...)`` / single quotes / no default
+    re.compile(r"""sys\.modules\.pop\s*\(\s*['"](""" + "|".join(_GUARDED_MODULES) + r""")['"]"""),
+    # ``del sys.modules["torch"]`` / single quotes
+    re.compile(r"""del\s+sys\.modules\s*\[\s*['"](""" + "|".join(_GUARDED_MODULES) + r""")['"]\s*\]"""),
+    # ``sys.modules["torch"] = None`` — equivalent corruption
+    re.compile(r"""sys\.modules\s*\[\s*['"](""" + "|".join(_GUARDED_MODULES) + r""")['"]\s*\]\s*=\s*None"""),
+]
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _scan_file(path: Path) -> List[Tuple[int, str, str]]:
+    """Return ``(line_number, matched_module, raw_line)`` for every hit."""
+    findings: List[Tuple[int, str, str]] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return findings
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        # Allow the guard itself + the comment-only references in tests
+        # that document WHY they don't use the pattern.  We detect those
+        # by looking for the sanctioned ``monkeypatch.delitem`` call
+        # within the same line (the canonical fix) or by scoping to
+        # non-comment / non-docstring lines via a coarse heuristic:
+        # skip lines that lead with ``#`` after stripping whitespace.
+        stripped = line.lstrip()
+        if stripped.startswith("#"):
+            continue
+        for pattern in _PATTERNS:
+            match = pattern.search(line)
+            if match:
+                findings.append((line_no, match.group(1), line.rstrip()))
+    return findings
+
+
+def _candidate_files() -> List[Path]:
+    """Every ``.py`` file under tests/ + forgelm/, plus self-exclusion."""
+    roots = [_REPO_ROOT / "tests", _REPO_ROOT / "forgelm"]
+    files: List[Path] = []
+    self_path = Path(__file__).resolve()
+    for root in roots:
+        if not root.exists():
+            continue
+        for path in root.rglob("*.py"):
+            if path.resolve() == self_path:
+                continue
+            files.append(path)
+    return files
+
+
+def main() -> int:
+    all_findings: List[Tuple[Path, int, str, str]] = []
+    for path in _candidate_files():
+        for line_no, mod, raw in _scan_file(path):
+            all_findings.append((path, line_no, mod, raw))
+
+    if not all_findings:
+        scanned = len(_candidate_files())
+        print(
+            f"OK: {scanned} Python file(s) under tests/ + forgelm/ carry no unguarded "
+            f"sys.modules eviction for any of: {', '.join(_GUARDED_MODULES)}."
+        )
+        return 0
+
+    print("FAIL: unguarded sys.modules eviction found — use monkeypatch.delitem instead.\n")
+    for path, line_no, mod, raw in all_findings:
+        rel = path.relative_to(_REPO_ROOT)
+        print(f"  {rel}:{line_no}  (module: {mod})")
+        print(f"    > {raw.strip()}")
+    print(
+        "\nThe v0.5.7 round-3 review absorption traced 35 unrelated test failures to "
+        "this exact pattern (torch._C unbound after partial re-import). Replace with:\n"
+        '    monkeypatch.delitem(sys.modules, "<module>", raising=False)\n'
+        "which auto-restores on test teardown."
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())