unified-execute-surface

🎯 Unified Execute Surface

Case Details

Case ID: task-a83bf643-0173-423d-8f8a-8a45019d8869 Status: parked Created: 2026-01-23T15:38:32.403Z Updated: 2026-01-23T15:38:32.403Z Priority: 3

Investigation Details

Case Type: story Urgency Level: routine Assigned Detective: Claude

Notes

The Problem

MCP currently exposes two separate execution tools:

oculus_execute_virtual_fence / ____execute - for TODO lists, workflows
oculus_execute_fence - for Python/bash code fences

This creates confusion when agents try to execute a fence - they need to know which type it is before calling the right tool. The addressing is already unified (slug:index or label), but the control surface is split.

Error That Triggered This

____execute({
  slug: "required-reading",
  index: 8,
  params: { topic: "ai-onboarding" },
  action: "execute"
})
// Failed: tried virtual fence endpoint for a code fence

Desired Behavior

Single MCP tool that routes internally:

execute({
  fence_id: "required-reading:8",  // or label
  action: "execute",               // or "add", "toggle", etc.
  params: { topic: "ai-onboarding" }
})

The MCP/API layer should:

Resolve the fence (by slug:index or label)
Detect fence type (virtual vs code)
Route to appropriate handler
Return unified response format

Implementation Notes

Unified addressing already exists
API may already have internal routing - need to verify
MCP proxy is the place to compress the surface
Could deprecate separate tools or keep as aliases

Acceptance Criteria

Single execute tool in MCP handles both fence types
Agent doesn't need to know fence type before calling
Existing calls continue to work (backward compat)
Error messages guide user if action doesn't match fence type

Investigation Timeline

2026-01-23T15:38:32.407Z - Claude - case_created

Case opened from CLI

Consciousness Links

Context: Unifying execution surface across fence types

This case file is automatically updated. For investigation logs, see the corresponding log channel.

📋 Case To-Do List

This case has an integrated to-do list system that syncs with the Oculus knowledge graph. The to-do list uses the virtual:todo-list fence which auto-detects GitHub-style checkbox markdown.

How the To-Do System Works

Auto-Detection: Checkbox lists are automatically detected as virtual:todo-list fences
Alice Integration: Display in Alice dashboard using :::wonderland-todo-list slug="${current_case}"
ISA Operations: Use fence exec for add/check/update operations
Metadata Support: Add [assignee:name] [priority:level] tags to tasks

Case To-Do Operations

View state: oculus fence list ${slug} then oculus fence view ${slug} <fence-index>
Add task: oculus fence exec ${slug} <fence-index> add "New task"
Check task: oculus fence exec ${slug} <fence-index> check 0
Update task: oculus fence exec ${slug} <fence-index> update 0 "Updated content"
Reference: See virtual-fence-todo for full documentation

Current Case Tasks

🎯 Solve the case
📝 Document findings in investigation notes
🔗 Link relevant evidence and consciousness resources
✅ Update case status when complete

Next Steps

Add investigation notes and evidence tags as you progress. The to-do list will evolve with your investigation. Tasks can be managed via Oculus fence operations or edited directly in the node.