[Architecture] Move propose-on-finish memory orchestration out of the MCP surface

[orenlab]

[Architecture] Move propose-on-finish memory orchestration out of the MCP surface

Labels: enhancement, architecture, memory, mcp
Priority: P1 (architecture triage)
Subject: codeclone/surfaces/mcp/_session_memory_mixin.py::finish_propose_memory
Signal: domain_logic_leakage (+ responsibility_overload)
Triage run: 1f2fd12a (health 91/A)

Summary

finish_propose_memory in the MCP surface owns a transport-neutral Engineering Memory workflow order:

coverage-before
→ propose candidates
→ apply staleness
→ coverage-after
→ coverage delta

The individual operations already live in codeclone.memory modules, but their required composition is defined only inside the MCP adapter.

Environment

• Product/Service: CodeClone
• Version: 2.1.0a1 (run 1f2fd12a)
• Area: Engineering Memory / controlled-change finish workflow

Current State

1. codeclone/surfaces/mcp/_session_memory_mixin.py::finish_propose_memory composes:
   • compute_scope_coverage before proposal;
   • propose_memory_from_changed_paths;
   • apply_scope_staleness;
   • compute_scope_coverage after proposal;
   • coverage delta calculation and result shaping.
2. These operations are owned by separate memory modules: memory.coverage, memory.ingest.receipts, and memory.staleness.
3. The full sequence is not duplicated in the CLI surface. CLI memory coverage is a standalone reporting path, not an equivalent propose-on-finish workflow.
4. _session_memory_mixin.py is also an overloaded module: 734 LOC, fan-out 22, overloaded score approximately 0.938. It combines retrieval, governance dispatch, auto-sync, projection rebuild, scope resolution, and finish proposal behavior.

Expected Behavior

A transport-neutral propose-on-finish workflow should be owned by a surface-neutral application service. MCP should parse tool arguments, invoke the service, and render the bounded response.

The final owner should be validated explicitly during implementation — likely a memory application/workflow service or a controlled-change memory service — rather than assumed from package convenience.

Actual Behavior

The MCP surface defines the workflow ordering and coverage/staleness accounting semantics. A future CLI, IDE, or internal consumer would need to reproduce that order to obtain equivalent behavior.

Impact

Medium to high — No correctness bug is demonstrated today, but workflow semantics are coupled to one transport. This creates drift risk for future surfaces and makes changes to proposal/staleness accounting depend on MCP internals.

Proposed Direction

• Extract a surface-neutral application operation for propose-on-finish.
• Return a typed result containing proposal outcome, coverage before/after, coverage delta, and staleness effects.
• Keep MCP-only argument parsing, error mapping, response budgeting, and payload shaping in _session_memory_mixin.py.
• Preserve Engineering Memory authority rules: memory must not grant edit permission or override findings, gates, Patch Trail, edit_allowed, or do_not_touch.
• Add contract tests for workflow ordering and result parity at the application-service boundary.

Acceptance Criteria

• The coverage → proposal → staleness → coverage sequence has one surface-neutral owner.
• _session_memory_mixin.py delegates the workflow and retains only MCP adaptation.
• Existing finish proposal payload semantics remain backward-compatible.
• CLI, MCP, and IDE consumers can reuse the same application operation without duplicating the sequence.
• Tests prove ordering, failure behavior, coverage delta semantics, and no authority expansion.
• No baseline, report, cache, fingerprint, gate, Patch Trail, or edit-authorization contract changes.

Additional Context

• Architecture triage score: B+D → 35 (P1).
• sqlite_store.py overload is tracked separately in [Architecture] Split Engineering Memory SQLite persistence monolith #41 and should not be duplicated here.
• memory/retrieval/service.py overload remains a watchlist item while extraction is already in progress.
• This issue concerns workflow ownership, not the presence of delegated memory calls in an MCP adapter.