fail dart doc CI on validate-links warnings (T-17)

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

@@ -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

.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",

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.