ci: drop bare issue tags from ci.yml comments (mara, #4146)

hive-rules.md: no #NNN tags in code, prose only. The two mentions in
the new prose-lint-errors job's comments were exactly that -- reworded
to describe the split without a ticket number.

.forgejo/workflows/ci.yml

@@ -80,10 +80,29 @@ jobs:
         # `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 real backlog against these rules
-        # (663 hits as of this writing), so this job starts out red on
-        # unrelated PRs until that backlog is worked down. Not (yet) wired
-        # into branch protection as a required check, so a red result here
-        # doesn't block a merge -- opting it into required-check status is
-        # a separate, later call.
+        # 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.
         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.
+        run: XDG_DATA_HOME="$PWD/.vale-data" nix shell nixpkgs#vale --command sh -c 'vale sync && vale --minAlertLevel=error docs'

docs/agent-lifecycle/persistence.md

@@ -479,7 +479,7 @@ so it survives restarts and redeploys.
   with. **Keep it.** It's handed to Forgejo when swarm-controller registers a hook,
   so replacing the file means every subsequent delivery fails
   verification until the hook is re-registered with the new value. It's
-  generated automatically on first start; there is nothing to configure.
+  generated automatically on first start; there's nothing to configure.
 
 If the file is unreadable at startup the daemon still starts and logs
 `webhook secret unavailable`; the webhook endpoint then answers 503

docs/integrations/forge.md

@@ -279,7 +279,7 @@ to `closed_at` that `state_change_is_current` returns `true` — so it takes
 the state-change path, dropping its body. Best of both worlds:
 on the merge/close path `forge_notify` fetches the `latest_comment_url` comment and, when
 its `created_at` is strictly **after** the subject's `closed_at`
-(`comment_is_after_close`) — that is it raced the merge rather than being the
+(`comment_is_after_close`) — that is, it raced the merge rather than being the
 pre-merge last comment the subject keeps — append it as a
 `comment by <author>: <excerpt>` block before the meta suffix
 (`fresh_post_close_comment_tail`). The wake carries **both** `[PR merged]`

docs/scheduler/ci.md

@@ -31,16 +31,24 @@ writeup.
 
 ## CI checks
 
-Three jobs run on every PR (and on `workflow_dispatch` for manual re-triggers),
-defined in [`.forgejo/workflows/ci.yml`](../../.forgejo/workflows/ci.yml). All
-three are required checks (forge branch protection) — a hit on any of them
-blocks merge.
+Several jobs run on every PR (and on `workflow_dispatch` for manual
+re-triggers), defined in
+[`.forgejo/workflows/ci.yml`](../../.forgejo/workflows/ci.yml). The first four
+below are required checks (forge branch protection) — a hit on any of them
+blocks merge. The two vale jobs split a single check in two (#4128): the
+error-only one exists so it _can_ become a required check without also
+gating on the full job's standing warning/suggestion backlog, but flipping
+that switch on the forge is a separate operator action, not something this
+table can assert ahead of it happening.
 
-| Job                    | What it runs                                                                      |
-| ---------------------- | --------------------------------------------------------------------------------- |
-| **nix flake check**    | treefmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation   |
-| **tracker-tag lint**   | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`)    |
-| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) |
+| Job                           | What it runs                                                                                            | Required?                       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| **nix flake check**           | treefmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation                         | yes                             |
+| **tracker-tag lint**          | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`)                          | yes                             |
+| **comment-block lint**        | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`)                       | yes                             |
+| **doc-pointer lint**          | flags `docs/…md` paths and relative markdown links that no longer resolve (`scripts/check-doc-refs.sh`) | yes                             |
+| **prose lint (vale, errors)** | vale, `docs/` tree, error-severity rule hits only                                                       | not yet — intended to be        |
+| **prose lint (vale)**         | vale, `docs/` tree, full severity range (warnings + suggestions too)                                    | no — advisory, standing backlog |
 
 `hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger
 without an empty commit.

docs/swarm/ca.md

@@ -179,7 +179,7 @@ Two consumers, and only one of them is fine:
 
   The consumption differs per runtime and is the part worth knowing.
   tuwunel links no openssl, which makes `SSL_CERT_FILE` look inapplicable
-  — it isn't: its rustls-based TLS stack still resolves trust through the
+  — it's not: its rustls-based TLS stack still resolves trust through the
   platform certificate store on Linux, and that store honors
   `SSL_CERT_FILE`, so the env var takes effect the same way it would for
   an OpenSSL-linked binary.

docs/tools/forge.md

@@ -257,8 +257,8 @@ to discover valid label names before triaging or to audit the label set.
 ## Notes
 
 - **Read-before-comment guard:** `comment` refuses to post when forge still
-  has an unread notification for the thread (that is someone commented since you
-  last read it). This prevents accidentally replying to old activity without
+  has an unread notification for the thread (that is, someone commented since
+  you last read it). This prevents accidentally replying to old activity without
   seeing the new context. Read the thread with `hive-forge view <n>` or
   `hive-forge comments <n>` (which mark the notification read and clear the
   block), or pass `--force` to skip the guard.

docs/tools/hivectl.md

@@ -240,7 +240,7 @@ Bare `choom` starts a fresh blank session. `--resume <value>` passes
 through as `claude --resume <value>` to rejoin a prior session by its
 session id — the flag name deliberately matches the claude flag it maps
 to. (choom never uses claude's `--continue`: that's a bare flag that
-takes no argument and resumes the cwd's _latest_ session, that is the
+takes no argument and resumes the cwd's _latest_ session, that is, the
 harness's; a value after it would be consumed as the first prompt,
 silently poking the live harness session.) A value is required when the
 flag is given. Either way choom never collides with the harness's live

docs/tools/swarmctl-cli.md

@@ -25,7 +25,7 @@ swarm-level operator CLI
 ###### **Options:**
 
 * `--authelia-bin <PATH>` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the *configured* package rather than whatever is on `PATH`
-* `--users-file <PATH>` — Host-side path of authelia's users database — that is the path inside the container, prefixed with the container's root.
+* `--users-file <PATH>` — Host-side path of authelia's users database — that is, the path inside the container, prefixed with the container's root.
 
    This is the only user store: it's read before every change and written in place, and `swarm-authelia-bridge` writes the same file.
 

docs/turn-loop/config.md

@@ -240,7 +240,7 @@ It leaves non-compile subcommands (`new`, `add`, third-party
 Set to `false` for agents that parse cargo's JSON output
 programmatically and don't pass `--message-format json` themselves.
 
-## API-key backend (`useApiKey` / `backendEnvironmentFile`)
+## API-key provider (`useApiKey` / `backendEnvironmentFile`)
 
 ```nix
 hyperhive.useApiKey = true;               # default: false
@@ -249,7 +249,7 @@ hyperhive.backendEnvironmentFile =
 hyperhive.model = "anthropic/claude-3.5-sonnet"; # provider-specific model string
 ```
 
-Runs this agent's `claude` against an API-key backend (for example OpenRouter)
+Runs this agent's `claude` against an API-key provider (for example OpenRouter)
 instead of a Claude subscription via OAuth. Two options, paired — each
 is a no-op without the other:
 
@@ -299,4 +299,4 @@ Switching an already-provisioned OAuth agent to `useApiKey` leaves
 `~/.claude/credentials.json` in place but unused — harmless, not
 cleaned up automatically. Cost shape also changes: subscription pricing
 → per-request billing with no built-in monthly cap, worth knowing before
-pointing a busy agent at a metered backend.
+pointing a busy agent at a metered provider.

docs/web-ui/dashboard.md

@@ -454,7 +454,7 @@ named buckets of MCP tools; each agent starts with a role default
 `ToolGroup::AGENT_DEFAULT`; hive-c0re seeds the root agent to
 `ToolGroup::MANAGER_DEFAULT` — `messaging`, `meta`, `inbox`,
 `lifecycle`, `approvals`, `scheduling`, `diagnostics`, `execution`,
-that is every group except `forge` and `web_tools`). Checking /
+that is, every group except `forge` and `web_tools`). Checking /
 unchecking stages which groups are active for the agent; the
 page-level **save all** button (below) commits it. Columns come from
 `GET /api/tool-groups`. hive-c0re queues a rebuild so `HIVE_TOOL_GROUPS`

swarmctl/src/main.rs

@@ -58,8 +58,8 @@ struct PathArgs {
     /// rather than whatever is on `PATH`.
     #[arg(long, value_name = "PATH")]
     authelia_bin: Option<PathBuf>,
-    /// Host-side path of authelia's users database — that is the path inside
-    /// the container, prefixed with the container's root.
+    /// Host-side path of authelia's users database — that is, the path
+    /// inside the container, prefixed with the container's root.
     ///
     /// This is the only user store: it's read before every change and
     /// written in place, and `swarm-authelia-bridge` writes the same file.