[Architecture] Move workspace intent read contract out of MCP-private modules

[orenlab]

[Architecture] Move workspace intent read contract out of MCP-private modules

Labels: enhancement, architecture, mcp, change-control
Priority: P2 (architecture triage)
Subject: codeclone/workspace_intent/gate.py
Signal: ownership_drift
Triage run: e28867ed (health 91/A)

Summary

codeclone.workspace_intent advertises a public read-only hook API, but gate.py depends on six MCP-private _workspace_intent_* modules for schema, parsing, lifecycle, and registry I/O.

Environment

• Product/Service: CodeClone
• Version: 2.1.0a1 (run e28867ed)
• Area: Structural Change Controller / workspace intent / Cursor plugin hooks

Current State

1. codeclone/workspace_intent/__init__.py exports evaluate_workspace_edit_gate, has_authorized_workspace_intent, etc. as public read-only helpers.
2. gate.py imports:
   • codeclone.surfaces.mcp._workspace_intent_contract
   • codeclone.surfaces.mcp._workspace_intent_lifecycle
   • codeclone.surfaces.mcp._workspace_intent_models
   • codeclone.surfaces.mcp._workspace_intent_paths
   • codeclone.surfaces.mcp._workspace_intent_schema
   • codeclone.surfaces.mcp._workspace_intents
3. Production consumer: plugins/cursor-codeclone/hooks/_hook_io.py.
4. Impact blast: medium.

Expected Behavior

Plugin hooks import only codeclone.workspace_intent (and config) for read decisions. Registry schema, document parsing, lifecycle rules, and storage backends are owned by a surface-neutral controller package; MCP remains a writer, not the definition owner of hook-facing contracts.

Actual Behavior

Hook-facing “public API” is a thin facade over MCP-private implementation modules. Registry backend or lifecycle contract changes can break hooks without a stable boundary.

Impact

Medium — Blocks clean evolution of workspace intent registry (SQLite vs file) and couples IDE hooks to MCP internal shapes. Documented intent vs implementation owner mismatch.

Proposed Direction

• Lift read models, parsing, lifecycle predicates, and readonly registry access into codeclone/workspace_intent/ (or a dedicated controller subpackage).
• MCP _workspace_intent_* modules import shared types or call shared read APIs; writers stay in MCP session workflow.
• Add architecture test: codeclone.workspace_intent must not import codeclone.surfaces.mcp._workspace_intent_* (mirror of _blast_radius guard).

Additional Context

• Architecture triage score: B → 25 (P2).
• Counterpart writers: codeclone/surfaces/mcp/_session_workflow_mixin.py, _workspace_intents.py.
• Tests: tests/test_workspace_intent_gate.py, tests/test_cursor_plugin_hooks.py.