refactor: no comments left - one-line module docstrings, contracts on public fields only; jobs/job.py; example config and README

src/beaver_gateway/agents/claude.py

@@ -1,24 +1,20 @@
 """Claude agent definition, backed by the Claude Agent SDK.
 
-The system prompt is ``system_prompt`` verbatim or, per conversation kind,
-the granules named in ``prompts`` assembled at every session spawn (see
-``core/prompt.py``). ``skill_sets`` are directories of ``<skill>/SKILL.md``
-folders; each becomes a local SDK plugin, either the same tuple for every
-kind or a ``SkillSets`` with a tuple per kind (§4.3: the master never sees
-what a branch opens). Nothing from disk is loaded otherwise: the adapter
-runs with ``setting_sources=[]``.
+``system_prompt`` is used verbatim, or per-kind granules from ``prompts``
+are assembled via ``agents/prompts.py``. ``skill_sets`` are
+``<skill>/SKILL.md`` directories, each becoming a local SDK plugin.
 """
 
 from __future__ import annotations
 
-from collections.abc import Mapping  # noqa: TC003 - pydantic runtime
-from pathlib import Path  # noqa: TC003 - pydantic runtime
+from collections.abc import Mapping  # noqa: TC003
+from pathlib import Path  # noqa: TC003
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from beaver_gateway.agents.base import BaseAgent
-from beaver_gateway.agents.policy import PolicyRule  # noqa: TC001 - pydantic runtime
-from beaver_gateway.agents.prompts import PromptSource  # noqa: TC001 - pydantic runtime
+from beaver_gateway.agents.policy import PolicyRule  # noqa: TC001
+from beaver_gateway.agents.prompts import PromptSource  # noqa: TC001
 from beaver_gateway.conversations.kinds import KINDS, Kind
 
 __all__ = ["ClaudeAgent", "ClaudeOptions", "Prompts", "SkillSets"]
@@ -50,10 +46,10 @@ class ClaudeOptions(BaseModel):
 
 
 class Prompts(BaseModel):
-    """Prompt assembly per conversation kind (§3.12): the granules, in order.
+    """Prompt assembly per conversation kind: the granules, in order.
 
-    A kind left ``None`` is not served by the agent; ``ClaudeAgent.kinds``
-    follows from the kinds set here.
+    A kind left ``None`` is not served; ``ClaudeAgent.kinds`` follows from
+    the kinds set here.
     """
 
     model_config = ConfigDict(frozen=True)
@@ -94,14 +90,12 @@ class ClaudeAgent(BaseAgent):
 
     prompts: Prompts = Field(default_factory=Prompts)
     kinds: tuple[Kind, ...] = ()
-    """Conversation kinds this agent serves; ``create``/``spawn`` reject the
-    rest. Defaults to the kinds ``prompts`` covers, or ``("deep",)`` for a
-    verbatim ``system_prompt``."""
+    """Conversation kinds this agent serves; ``create``/``spawn`` reject the rest.
+    Defaults to what ``prompts`` covers, or ``("deep",)`` for a verbatim prompt."""
 
     skill_sets: tuple[Path, ...] | SkillSets = ()
     """Skill-set directories, each a local plugin: one tuple for every kind,
-    or ``SkillSets`` to give each kind its own (a kind left ``None`` gets
-    no skills)."""
+    or a ``SkillSets`` giving each kind its own (``None`` = no skills)."""
 
     gateway_tools: tuple[str, ...] = ()
     """Gateway tools exposed in-process (``read_conversation``, ``spawn``,
@@ -109,8 +103,8 @@ class ClaudeAgent(BaseAgent):
 
     options: ClaudeOptions = Field(default_factory=ClaudeOptions)
     policy: tuple[PolicyRule, ...] = ()
-    """``PreToolUse`` rules (§3.7), run in order on every tool call; the
-    first ``Deny`` is what the model reads back. See ``core/policy``."""
+    """``PreToolUse`` rules, run in order on every tool call; the first
+    ``Deny`` is what the model reads back. See ``agents/policy.py``."""
 
     @model_validator(mode="after")
     def _kinds_follow_prompts(self) -> ClaudeAgent: