Architecture Notes: Master Thinker Edition

1. Data Flow Map (Request-to-Execution)

User Input: Received via the React Webview.
Context Assembly: ClineProvider.ts calls src/core/task/Task.ts to generate the System Prompt.
Decision: The LLM selects a tool. presentAssistantMessage.ts orchestrates the tool call.
Execution: WriteToFileTool.ts executes the handle() method to modify the file system.

2. Governance Interception Points

Pre-Hook (Phase 1/2): Located in WriteToFileTool.ts inside handle(). This will block execution if .orchestration/active_intents.yaml does not have an in-progress status.
Post-Hook (Phase 3): Located at the end of handle() after a successful write. This will trigger the agent_trace.jsonl logger to hash the new content.

3. Intent-Code Gap Analysis

Standard Git tracks "What" changed but lacks the "Why." By using a sidecar orchestration layer, we map every Abstract Syntax Tree (AST) change to a specific Requirement ID. This prevents "Context Rot" where agents lose track of architectural constraints during long-running tasks.

Architectural Design Report

1. The Intent-First Protocol (Two-Stage State Machine)

The core of this implementation is a move away from "Vibe Coding" towards a governed, stateful interaction. I have architected a Two-Stage State Machine for every user request:

Stage 1: The Reasoning Intercept (The Handshake): The agent is no longer permitted to generate code immediately. It must first analyze the request, identify a valid intent_id from the governance sidecar, and call the select_active_intent tool. +1

Stage 2: Contextualized Action: Only after the "Handshake" is successful and the context is injected can the agent proceed to use destructive tools like write_to_file or execute_command. +1

2. The Deterministic Hook (Gatekeeper Architecture)

To ensure compliance, I implemented a Deterministic Hook System that acts as a strict middleware boundary: +1

Pre-Hook Implementation: In WriteToFileTool.ts and ExecuteCommandTool.ts, I injected a gatekeeper check at the start of the handle method.

Verification Logic: This hook verifies the presence of a global active intent flag. If the agent attempts a file modification without a validated "checkout," the hook blocks execution and returns a formal governance error: "You must cite a valid active Intent ID".

Fail-Safe: This ensures that the architecture enforces the rules, rather than relying on the LLM's "best effort" to follow instructions.

3. Context Engineering (Dynamic Injection vs. Context Rot)

Traditional AI IDEs suffer from "Context Rot" by dumping entire file trees into the prompt. This implementation solves this via Dynamic Context Injection: +1

Sidecar Pattern: All architectural constraints and business intents are stored in .orchestration/active_intents.yaml. +1

On-Demand Context: When select_active_intent is called, the system reads the YAML and constructs a targeted <intent_context> XML block.

Traceability: This ensures the agent only operates within its "owned_scope" and respects the "acceptance_criteria" defined in the sidecar, maintaining a high signal-to-noise ratio in the context window.

5. Diagrams and Schemas (Required for Interim Submission)

A. The Two-Stage Handshake (Sequence Diagram)

This diagram illustrates how the Hook Engine intercepts the LLM's request to ensure intent-validation before execution.

sequenceDiagram
    participant User
    participant LLM as Roo Code Agent
    participant Hook as Hook Engine (Middleware)
    participant Sidecar as .orchestration/active_intents.yaml

    User->>LLM: "Refactor Auth Logic"
    Note over LLM: Agent is blocked from writing code
    LLM->>Hook: call select_active_intent(INT-001)
    Hook->>Sidecar: Validate Intent ID & Status
    Sidecar-->>Hook: Return Scope & Constraints
    Hook-->>LLM: Inject <intent_context> into prompt
    Note over LLM: Agent now has authorization
    LLM->>User: "I have loaded intent INT-001. Proceeding..."

B. Intent Context Schema

<intent_context>
<intent_id>INT-001</intent_id>
<status>IN PROGRESS</status>
<owned_scope>
<file>src/auth/\*\*</file>
<file>src/middleware/jwt.ts</file>
</owned_scope>
<constraints> - Must not use external auth providers - Maintain backward compatibility
</constraints>
</intent_context>

4.3 KiB Raw Blame History