scriptoriumadmin/Roo-Code
1
0
Fork 0
mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-09-17 23:51:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update ARCHITECTURE_NOTES.md and lockfile

Browse source
This commit is contained in:
kidist demessie 2026-02-18 21:05:45 +03:00
parent 2db1a917a4
commit 0ef7a85741
2 changed files with 21869 additions and 28552 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

107
ARCHITECTURE_NOTES.md
View file

@ -1,39 +1,76 @@
ARCHITECTURE REPORT: The Governed AI-Native IDERole: Forward Deployed Engineer (FDE)Framework: TRACE (Trusted Runtime for Autonomous Containment and Evidence)Executive SummaryThis 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 TopologyTo 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 BrainBased 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): I 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): This file 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 EngineI 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 & SchemasAdvanced Intent-Code Traceability FlowI 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 snippetsequenceDiagram
# 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)
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)
The Semantic Ledger Schema (agent_trace.jsonl)My ledger implements position-independent tracking by hashing specific AST nodes (Cursor, 2026).JSON{
"version": "1.0",
"id": "uuid-v4",
"timestamp": "2026-02-18T12:00:00Z",
"vcs": { "type": "git", "revision": "git_sha" },
"files": [
{
"path": "src/auth/middleware.ts",
"conversations": [
{
"contributor": { "type": "ai", "model_id": "claude-3-7-sonnet" },
"ranges": [
{
"start_line": 15,
"end_line": 45,
"content_hash": "sha256:a8f5f167f44f..."
}
]
}
]
}
]
} 5. Mathematical Verification: Spatial HashingTo solve code movement during refactors, I implemented a multidimensional Spatial Hashing algorithm (Rigaux et al., 2001; Dropstone, 2025). The content hash $H$ for an AST node $N$ is:$$H = \text{SHA-256}(\text{Normalize}(\text{Tree-sitter}(N)))$$This ensures Spatial Independence. Even if a function moves 200 lines, its cryptographic identity remains linked to the original business intent, allowing us to mathematically distinguish between an AST_REFACTOR and an INTENT_EVOLUTION (Dropstone, 2025).6. Repository Structure: src/hooks/To satisfy the "Master Thinker" rubric, I organized the src/hooks/ folder to be clean, isolated, and modular:types.ts: Shared interfaces for WBS contexts and mutation classes (Bora, 2024).HookEngine.ts: The central orchestrator wrapping the executeTool pipeline.IntentManager.ts: State management for the two-stage handshake.TraceLogger.ts: Implementation of SHA-256 hashing and the JSONL semantic ledger.7. Conclusion: Repaying the Cognitive DebtBy embedding Leveson’s hierarchy and the TRACE framework into the IDE host, I have repaid the Trust Debt of AI coding (Vella, 2026). Human intent remains the "Supreme Guiding Principle," making every AI-generated line verifiable and structurally sound (Bora, 2024; LF Projects, 2025).
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)
```

50314
pnpm-lock.yaml generated
View file

File diff suppressed because it is too large Load diff