change

backend/app/cad_agent/ports.py

@@ -5,13 +5,60 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Protocol
 
-from .domain.state import TaskState
+from .domain.state import TaskPhase, TaskState
 
 
 class AdapterUnavailable(RuntimeError):
     """A bounded external-service outage; handlers must preserve checkpoints."""
 
 
+@dataclass(frozen=True, slots=True)
+class AuthorGuidanceSelection:
+    """Non-authoritative author context selected from the local guidance corpus."""
+
+    version: str = ""
+    section_ids: tuple[str, ...] = ()
+    content: str = ""
+    enabled: bool = False
+    fallback_reason: str = ""
+
+    def usage_metadata(self) -> dict[str, object]:
+        return {
+            "guidance_version": self.version,
+            "guidance_section_ids": list(self.section_ids),
+            "guidance_chars": len(self.content),
+            "guidance_enabled": self.enabled,
+            "guidance_fallback_reason": self.fallback_reason,
+        }
+
+
+class AuthorGuidance(Protocol):
+    """Select bounded local author guidance without interpreting user intent."""
+
+    def select(
+        self,
+        *,
+        phase: TaskPhase,
+        atomic_id: str,
+        repair_required: bool,
+        supported_atomic_ids: tuple[str, ...],
+    ) -> AuthorGuidanceSelection: ...
+
+
+class NullAuthorGuidance:
+    """Compatibility default that retains the pre-guidance author prompt."""
+
+    def select(
+        self,
+        *,
+        phase: TaskPhase,
+        atomic_id: str,
+        repair_required: bool,
+        supported_atomic_ids: tuple[str, ...],
+    ) -> AuthorGuidanceSelection:
+        return AuthorGuidanceSelection(fallback_reason="guidance_not_configured")
+
+
 @dataclass(frozen=True, slots=True)
 class InvocationRecord:
     invocation_id: str