ci: add a ruff (pyflakes) lint gate

.github/workflows/ci.yml

@@ -6,6 +6,20 @@ name: CI
 on: [push, pull_request]
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff (pyflakes — undefined names, dead imports/vars, syntax errors)
+        run: ruff check coworker tests
+
   pytest:
     runs-on: ubuntu-latest
     steps:

coworker/automation/tools.py

@@ -9,7 +9,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, Optional
+from typing import Any, Callable
 
 import aisuite as ai
 

coworker/catalog.py

@@ -14,7 +14,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Callable
 
 import aisuite as ai

coworker/connectors/base.py

@@ -9,7 +9,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass
 from enum import Enum
 from typing import Any, Awaitable, Callable, Optional
 

coworker/connectors/descriptors.py

@@ -9,7 +9,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import Callable, Optional
 
 

coworker/connectors/relay_client.py

@@ -30,7 +30,7 @@
 from typing import Any, Awaitable, Callable, Optional, Protocol
 
 from .adapters import _SLACK_MENTION_RE, slack_event_to_event
-from .base import BasePlatformAdapter, InteractionEvent, SendResult, SessionSource
+from .base import BasePlatformAdapter, InteractionEvent, SendResult
 from .senders import _send_slack, _send_slack_interactive
 from .slack_addr import qualify
 

coworker/permissions.py

