feat(memory) + docs: T01 complete — cya/phase-memory integration contract (MemoryVision), refined port signatures in seam (no-op preserved), phase-memory (arch/interop/lifecycle/ports) review; workplan T01 marked done. ralph iter 1.

src/cya/memory/__init__.py

@@ -1,19 +1,18 @@
-"""phase-memory ports (T05) — strictly minimal no-op version.
+"""phase-memory ports (T05 → T02) — cya seam to phase-memory (markitect).
 
-Operator direction (2026-05-26): Keep strictly minimal in this slice.
-Pure explicit ports with no-op implementations and clear
-"to be replaced by real phase-memory integration" markers.
-**No local JSON placeholder or file-backed store in this slice.**
+See CYA-WP-0002 T01 contract in MemoryVision.md for full details.
+This module is the explicit, inspectable boundary. All memory for
+assistance (preferences, project context, etc.) flows through here.
 
-All memory interactions in can-you-assist must go through these ports.
-No global singletons, no implicit ~/.cache, no opaque vendor memory.
+Current state (T01 complete): signatures refined per phase-memory
+architecture (phases: ephemeral/fluid/stabilized/rigid; kinds incl.
+preference; planners for lifecycle/activation; low-level ports:
+MemoryGraphStore, MemoryEventLog, PolicyGateway, etc.). Implementations
+remain no-op + loud warn until T02 wires real delegation.
 
-When the real `phase-memory` package is integrated, the entire contents
-of this module (or the implementations behind these names) will be
-replaced by the real ports. Code reviewers and future contributors
-should be able to point at this file and say "this is the seam".
-
-See workplan CYA-WP-0001-T05 for the full contract and acceptance criteria.
+Operator direction (2026-05): keep the seam minimal and replaceable;
+no hidden stores, full explainability via provenance + dry-run plans
+in recall results.
 """
 
 from __future__ import annotations
@@ -34,49 +33,75 @@ def _warn_not_connected(feature: str) -> None:
 
 # ---------------------------------------------------------------------------
 # Explicit ports (the four capabilities from the workplan)
-# These are the exact extension points that phase-memory will implement.
+# Refined in T01 per phase-memory architecture + interop + lifecycle.
+# These map to preference kind + graph/event + planner concepts.
+# See MemoryVision.md "cya ↔ phase-memory Integration Contract".
+# Implementations (T02+) will delegate to phase_memory.ports / planner / runtime.
+# Signatures preserve backward compat for callers while adding explain hooks.
 # ---------------------------------------------------------------------------
 
 
-def remember_preference(key: str, value: Any, scope: str = "cwd") -> None:
-    """Remember a user preference or workflow pattern.
+def remember_preference(
+    key: str,
+    value: Any,
+    scope: str = "cwd",
+    *,
+    profile: str | None = None,
+    ttl: str | None = None,
+) -> None:
+    """Remember a user preference or workflow pattern (preference kind).
 
-    Will be replaced by real phase-memory.
+    Delegates (T02+) to phase-memory profile execution / graph store.
+    Dry-run plans and policy checks come from phase-memory lifecycle.
     """
-    _warn_not_connected(f"remember_preference({key!r}, scope={scope})")
-    # No-op by design
+    _warn_not_connected(
+        f"remember_preference({key!r}, scope={scope}, profile={profile})"
+    )
+    # No-op by design (T01 complete; real in T02)
 
 
-def recall_preferences(scope: str = "cwd", task_class: str | None = None) -> dict[str, Any]:
-    """Recall relevant history / preferences for the current cwd + task class.
+def recall_preferences(
+    scope: str = "cwd",
+    task_class: str | None = None,
+    *,
+    kinds: list[str] | None = None,
+    profile: str | None = None,
+    limit: int = 50,
+) -> dict[str, Any]:
+    """Recall relevant history / preferences for cwd + task (preference + context).
 
-    Will be replaced by real phase-memory.
-    Returns empty dict in this slice.
+    Returns structured payload with items, provenance, dry_run_plan, phase.
+    Enables explainability in orchestrator / --explain-context.
+    Will be replaced by real phase-memory retrieval + planner.
     """
-    _warn_not_connected(f"recall_preferences(scope={scope}, task={task_class})")
+    _warn_not_connected(
+        f"recall_preferences(scope={scope}, task={task_class}, profile={profile})"
+    )
     return {}
 
 
-def forget(scope: str = "cwd", keys: list[str] | None = None) -> None:
+def forget(scope: str = "cwd", keys: list[str] | None = None, *, profile: str | None = None) -> None:
     """Forget / reset memory (scoped).
 
-    Will be replaced by real phase-memory.
+    Delegates to phase-memory retention / lifecycle planner (dry-run first).
     """
-    _warn_not_connected(f"forget(scope={scope}, keys={keys})")
+    _warn_not_connected(f"forget(scope={scope}, keys={keys}, profile={profile})")
     # No-op
 
 
-def export_memory(scope: str = "cwd") -> dict[str, Any]:
+def export_memory(scope: str = "cwd", *, profile: str | None = None) -> dict[str, Any]:
     """Inspect / export current memory for this project or user.
 
-    Will be replaced by real phase-memory.
-    Returns a clear "disabled" marker in this slice.
+    Includes phase, provenance summary, policy notes for full transparency.
+    Used by CLI explain paths.
     """
-    _warn_not_connected(f"export_memory(scope={scope})")
+    _warn_not_connected(f"export_memory(scope={scope}, profile={profile})")
     return {
-        "status": "phase-memory not connected (T05 no-op)",
+        "status": "phase-memory not connected (T05 no-op; T01 contract complete)",
         "scope": scope,
-        "note": "Replace this entire module with the real phase-memory ports.",
+        "profile": profile,
+        "note": "Replace this module with real phase-memory ports (see MemoryVision contract).",
+        "phases": ["ephemeral", "fluid", "stabilized", "rigid"],
     }