From d24ebcd87d29df47b5958c0db06eeb8aaf236618 Mon Sep 17 00:00:00 2001 From: Rediet Bekele Date: Fri, 20 Feb 2026 15:59:58 +0000 Subject: [PATCH] docs: add Phase 1 handshake architecture with interception points and data model --- ARCHITECTURE_NOTES.md | 62 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 ARCHITECTURE_NOTES.md diff --git a/ARCHITECTURE_NOTES.md b/ARCHITECTURE_NOTES.md new file mode 100644 index 0000000000..695d1addff --- /dev/null +++ b/ARCHITECTURE_NOTES.md @@ -0,0 +1,62 @@ +# 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/` and `src/core/RooCode.ts` +- **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. +