autofix: add a docs scope that fixes only documentation threads

.changeset/autofix-docs-scope.md

@@ -0,0 +1,13 @@
+---
+"autofix": minor
+---
+
+Add `docs` to the scope axis: `autofix: docs` / `/autofix docs` fixes only the `documentation` reviewer's threads, selected by the label that reviewer mints (`suggestion (non-blocking, documentation)`).
+
+It is a **subset of `nits`, not a peer of it**. Documentation findings are non-blocking, so `nits` already covers them and arming both is the same as arming `nits`; the containment runs one way only, and `docs` exists because arming `nits` to clear three stale comments also invites the fixer into every other cosmetic thread on the PR. The flat token namespace cannot express that, so `scope.ts` and the README both say it. `findingLabelsForScope` becomes an exhaustive switch rather than a blocking/non-blocking ternary, and the tests pin the containment and the absence of any blocking label from docs scope.
+
+`docs` is **not loop-eligible**, which is worth stating because it looks like the exception to "nits never loop" and is only half one: its deletion half converges (a comment that restates the code is either gone or not), while the documentation reviewer's *missing explanation* findings are answered with prose, and prose can always be wanted better. Ineligible until something measures which half dominates.
+
+One prompt rule comes with it: a documentation item changes text, never code. Deleting a redundant comment is the expected fix (and such findings often carry no suggestion block, since a deletion cannot be expressed as one), but if the honest fix would touch an executable line the item is left unfixed and reported rather than becoming a code change wearing a documentation label. That property — edits that cannot alter behavior — makes `docs` the safest scope to trial first in a repo new to autofix.
+
+Note the version coupling: autofix selects threads by parsing the label off each posted comment, so this scope finds threads only in repos whose **installed** `review` release mints the documentation label. Against an older reviewer it is not broken, just always empty.

.github/workflows/autofix.md

@@ -1,10 +1,10 @@
 ---
 description: >
   Addresses the PR reviewer's own feedback on demand, one run per arming. Arm it
-  with an `/autofix [blocking|nits]` comment, or with an `autofix: blocking` /
-  `autofix: nits` label; the two are peers. The run fixes the reviewer's open
-  threads in that scope, pushes one commit, replies in each thread, and clears
-  the label if one armed it.
+  with an `/autofix [blocking|nits|docs]` comment, or with an `autofix: blocking`
+  / `autofix: nits` / `autofix: docs` label; the two are peers. The run fixes the
+  reviewer's open threads in that scope, pushes one commit, replies in each
+  thread, and clears the label if one armed it.
 
 on:
   # Two arming surfaces, and they are PEERS — neither is a shorthand for the
@@ -167,6 +167,7 @@ safe-outputs:
     allowed:
       - "autofix: blocking"
       - "autofix: nits"
+      - "autofix: docs"
       - "autofix: loop"
       - "autofix: human"
       - "autofix: author"
@@ -472,6 +473,16 @@ Edit the files directly in the workspace. Rules, all hard:
   the finding unfixed and explain why in Step 7. Deleting an assertion, loosening
   a matcher, adding a skip, or widening an expected range to make something pass
   is never an acceptable outcome of this workflow.
+- **A documentation item changes text, never code.** An item labelled
+  `suggestion (non-blocking, documentation)` is a finding about a comment or a
+  prose doc, and the whole reason its scope exists is that its edits cannot
+  alter behaviour. Deleting a comment the finding calls redundant is the
+  expected fix, not an overreach, and such a finding often carries no
+  suggestion block precisely because a deletion cannot be expressed as one. But
+  if the honest fix would touch an executable line — renaming the symbol the
+  comment misdescribes, changing the constant the comment contradicts — that is
+  a code change wearing a documentation label: leave the item unfixed and say
+  why in Step 7. Fix the sentence, or fix nothing.
 - **Do not touch files no item points at.** The one exception is a change that
   is mechanically forced by a fix (a caller that must be updated for a changed
   signature); note any such file in Step 7.