@@ -25,8 +25,8 @@ def _has_shell_operators(command: str) -> bool:
     return any(op in command for op in _SHELL_OPERATORS)
 
 from .risk import (  # re-exported for back-compat (manager.py imports WRITE_TOOLS)
-    SHELL_TOOL,
-    WRITE_TOOLS,
+    SHELL_TOOL,  # noqa: F401
+    WRITE_TOOLS,  # noqa: F401
     RiskClass,
     RiskOverrides,
     classify,

coworker/personas/loading.py

@@ -11,7 +11,7 @@
 
 import subprocess
 from pathlib import Path
-from typing import Callable, Optional
+from typing import Callable
 
 from .manifest import PersonaManifest
 

coworker/server/manager.py

@@ -2656,8 +2656,6 @@ def approval_outcome(self, resolution: str, request, session_id: str):
         """Map an approval resolution (from any surface) to an ApprovalOutcome, handling
         the task-persistent "always_task" vocabulary alongside the session-scoped ones.
         """
-        from ..engine import ApprovalOutcome
-
         if resolution == "always_task":
             self.mint_task_rule(
                 session_id,
@@ -2677,7 +2675,6 @@ def approval_outcome(self, resolution: str, request, session_id: str):
         return ApprovalOutcome.DENY
 
     def _scheduled_approver(self, task, session_id: str):
-        from ..engine import ApprovalOutcome
         from ..permissions import WRITE_TOOLS
 
         name_allowed = task.name_allowed_tools()

coworker/skills/store.py

@@ -28,7 +28,7 @@
 import aisuite as ai
 
 from ..secrets import state_dir
-from .base import Skill, _parse_skill
+from .base import _parse_skill
 
 _NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
 _MAX_NAME = 64

coworker/subscriptions.py

@@ -21,7 +21,7 @@
 import re
 import threading
 from collections import deque
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Optional
 

pyproject.toml

@@ -37,7 +37,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-asyncio", "httpx"]
+dev = ["pytest>=8", "pytest-asyncio", "httpx", "ruff>=0.16"]
 # Inbound messaging listeners (outbound send_message needs only httpx, already a core dep).
 # aiohttp is slack-bolt's Socket Mode transport at runtime (and the FakeSlack test harness
 # drives the real handler) — declare it so CI installs it, not just transitively.
@@ -62,3 +62,15 @@ coworker = ["personas/builtin/*.md"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
+
+[tool.ruff]
+# CI actually runs 3.12 (see ci.yml); pinning here (rather than deriving from the
+# 3.10-floor `requires-python`) avoids false undefined-name positives on names the
+# stdlib only added later (e.g. `ExceptionGroup`, 3.11+).
+target-version = "py312"
+
+[tool.ruff.lint]
+# Deliberately narrow (owner call — see issue #34): pyflakes catches real latent bugs
+# (undefined names, dead imports/variables, shadowed-unused redefinitions) with ~zero
+# false positives and no style opinions to bikeshed. Widen once this is settled in.
+select = ["E9", "F"]

tests/test_code_tools.py

@@ -9,8 +9,6 @@
 import subprocess
 from types import SimpleNamespace
 
-import pytest
-
 from coworker.tools.files import file_tools
 from coworker.tools.git import git_tools
 from coworker.tools.search import _py_grep, search_tools

tests/test_config.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from pathlib import Path
-
 from coworker.config import load_config
 
 

tests/test_connectors.py

@@ -4,8 +4,6 @@
 
 from __future__ import annotations
 
-import asyncio
-
 import pytest
 
 from coworker.connectors import (

tests/test_dm_routing.py

@@ -3,7 +3,6 @@
 
 import asyncio
 
-import pytest
 from fastapi.testclient import TestClient
 
 from coworker.connectors.base import MessageEvent, SessionSource

tests/test_email_tools.py

@@ -4,8 +4,6 @@
 
 from email.message import EmailMessage
 
-import pytest
-
 from coworker.connectors.email_tools import (
     build_search_criteria,
     decode_mime_header,

tests/test_memory.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import aisuite as ai
 from coworker.conversations import ConversationStore
 from coworker.memory import Scope, SQLiteMemoryStore, format_memories, memory_tools
 from coworker.sessions import SessionRecord

tests/test_message_source.py

@@ -9,7 +9,7 @@
 
 from fastapi.testclient import TestClient
 
-from coworker.connectors.base import MessageEvent, MessageSource, SessionSource
+from coworker.connectors.base import MessageEvent, SessionSource
 from coworker.engine import TurnEngine
 from coworker.permissions import PermissionEngine
 from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient

tests/test_multiroot.py

@@ -14,7 +14,7 @@
 import aisuite as ai
 from coworker.engine import TurnEngine
 from coworker.events import EventType
-from coworker.permissions import Decision, Mode, PermissionEngine
+from coworker.permissions import PermissionEngine
 from coworker.providers import AssistantTurn, ToolCall
 from coworker.roots import RootDir, normalize_roots, render_context
 from coworker.tools import ToolRegistry

tests/test_plan_mode.py

@@ -195,7 +195,7 @@ def test_discuss_mode_blocks_writes_without_plan_pressure(tmp_path):
         ],
     )
     permissions.mode = Mode.DISCUSS
-    events = _collect(engine, "tweak x.py")
+    _collect(engine, "tweak x.py")
     assert not (tmp_path / "x.py").exists()
     assert any(
         m.get("role") == "tool" and "discuss mode is read-only" in m["content"]

tests/test_risk_overrides.py

@@ -5,7 +5,7 @@
 from types import SimpleNamespace
 
 from coworker.overrides import RiskOverrideStore
-from coworker.permissions import Mode, PermissionEngine
+from coworker.permissions import PermissionEngine
 from coworker.risk import RiskClass, classify
 
 MCP_META = SimpleNamespace(requires_approval=True, category="mcp")

tests/test_skills_api.py

@@ -11,7 +11,6 @@
 import io
 import zipfile
 
-import pytest
 from fastapi.testclient import TestClient
 
 from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient

tests/test_skills_sessions.py

@@ -15,7 +15,6 @@
 from coworker.skills import (
     SessionSkillStore,
     SkillLoader,
-    SkillStore,
     effective_skills,
     skill_catalog_text,
     skill_tools,

tests/test_skills_store.py

@@ -9,7 +9,6 @@
 from __future__ import annotations
 
 import io
-import json
 import os
 import zipfile
 from pathlib import Path

tests/test_slack_relay.py

@@ -11,7 +11,7 @@
 from coworker.connectors import relay_client
 from coworker.connectors.adapters import make_adapter
 from coworker.connectors.base import InteractionEvent, MessageEvent
-from coworker.connectors.config import ConnectorSettings, load_settings
+from coworker.connectors.config import load_settings
 from coworker.connectors.relay_client import SlackRelayAdapter
 from coworker.connectors.slack_addr import qualify, split
 from coworker.connectors.tools import make_send_message_tool

tests/test_standing_approvals.py

@@ -10,7 +10,6 @@
 import asyncio
 
 import aisuite as ai
-import pytest
 
 from coworker.automation import Schedule, ScheduledTask, Scheduler, TaskRun, TaskStore
 from coworker.automation.models import grant_entries, rule_entry, rule_parts

tests/test_subscriptions.py

@@ -2,8 +2,6 @@
 
 import asyncio
 
-import pytest
-
 from coworker.connectors.base import MessageEvent, SessionSource
 from coworker.subscriptions import (
     ChannelBuffer,

tests/test_tools_permissions.py

@@ -7,7 +7,7 @@
 import pytest
 
 import aisuite as ai
-from coworker.permissions import Decision, Mode, PermissionEngine
+from coworker.permissions import Mode, PermissionEngine
 from coworker.tools import ToolRegistry