mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-09-19 00:01:19 +00:00
76 lines
3.7 KiB
Markdown
76 lines
3.7 KiB
Markdown
# ARCHITECTURE REPORT: The Governed AI-Native IDE
|
||
|
||
**Role:** Forward Deployed Engineer (FDE)
|
||
**Framework:** TRACE (Trusted Runtime for Autonomous Containment and Evidence)
|
||
|
||
---
|
||
|
||
## Executive Summary
|
||
|
||
This report formalizes the architecture for a governed AI-Native IDE, engineered to bridge the Provenance Gap between probabilistic reasoning and deterministic software engineering (Entire, 2026). By embedding infrastructure-level mediation into the IDE tool loop, we replace "vibe coding" with cryptographic verification and structured intent (TRACE, 2026; Bora, 2024).
|
||
|
||
---
|
||
|
||
## 1. How the VS Code Extension Works: Dual-Process Topology
|
||
|
||
To ensure security and performance, the extension operates as a distributed system within VS Code (VS Code, 2026):
|
||
|
||
### Extension Host (Logic Layer)
|
||
|
||
A Node.js process where the core orchestrator (`src/core/Cline.ts`) manages the agentic loop. It has full privileges for filesystem access and terminal execution (VS Code, 2026).
|
||
|
||
### Webview (UI Layer)
|
||
|
||
A restricted React sandbox for the user interface. It communicates with the Host via the `postMessage` API, ensuring reasoning-heavy tasks do not block the UI thread (Ansible, 2026).
|
||
|
||
> My architecture intercepts the Thinking-Acting-Observing loop at the Extension Host level, mediating every system-level tool call (e.g., `write_to_file`) before execution (Roo Code, 2026).
|
||
|
||
---
|
||
|
||
## 2. Code & Design Architecture: The Shared Brain
|
||
|
||
Based on my Phase 0 archaeological dig into the Roo Code "nervous system," I have implemented two critical intervention points (Bockeler, 2025):
|
||
|
||
- **The Prompt Factory (`src/core/prompts/system.ts`)**
|
||
Modified the prompt builder to move from "Instruction-based" to "Context-based" engineering. The agent is now architecturally barred from code synthesis until it completes a mandatory "Reasoning Handshake" (Bora, 2024; Bockeler, 2025).
|
||
|
||
- **The Shared Brain (`AGENT.md`)**
|
||
Acts as a persistent project "Constitution." It records lessons learned from failed verification loops, preventing Context Rot during parallel agent sessions (LF Projects, 2025).
|
||
|
||
---
|
||
|
||
## 3. Architectural Decisions: The TRACE Hook Engine
|
||
|
||
I have implemented the TRACE framework to derive assurance from infrastructure mediation rather than model behavior (TRACE, 2026).
|
||
|
||
- **Command Classification:** Every tool is classified as Safe (Read/Search) or Destructive (Write/Execute) (Roo Code, 2026).
|
||
- **The Handshake (Pre-Hook):** Mutation is prohibited until the agent calls `select_active_intent(intent_id)`. This pauses the promise chain and injects `What-Boundaries-Success` (WBS) constraints from `.orchestration/active_intents.yaml` into the current context (Bora, 2024).
|
||
- **Autonomous Recovery:** If the engine blocks an action, it returns a standardized JSON error to the LLM, allowing the "silicon worker" to self-correct without human intervention (TRACE, 2026).
|
||
|
||
---
|
||
|
||
## 4. Diagrams & Schemas
|
||
|
||
### Advanced Intent-Code Traceability Flow
|
||
|
||
I integrated Nancy Leveson’s Seven Levels of Intent Specification to provide a vertical trace from Level 1 (System Purpose) to Level 5 (Physical Code) (Navarro et al., 2001).
|
||
|
||
### Code Snippet (Sequence Diagram)
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant LLM as AI Agent (Builder)
|
||
participant Hook as TRACE Hook Engine
|
||
participant AST as Tree-sitter Parser
|
||
participant FS as .orchestration/ (Ledger)
|
||
|
||
LLM->>Hook: select_active_intent(INT-001)
|
||
Note right of Hook: Loads Level 3 WBS Constraints
|
||
Hook-->>LLM: Injected XML Constraints
|
||
LLM->>Hook: write_file(src/auth.ts, content)
|
||
Hook->>AST: Parse Block to AST Node
|
||
AST-->>Hook: Structural Identity
|
||
Hook->>Hook: Calculate H = SHA-256(Normalize(Block))
|
||
Hook->>FS: Append Trace to agent_trace.jsonl
|
||
Hook-->>LLM: Success (Level 6 Operations Data)
|
||
```
|