From bfba148f76c4bc7733c54b932a02f040491b5981 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Sat, 4 Jul 2026 20:41:39 +0200
Subject: [PATCH] docs(ci): update CI workflow section to reflect 3-job layout

---
 docs/ci.md | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/docs/ci.md b/docs/ci.md
index 73da7583..2d119e38 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -110,24 +110,57 @@ to avoid provisioning collisions.
 
 ## CI workflow
 
-The single CI job is defined in `.forgejo/workflows/ci.yml`:
+Three jobs are defined in `.forgejo/workflows/ci.yml`:
 
 ```yaml
 name: CI
 on:
   pull_request:
     branches: ["**"]
+  # workflow_dispatch lets `hive-forge ci-rerun --pr N` retrigger without
+  # an empty commit.
+  workflow_dispatch:
+
 jobs:
   check:
     name: nix flake check
     runs-on: [hive-ci]
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v3
-      - name: check
-        run: nix flake check
+      - run: nix flake check
+
+  tracker-tags:
+    name: tracker-tag lint
+    runs-on: [hive-ci]
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v3
+      - run: sh scripts/check-issue-refs.sh
+
+  comment-blocks:
+    name: comment-block lint
+    runs-on: [hive-ci]
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v3
+      - run: sh scripts/check-comment-blocks.sh
 ```
 
-This runs on every PR, executing all flake checks (treefmt, rustfmt, cargo test, cargo clippy, module evaluation). No `--no-build`: the checks' derivations are the canonical source of truth.
+- **`nix flake check`** — all flake checks: formatting (treefmt+rustfmt),
+  cargo test, cargo clippy, module evaluation, `hivectl-docs` freshness.
+  No `--no-build`: the check derivations are the canonical source of truth.
+  30-minute wall-clock cap.
+- **`tracker-tag lint`** — flags `#NNN` tracker references in non-markdown
+  source (hive convention: use prose in code, not tags). Non-blocking for
+  now (doesn't gate merge) while the legacy backlog is cleaned up.
+- **`comment-block lint`** — flags contiguous comment blocks over 30 lines.
+  Prose belongs in `docs/`, not inline. Also non-blocking while the tree
+  settles.
+
+All three jobs run in parallel on each PR push. `hive-forge ci-rerun --pr N`
+dispatches a fresh `workflow_dispatch` run without an empty commit — the
+correct way to retry a transient CI failure.
 
 ## Security: unsandboxed builds and trusted contributors