From ad807fb0df7d3ba6fc41345bbd3bf61c3eab6844 Mon Sep 17 00:00:00 2001
From: Jeroen Schweitzer <jpmschweitzer@gmail.com>
Date: Wed, 6 May 2026 17:58:27 +0200
Subject: [PATCH] fail dart doc CI on validate-links warnings (T-17)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wraps the `dart doc --validate-links` step so any warning fails the
job, not just hard errors. The previous step exited 0 even with
broken doc refs and dangling README links — exactly the
informational-mode drift that lets a clean board rot.

Updates the CHANGELOG entry to describe the gate accurately (the
earlier wording overstated `--validate-links`, which only prints).

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .gitea/workflows/test.yml | 9 ++++++++-
 .pql/pql-plan.json        | 2 +-
 CHANGELOG.md              | 7 ++++---
 3 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml
index a292681f..a230b085 100644
--- a/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -78,7 +78,14 @@ jobs:
       - uses: subosito/flutter-action@v2
         with: { channel: stable, cache: true }
       - run: dart pub get
-      - run: dart doc --validate-links
+      - name: dart doc --validate-links (fail on warning)
+        run: |
+          set -o pipefail
+          dart doc --validate-links 2>&1 | tee dartdoc.log
+          if grep -q "^  warning:" dartdoc.log; then
+            echo "::error::dartdoc emitted warnings — see log above"
+            exit 1
+          fi
       - uses: actions/upload-artifact@v4
         with:
           name: dart-api-docs
diff --git a/.pql/pql-plan.json b/.pql/pql-plan.json
index 5509e599..cbd96917 100644
--- a/.pql/pql-plan.json
+++ b/.pql/pql-plan.json
@@ -1,5 +1,5 @@
 {
-  "exported_at": "2026-05-06T15:58:18Z",
+  "exported_at": "2026-05-06T15:58:27Z",
   "decisions": [
     {
       "id": "D-1",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b52a8bd0..f35ca2e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,9 +19,10 @@ heading, and (b) bumping `pubspec.yaml` `version:` in the same commit.
 ### Added
 
 - Staged `dart doc` CI job — generates and uploads an HTML API
-  reference for the public `lib/` surface, with `--validate-links` to
-  fail the build on broken references. Inert with the rest of the
-  workflow until Gitea Actions activates.
+  reference for the public `lib/` surface. The step wraps
+  `dart doc --validate-links` and grep-fails the build on any warning,
+  so broken doc refs and dangling links can't accumulate. Inert with
+  the rest of the workflow until Gitea Actions activates.
 - Mouse wheel scrolling in Claude pane — converts scroll events to
   PgUp/PgDown so Claude Code (and other TUI apps) scroll their
   history naturally.