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
Roo-Code/docs/submission-report.md
Yakob Dereje 3db3b0112a feat: implement deterministic hook system and intent-traceability ledger 
- Added SelectActiveIntentTool for handshake protocol
- Implemented middleware gatekeeper in tool execution pipeline
- Integrated RecordAgentTraceTool for SHA-256 content hashing
- Created .orchestration/ artifacts for machine-readable audit trails
2026-02-21 23:00:24 +03:00

12 KiB
Raw Blame History

Master Thinker Orchestration Architecture Report

Submission Draft (Markdown → PDF)

Project: Roo Code Master Thinker
Date: February 21, 2026
Prepared by: Yakob

1) Architecture Overview

This implementation evolves the extension into an intent-governed orchestration system across four phases:

  1. Phase 1 — Handshake: force intent selection before destructive actions.
  2. Phase 2 — Hook Middleware: add classification + human authorization + scope checks in the execution path.
  3. Phase 3 — Traceability: persist intent-linked file-change traces with deterministic content hashing.
  4. Phase 4 — Concurrency: prevent stale writes using optimistic locking and conflict feedback.

The guiding principle is: no destructive write without validated intent context, and no untraceable mutation.

Diagram A — Two-Stage Handshake

sequenceDiagram
    participant U as User
    participant L as LLM Agent
    participant T as select_active_intent Tool
    participant Y as active_intents.yaml
    participant W as Write Tool

    U->>L: "Implement change X"
    L->>T: select_active_intent(intent_id)
    T->>Y: load intent context
    Y-->>T: constraints + scope (+ status)
    T-->>L: intent_context XML
    L->>W: write_to_file/apply_patch
    Note over W: Allowed only after valid active intent context

Diagram B — Hook Middleware Flow

flowchart TD
    A[Tool call emitted] --> B{Command Classification}
    B -->|SAFE| C[Continue]
    B -->|DESTRUCTIVE| D[HITL Authorization]
    D -->|Denied| X[Reject tool_result + stop]
    D -->|Approved| E[Intent Context Validation]
    E -->|Invalid/Missing| X
    E -->|Valid| F[Scope Enforcement]
    F -->|Out of scope| X
    F -->|In scope| G[Execute tool]
    G --> H[Return tool_result]

Diagram C — Traceability Pipeline

flowchart LR
    A[Successful file write] --> B[Read final content]
    B --> C[SHA-256 hash]
    C --> D[Semantic classifier: REFACTOR/EVOLUTION]
    D --> E[Build trace entry]
    E --> F[Append JSONL line to .orchestration/agent_trace.jsonl]

Diagram D — Concurrency Control

flowchart TD
    A[Before write: capture initial hash] --> B[User approval complete]
    B --> C[Recompute current file hash]
    C --> D{Hash unchanged?}
    D -->|Yes| E[Proceed write]
    D -->|No| F[Raise StaleFileError]
    F --> G[Return error tool_result]
    G --> H[Force re-read before retry]

2) Phase 0: Architecture Notes (Archaeological Dig)

Key Findings

Tool Execution Locations

Prompt Builder Location

Webview Communication

3) Phase 1: The Handshake

Components Implemented

Gatekeeper Implementation

4) Phase 2: Hook Middleware

Command Classification

HITL Authorization

Scope Enforcement

Autonomous Recovery

  • Denied/out-of-scope/invalid-intent cases return structured tool errors so the agent can recover by:
    1. selecting valid intent,
    2. re-reading context,
    3. producing scoped retries.

5) Phase 3: Traceability

SHA-256 Content Hashing

Semantic Classification

Trace Serialization

JSONL Schema (Operational)

{
	"timestamp": "2026-02-21T21:00:00.000Z",
	"intent_id": "INTENT-001",
	"file_path": "src/core/tools/WriteToFileTool.ts",
	"content_sha256": "hex_sha256_digest",
	"semantic_change": "REFACTOR | EVOLUTION",
	"tool": "write_to_file"
}

6) Phase 4: Concurrency

Optimistic Locking Primitive

Write-path Integration

  • Integrated (minimally/safely) in src/core/tools/WriteToFileTool.ts:
    1. Capture initial hash after file existence resolution.
    2. Revalidate hash immediately before final save.
    3. On mismatch, block write and emit stale-file error.
    4. Clear hash state on completion/failure paths.

Stale File Detection

If file content changes between read and write windows, write is rejected and the agent is instructed to re-read current content before retry.

Conflict Resolution

  • Returns explicit stale conflict error (StaleFileError semantics).
  • Prevents silent overwrite.
  • Forces reconciliation loop (read → regenerate patch/write).

7) Evaluation Rubric Self-Assessment

Metric How I Achieve Score 5
Intent-AST Correlation .orchestration/agent_trace.jsonl links intent_id to content hash and file path after successful writes.
Context Engineering Dynamic intent context resolution from .orchestration/active_intents.yaml, injected before execution.
Hook Architecture Middleware checks in src/core/assistant-message/presentAssistantMessage.ts gate destructive paths with policy layering.
Orchestration Intent-first flow + traceability + optimistic locking provide safe multi-agent behavior and conflict-aware writes.

8) Screenshots (Submission Section)

Add these 4 screenshots with captions:

  1. Gatekeeper block without intent

    • Show Roo response containing governance error: “You must cite a valid active Intent ID”.

  2. HITL approval dialog

    • Show destructive action confirmation prompt before execution.

  3. Trace output with hash

  4. Stale-file conflict error

    • Show rejected write with stale/optimistic-lock error forcing re-read.

Appendix A — Primary Files by Phase

Appendix B — PDF Conversion Tips

  • Use VS Code Markdown Preview + “Print to PDF”, or Pandoc:
    • pandoc report.md -o report.pdf
  • Ensure Mermaid diagrams are rendered before export (or pre-render to images if needed).
graph TD
    A[User Request] --> B{Has Intent?}
    B -->|No| C[Call select_active_intent]
    C --> D[Load Intent Context]
    D --> B

    B -->|Yes| E{Command Type?}
    E -->|Safe| F[Execute Immediately]
    E -->|Destructive| G{In Scope?}
    G -->|No| H[Scope Violation Error]
    G -->|Yes| I{HITL Approved?}
    I -->|No| J[User Rejected Error]
    I -->|Yes| K[Execute Tool]

    K --> L{File Changed?}
    L -->|Yes| M[Stale File Error]
    L -->|No| N[Write Success]
    N --> O[Record Trace]