feat: harden agent verification and runtime contracts

Introduce two-gate checker settlement, explicit graph visibility and checkpoints, structured LLM reliability, centralized action specifications, and corresponding tests and design documentation.

tests/unit/tools/test_append_note_tool.py

@@ -13,9 +13,8 @@
 # limitations under the License.
 
 from pathlib import Path
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import MagicMock, patch
 
-from artemis.constants import VALIDATOR_MESSAGES_KEY
 from artemis.context import ArtemisContext
 from artemis.graph.state import State
 from artemis.tools.base import ArtemisTool, ToolRegistry
@@ -28,7 +27,7 @@ from artemis.tools.scratchpad import (
     append_note,
     append_note_wrapper,
 )
-from langgraph.types import Command
+from langchain_core.messages import ToolMessage
 import pytest
 
 
@@ -108,11 +107,9 @@ async def test_append_note_callable_execution(mock_ctx, tmp_path):
 
 
 @pytest.mark.asyncio
-async def test_append_note_with_state_command(mock_ctx, tmp_path):
-    """Verify AppendNoteTool.execute with state returns Command updating VALIDATOR_MESSAGES_KEY."""
+async def test_append_note_with_state_tool_message(mock_ctx, tmp_path):
+    """Verify AppendNoteTool.execute with state returns a ToolMessage directly."""
     mock_state = MagicMock(spec=State)
-    mock_state.current_agent = "operator"
-    mock_state.asanitize_update = AsyncMock(side_effect=lambda ctx, update, agent: update)
 
     result = await append_note.execute(
         ctx=mock_ctx,
@@ -122,15 +119,10 @@ async def test_append_note_with_state_command(mock_ctx, tmp_path):
         tool_call_id="call_append_999",
     )
 
-    assert isinstance(result, Command)
-    assert VALIDATOR_MESSAGES_KEY in result.update
-    tool_messages = result.update[VALIDATOR_MESSAGES_KEY]
-    assert len(tool_messages) == 1
-    assert tool_messages[0].tool_call_id == "call_append_999"
-    assert tool_messages[0].content == "Successfully appended note to state_append_note.md."
-    assert tool_messages[0].status == "success"
-
-    mock_state.asanitize_update.assert_called_once()
+    assert isinstance(result, ToolMessage)
+    assert result.tool_call_id == "call_append_999"
+    assert result.content == "Successfully appended note to state_append_note.md."
+    assert result.status == "success"
 
     note_path = Path(tmp_path) / "notes" / "state_append_note.md"
     assert note_path.exists()