ops: reduce comment density in PR #4433

Cut commentary from 104 to 24 lines across the new lint script, CI
config, and pre-push hook. Kept only: policy reference, why pattern is
loose, why scope is PR commits not history, and non-obvious CI behavior
notes. No logic lines changed.

Refs #4432

.forgejo/workflows/ci.yml

@@ -3,123 +3,78 @@ name: CI
 on:
   pull_request:
     branches: ["**"]
-  # Lets `hive-forge ci-rerun` re-trigger CI via the workflow-dispatch API
-  # without an empty commit. No effect on the PR-triggered runs above.
+  # Lets `hive-forge ci-rerun` re-trigger CI via workflow-dispatch API
   workflow_dispatch:
 
 jobs:
   check:
     name: nix flake check
     runs-on: [hive-ci]
-    # Bound the job so a wedged build fails in minutes instead of
-    # hanging until the runner's 3h cap (or, when the runner itself
-    # deadlocks, never). 30 min is well above a cold-cache rebuild
-    # (~15 min observed) and well under the 3h hard cap — tune if a
-    # legit cold build ever trips it.
+    # 30 min is well above a cold-cache rebuild (~15 min observed) and well
+    # under the runner's 3h cap
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v3
       - name: check
-        # Runs all flake checks: formatting (treefmt+rustfmt), cargo test,
-        # cargo clippy, and module evaluation. No --no-build: the checks
-        # derivations are the canonical source of truth.
         run: nix flake check
 
   tracker-tags:
     name: tracker-tag lint
     runs-on: [hive-ci]
-    # Pure git+grep — seconds normally; a few minutes is already a hang.
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v3
       - name: lint
-        # Flags hash-number tracker tags in source (hive convention is
-        # prose, not tags — /knowledge/hive-rules.md). Its own job, and
-        # IS a required check on the forge (branch protection) — a hit
-        # blocks merge. See scripts/check-issue-refs.sh.
         run: sh scripts/check-issue-refs.sh
 
   comment-blocks:
     name: comment-block lint
     runs-on: [hive-ci]
-    # Pure git+awk — seconds.
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v3
       - name: lint
-        # Flags contiguous comment blocks over 30 lines (a giant prose
-        # block belongs in docs/ as implementation notes, not in source).
-        # Own job, and IS a required check on the forge (branch
-        # protection) — a hit blocks merge. See
-        # scripts/check-comment-blocks.sh.
         run: sh scripts/check-comment-blocks.sh
 
   doc-refs:
     name: doc-pointer lint
     runs-on: [hive-ci]
-    # Pure git+grep — seconds.
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v3
       - name: lint
-        # Flags `docs/…md` paths and relative markdown links that no
-        # longer resolve. Pointing at a doc is what the comment-block
-        # lint above pushes people toward, so the pointers need a gate of
-        # their own. See scripts/check-doc-refs.sh.
         run: sh scripts/check-doc-refs.sh
 
   attribution-trailers:
     name: attribution-trailer lint
     runs-on: [hive-ci]
-    # Pure git — seconds.
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0
       - name: lint
-        # Flags Co-Authored-By trailers with Claude/Anthropic attribution
-        # in PR commits (hive convention in /knowledge/hive-rules.md forbids
-        # them — an attribution line in a prompt is not a control). Own
-        # job, and IS a required check on the forge (branch protection) — a
-        # hit blocks merge. See scripts/check-attribution-trailers.sh.
         run: sh scripts/check-attribution-trailers.sh
 
   prose-lint:
     name: prose lint (vale)
     runs-on: [hive-ci]
-    # A `vale sync` + full docs/ run took under a minute in testing.
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v3
       - name: lint
-        # Styles (Microsoft + alex + write-good, named in .vale.ini's
-        # `Packages` line) are fetched fresh from the Vale Package Hub each
-        # run rather than vendored, so this job always lints against
-        # upstream's current rules. Failing red on a hit is intentional --
-        # the existing docs/ tree has a standing backlog of warning- and
-        # suggestion-level rule hits, so this job stays red on unrelated
-        # PRs until that backlog is worked down (tracked separately, as a
-        # follow-up to the error-only work below). Not wired into branch
-        # protection -- see the sibling job below for the error-only slice
-        # that is.
+        # Styles are fetched fresh from Vale Package Hub each run (not vendored).
+        # Not wired into branch protection — see prose-lint-errors below for the
+        # error-only slice that is.
         run: XDG_DATA_HOME="$PWD/.vale-data" nix shell nixpkgs#vale --command sh -c 'vale sync && vale docs'
 
   prose-lint-errors:
     name: prose lint (vale, errors)
     runs-on: [hive-ci]
-    # Own `vale sync` rather than reusing the sibling job's: each job gets
-    # a fresh checkout/environment, so there is nothing to share between
-    # them without an artifact-upload step this doesn't need.
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v3
       - name: lint
-        # The error-level-only slice of the sibling job above.
-        # `--minAlertLevel=error` changes what vale both reports AND exits
-        # non-zero on, so this job's pass/fail tracks only error-severity
-        # rule hits, not the warning/suggestion backlog the sibling job
-        # carries. Split out so this one alone can be a required check
-        # (forge branch protection) without blocking merges on the
-        # pre-existing backlog the sibling job still surfaces.
+        # Error-level-only slice. Split out so this job alone can be a required
+        # check without blocking merges on the warning/suggestion backlog.
         run: XDG_DATA_HOME="$PWD/.vale-data" nix shell nixpkgs#vale --command sh -c 'vale sync && vale --minAlertLevel=error docs'