[loop-cycle-65] feat: scaffold three-phase loop skeleton (#324) (#330)

src/loop/phase2_reason.py

@@ -0,0 +1,36 @@
+"""Phase 2 — Reason: accept gathered context, produce reasoning output.
+
+This is the deliberation phase. It receives enriched context from Phase 1
+and decides what to do. In the stub form, it passes the payload through
+with a phase marker.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from loop.schema import ContextPayload
+
+logger = logging.getLogger(__name__)
+
+
+def reason(payload: ContextPayload) -> ContextPayload:
+    """Accept gathered context and return a reasoning result.
+
+    Stub: tags the payload with phase=reason and logs transit.
+    Timmy will flesh this out with LLM calls, confidence scoring,
+    plan generation, and judgment logic.
+    """
+    logger.info(
+        "Phase 2 (Reason) received: source=%s gathered=%s",
+        payload.source,
+        payload.metadata.get("gathered", False),
+    )
+
+    result = payload.with_metadata(phase="reason", reasoned=True)
+
+    logger.info(
+        "Phase 2 (Reason) produced: metadata_keys=%s",
+        sorted(result.metadata.keys()),
+    )
+    return result