[sweep] strip Fxxx audit-ID tokens + trim bloated comments/docstrings + add behavior-change docs

Post-audit sweep over the 135 audit-fix commits since 19a474d3:

1. Stripped every # Fxxx: audit-ID token from comments AND every Fxxx token
   from docstring openings across 211 blocks / ~626 lines. The CEO flagged
   these twice: audit-issue IDs in code confuse future devs/agents. The
   descriptive text is preserved; only the Fxxx token is removed (and bloated
   narrative blocks trimmed to 1-3 lines keeping the one non-obvious invariant).
2. Trimmed bloated comments/docstrings to the concise standard (1-3 lines).
3. Added missing behavior-change docs for the audit-fix batch: prompts/roles
   (documenter, pr_reviewer, qa), user-facing docs (api auth, websockets,
   agent-gateway, megatask, merge-model, task-lifecycle, grok, resilience,
   conventions, panel, security, troubleshooting), and the RAG corpus (cell-pm,
   main-pm, pr-reviewer, qa roles; conventions; messaging-tools; escalation;
   megatask; task-claiming workflows).

Comment/docstring/prose ONLY — zero code-line edits (verified: the diff
contains no def/class/return/if/for/await/assignment/call lines). Gates green:
ruff format + ruff check clean, mypy clean on roboco/. The only pytest failures
are the pre-existing sync_branch tracing-decision gap (B1, 250be5c2) — not
sweep-caused and tracked separately.

tests/unit/llm/providers/test_grok_auth.py

@@ -112,11 +112,10 @@ def test_refresh_mints_new_token_when_stale(tmp_path: Path) -> None:
 
 
 def test_refresh_omitting_expires_in_still_marks_token_valid(tmp_path: Path) -> None:
-    """F092: if xAI's refresh response omits ``expires_in``, the access token's
-    JWT ``exp`` claim is the authoritative expiry — decode it so a fresh token
-    isn't left with the stale pre-refresh ``expires_at`` (which would make
-    ``is_valid`` / ``--check`` forever reject it and the refresh loop re-rotate
-    the single-use refresh token every tick)."""
+    """If xAI's refresh response omits ``expires_in``, the access token's JWT
+    ``exp`` claim is the authoritative expiry — decode it so a fresh token isn't
+    left with the stale pre-refresh ``expires_at`` (which would re-rotate the
+    single-use refresh token every tick)."""
     path = tmp_path / "auth.json"
     _write(path, _bundle(_PAST))
     exp_unix = int((datetime.now(UTC) + timedelta(hours=6)).timestamp())
@@ -136,10 +135,9 @@ def test_refresh_omitting_expires_in_still_marks_token_valid(tmp_path: Path) ->
 def test_refresh_omitting_expires_in_with_unreadable_jwt_defaults_ttl(
     tmp_path: Path,
 ) -> None:
-    """F092 fallback: expires_in missing AND the access token isn't a JWT with a
-    readable ``exp`` — default to the documented ~6h TTL so a fresh token is
-    treated as live instead of stale, rather than forever rejected (the warning
-    is emitted via structlog, visible in the captured stdout)."""
+    """Fallback when ``expires_in`` is missing AND the access token isn't a JWT
+    with a readable ``exp``: default to the documented ~6h TTL so a fresh token
+    is treated as live instead of forever rejected."""
     path = tmp_path / "auth.json"
     _write(path, _bundle(_PAST))
 
@@ -185,12 +183,10 @@ def test_refresh_failed_when_no_access_token(tmp_path: Path) -> None:
 def test_refresh_persists_rotated_token_when_atomic_write_fails(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    """F006: a rotated refresh_token is single-use — xAI invalidates the old one
-    the moment it issues the new one. If the atomic write (tmp+replace) fails
-    after the rotation, the file keeps the now-dead old refresh_token and the
-    credential is permanently lost on the next refresh. The write must fall back
-    to a direct write so the rotated refresh_token survives even when the atomic
-    replace can't."""
+    """A rotated refresh_token is single-use — xAI invalidates the old one on
+    rotation. If the atomic write (tmp+replace) fails after rotation, the file
+    keeps the now-dead refresh_token and the credential is permanently lost; the
+    write must fall back to a direct write so the rotated token survives."""
     path = tmp_path / "auth.json"
     _write(path, _bundle(_PAST))
 

tests/unit/llm/test_providers.py

@@ -242,10 +242,9 @@ async def test_grok_spawn_mounts_auth_when_present(_isolate_grok_auth: Path) ->
     ) as exec_mock:
         await provider.spawn(_config())
     cmd = list(exec_mock.call_args.args)
-    # F005: mount the host ~/.grok DIRECTORY (ro), not the single auth.json
-    # file — a single-file bind mount pins the inode, so the orchestrator's
-    # atomic auth.json refresh (rename) never reaches a running container.
-    # The entrypoint symlinks ~/.grok/auth.json at this RO dir mount.
+    # mount the host ~/.grok DIRECTORY (ro), not the single auth.json file — a
+    # single-file bind mount pins the inode, so the orchestrator's atomic
+    # auth.json refresh (rename) never reaches a running container.
     expected = f"{_isolate_grok_auth}:/home/agent/.grok-auth-ro:ro"
     assert expected in cmd