Roo-Code/ARCHITECTURE_NOTES.md

Phase 1: The Handshake (Reasoning Loop Implementation)

1. Executive Summary

The objective is to move beyond text-based version control by implementing a Deterministic Hook System.
This system enforces a "Plan-First" workflow where AI agents must formally declare their Intent before mutating the codebase.

---

2. Nervous System & Interception Points

Based on the codebase audit, the following functions represent the "Strategic High Ground" for hook injection:

A. The "Reasoning Loop" (Prompt Construction)

• Location: src/core/prompts/
• Function: Handles the assembly of system instructions and tool definitions.
• Injection Strategy: Modify the SystemPrompt generator to include the mandatory select_active_intent tool and instructions that forbid file writes without an active session intent.

B. The "Pre-Hook" (Command Execution)

• Location: src/integrations/terminal/TerminalManager.ts and src/services/EditorService.ts
• Function: executeCommand() and openFile()
• Injection Strategy: Intercept calls before they reach the terminal or editor. If the agent attempts a structural change (e.g., npm install or rm), the Pre-Hook validates the action against the owned_scope defined in .orchestration/active_intents.yaml.

C. The "Post-Hook" (File Mutations)

• Location: src/core/webview/DiffViewProvider.ts and src/services/RelayService.ts
• Function: writeFile() and applyDiff()
• Injection Strategy: Intercept immediately after a successful write. This hook triggers the Content Hashing engine to generate a spatial fingerprint of the change, appending the metadata to the .orchestration/agent_trace.jsonl ledger.

---

3. The Two-Stage State Machine

To eliminate "Vibe Coding," the execution flow is re-architected into a strict handshake:

State	Entity	Action
1. Request	User	"Refactor the auth middleware."
2. Intent Handshake	Agent	Calls select_active_intent("INT-001").
3. Validation	Pre-Hook	Pauses loop. Queries .orchestration/. Injects constraints (e.g., "Use JWT, not Session").
4. Contextual Action	Agent	Generates code with injected constraints. Calls write_file.
5. Trace Logging	Post-Hook	Calculates sha256 hash. Updates agent_trace.jsonl.

---

4. Logical Architecture Diagram

User Prompt → Extension Host → Pre-Hook (Intent Validation) → LLM → Post-Hook (Trace Logging) → File System

---

5. Data Model Specification

The following machine-managed files in .orchestration/ act as the "Source of Truth" for AI governance:

• active_intents.yaml: The "Why." Defines scope, constraints, and Definition of Done (DoD).
• agent_trace.jsonl: The "How." An append-only ledger linking Intent IDs to specific Code Hashes.
• intent_map.md: The "Where." A spatial map linking business logic to AST nodes and files.
• AGENT.md: The "Memory." Shared architectural decisions and lessons learned across agent sessions.

---

6. Phase 1 Implementation Goals

• Initialize Sidecar: Automatically generate the .orchestration/ directory on extension activation.
• Tool Injection: Register select_active_intent as a core capability.
• Strict Middleware: Implement logic that blocks write_file if current_session_intent is null.