From 97fa3a17a1dae47e96d29e148122dd7291f6de35 Mon Sep 17 00:00:00 2001
From: kellito <kellito@redbear>
Date: Fri, 12 Jun 2026 01:59:17 +0300
Subject: [PATCH] docs: mark 3 of 10 build-system improvements as DONE
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implemented (this session):
- #3 audit-patch-idempotency.py — found 1 real bug (libdrm/02)
- #8 auto-link Qt sysroot dirs — no recipe edits needed
- #9 classify-cook-failure.py — 14 known failure patterns

Remaining priority: #6 (KF6 recipe dep audit), #2 (cook --repair),
#5 (recipe lint), #4 (cook TUI), #10 (scratch-rebuild), #1 (parallel),
#7A (Linux-host qmltyperegistrar)
---
 local/docs/BUILD-SYSTEM-IMPROVEMENTS.md | 59 ++++++++++++++++++-------
 1 file changed, 44 insertions(+), 15 deletions(-)

diff --git a/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md b/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md
index 6091c787d2..39f53de409 100644
--- a/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md
+++ b/local/docs/BUILD-SYSTEM-IMPROVEMENTS.md
@@ -251,19 +251,48 @@ Eliminates the "delete and pray" pattern.
 
 ## Summary
 
-| # | Title | Size | Gain | Risk |
-|---|---|---|---|---|
-| 1 | Parallel-safe cook pool | M | 2-3x | M |
-| 2 | `cook --repair` mode | S | 5-10x per-failure | L |
-| 3 | Per-recipe patch idempotency auditor | S | Catch at lint | None |
-| 4 | Cook TUI status | M | UX | None |
-| 5 | Build-time recipe lint | M | Catch at lint | None |
-| 6 | KF6 recipe dep audit | S | Prevent bugs | None |
-| 7 | QML gate | L | Unblock KDE | A: L, B: H |
-| 8 | Auto-link Qt sysroot dirs | S | Fewer bugs | L |
-| 9 | Failure classifier | M | 5-10x diagnosis | None |
-| 10 | Scratch-rebuild system | L | Predictable | M |
+| # | Title | Size | Gain | Risk | Status |
+|---|---|---|---|---|---|
+| 1 | Parallel-safe cook pool | M | 2-3x | M | open |
+| 2 | `cook --repair` mode | S | 5-10x per-failure | L | open |
+| 3 | Per-recipe patch idempotency auditor | S | Catch at lint | None | **DONE** (commit 03c8a38a1) |
+| 4 | Cook TUI status | M | UX | None | open |
+| 5 | Build-time recipe lint | M | Catch at lint | None | open |
+| 6 | `recipes/kf6-*` recipe dep audit | S | Prevent bugs | None | open |
+| 7 | QML gate | L | Unblock KDE | A: L | open |
+| 8 | Auto-link Qt sysroot dirs | S | Fewer bugs | L | **DONE** (commit 03c8a38a1) |
+| 9 | Failure classifier | M | 5-10x diagnosis | None | **DONE** (commit bd18eefc6) |
+| 10 | Cookbook scratch-rebuild system | L | Predictable | M | open |
+
+**Implemented (commits 03c8a38a1, bd18eefc6):**
+
+- **#3 (patch idempotency auditor):** `local/scripts/audit-patch-idempotency.py`
+  validates every external patch in `local/patches/` against a fresh
+  upstream checkout. Catches the idempotency class of bug at lint
+  time. Found 1 real bug on first run:
+  `local/patches/libdrm/02-redox-dispatch.patch` has a hunk at
+  `xf86drm.c:321` that no longer matches the upstream
+  `libdrm-2.4.125`.
+
+- **#8 (auto-link Qt sysroot dirs):** The cookbook's `BUILD_PRESCRIPT`
+  now auto-detects if the per-recipe sysroot has Qt6 (qtbase or
+  qtdeclarative) and creates the canonical
+  `/usr/{plugins,mkspecs,metatypes,modules}` symlinks. New KF6 recipes
+  that depend on qtbase no longer need to manually call
+  `redbear_qt_link_sysroot_dirs` in their build script. Recipes that
+  need more customization can still call the helper directly via
+  `source $COOKBOOK_ROOT/local/scripts/lib/qt-sysroot.sh`.
+
+- **#9 (failure classifier):** `local/scripts/classify-cook-failure.py`
+  scans the tail of a failed `repo cook` output and matches it against
+  ~14 known failure patterns documented in AGENTS.md "COMPLEX FIX
+  CHECKLIST (v6.0-impl17)". Each rule emits a structured fix with
+  the relevant build flags, paths, and AGENTS.md reference. Cuts
+  per-failure diagnosis from 5-10 min of manual pattern-matching to
+  10-30 seconds. Pure read-only analysis, no build side effects.
+  Also opportunistically references the new
+  `audit-patch-idempotency.py` from the patch-no-longer-applies rule,
+  tying the two improvements together.
+
+Recommended order for the remaining 7: #6, #2, #5, #4, #10, #1, #7A.
 
-Recommended order: #3, #6, #8 (S-sized, low risk, quick wins), then #2,
-#5, #9 (M-sized, real productivity wins), then #4, #7A, #10, #1
-(bigger), then #7B as a separate project.