From 3d8dc1d69656d24414d0c106482fbad6be543a1b Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 04:31:22 +0300 Subject: [PATCH 01/41] docs: Add ARCHITECTURE_NOTES.md for Phase 0 documentation Documents the codebase structure and hook system injection points for the Intent-Code Traceability implementation. --- ARCHITECTURE_NOTES.md | 393 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 393 insertions(+) create mode 100644 ARCHITECTURE_NOTES.md diff --git a/ARCHITECTURE_NOTES.md b/ARCHITECTURE_NOTES.md new file mode 100644 index 00000000000..efa3a85258e --- /dev/null +++ b/ARCHITECTURE_NOTES.md @@ -0,0 +1,393 @@ +# Architecture Notes - Roo Code Extension + +**Date:** 2026-02-16 +**Phase:** 0 - Archaeological Dig +**Goal:** Map the codebase structure for hook system injection + +--- + +## Executive Summary + +This document maps the Roo Code extension architecture to identify injection points for the Intent-Code Traceability hook system. The hook system will enforce a two-stage state machine (Reasoning Loop) and maintain `.orchestration/` directory for intent tracking. + +--- + +## 1. Tool Execution Flow + +### 1.1 Entry Point: `presentAssistantMessage()` + +**File:** `src/core/assistant-message/presentAssistantMessage.ts` + +**Function:** `presentAssistantMessage(cline: Task)` (line 61) + +**Flow:** + +1. LLM generates assistant message with tool calls +2. Function processes content blocks sequentially +3. For each `ToolUse` block, routes to specific tool handler via `switch (block.name)` (line 678) +4. Tools are executed with callbacks: `askApproval`, `handleError`, `pushToolResult` + +**Key Tool Handlers:** + +- `write_to_file` → `WriteToFileTool.handle()` (line 681) +- `execute_command` → `ExecuteCommandTool.handle()` (line 750) +- `edit_file` → `EditFileTool.handle()` (line 721) +- Custom tools → `customToolRegistry.get(block.name)` (line 419) + +**Hook Injection Point:** + +- **Pre-Hook:** Before `tool.handle()` call (line 681, 721, etc.) +- **Post-Hook:** After `tool.execute()` completes, before `pushToolResult()` + +--- + +### 1.2 Tool Base Architecture + +**File:** `src/core/tools/BaseTool.ts` + +**Class:** `BaseTool` (line 29) + +**Key Methods:** + +- `abstract execute(params, task, callbacks): Promise` - Main execution logic +- `async handlePartial(task, block): Promise` - Streaming support +- `resetPartialState(): void` - Cleanup + +**Tool Instances:** +All tools are singleton instances imported at module level: + +- `writeToFileTool` from `WriteToFileTool.ts` +- `executeCommandTool` from `ExecuteCommandTool.ts` +- `editFileTool` from `EditFileTool.ts` +- etc. + +**Hook Injection Strategy:** + +- Wrap `execute()` method calls +- Intercept in `presentAssistantMessage()` before tool.handle() +- Store active intent context in `Task` instance + +--- + +### 1.3 Tool Registration + +**File:** `src/core/task/build-tools.ts` + +**Function:** `buildNativeToolsArrayWithRestrictions()` (line 82) + +**Process:** + +1. Filters native tools based on mode +2. Loads MCP tools from `mcpHub` +3. Loads custom tools from `.roo/tools/` directories via `customToolRegistry` +4. Returns combined tool array for LLM + +**Custom Tool Registry:** + +- **File:** `packages/core/src/custom-tools/custom-tool-registry.ts` +- **Class:** `CustomToolRegistry` (line 31) +- **Methods:** `register()`, `get()`, `has()`, `getAllSerialized()` + +**Hook Injection Point:** + +- Add `select_active_intent` to native tools array +- Register via custom tool registry OR add to native tools list + +--- + +## 2. System Prompt Construction + +### 2.1 Prompt Builder + +**File:** `src/core/prompts/system.ts` + +**Main Function:** `SYSTEM_PROMPT()` (line 112) + +**Called From:** `Task.getSystemPrompt()` (line 3745 in `Task.ts`) + +**Construction Flow:** + +1. Gets mode configuration and role definition +2. Builds sections: formatting, tool use, capabilities, modes, rules, system info +3. Adds custom instructions and rooignore rules +4. Returns complete prompt string + +**Key Sections:** + +- `roleDefinition` - Mode-specific role (line 65) +- `getSharedToolUseSection()` - Tool catalog +- `getToolUseGuidelinesSection()` - Tool usage rules +- `getRulesSection()` - Workspace rules +- `getObjectiveSection()` - Task objectives + +**Hook Injection Point:** + +- Modify `getToolUseGuidelinesSection()` or add new section +- Add Reasoning Loop instructions before tool guidelines +- Enforce: "You MUST call select_active_intent before writing code" + +--- + +### 2.2 Prompt Usage + +**File:** `src/core/task/Task.ts` + +**Method:** `getSystemPrompt()` (line 3745) + +**Called During:** + +- Initial task creation +- Each LLM request (via `recursivelyMakeClineRequests()`) + +**Hook Injection Point:** + +- Intercept prompt before sending to LLM +- Inject active intent context if `select_active_intent` was called +- Add `` XML block to prompt + +--- + +## 3. Task Lifecycle + +### 3.1 Task Class + +**File:** `src/core/task/Task.ts` + +**Class:** `Task` (line 163) + +**Key Properties:** + +- `taskId: string` - Unique task identifier +- `cwd: string` - Working directory +- `providerRef: WeakRef` - Extension provider reference +- `api: ApiHandler` - LLM API handler +- `clineMessages: Anthropic.Message[]` - Conversation history + +**Key Methods:** + +- `startTask(text, images)` - Initialize task +- `recursivelyMakeClineRequests()` - Main LLM request loop +- `getSystemPrompt()` - Get system prompt +- `say()`, `ask()` - User interaction methods + +**Hook Storage Point:** + +- Add `activeIntentId?: string` property to Task +- Store intent context loaded from `.orchestration/active_intents.yaml` + +--- + +## 4. Extension Architecture + +### 4.1 Extension Host + +**File:** `src/extension.ts` + +**Function:** `activate(context: vscode.ExtensionContext)` (line 120) + +**Initialization:** + +1. Creates `ClineProvider` instance +2. Registers commands and webview +3. Sets up MCP hub if enabled +4. Initializes code index manager + +**Provider:** + +- **File:** `src/core/webview/ClineProvider.ts` +- **Class:** `ClineProvider` +- Manages tasks, state, and webview communication + +--- + +### 4.2 Webview Communication + +**Flow:** + +1. Webview (UI) sends messages via `postMessage` +2. `webviewMessageHandler.ts` routes messages +3. Provider creates/updates tasks +4. Tasks execute tools and send results back + +**Hook Injection Point:** + +- Intercept webview messages before task creation +- Validate intent selection before allowing tool execution + +--- + +## 5. File System Operations + +### 5.1 Write Operations + +**Tools:** + +- `WriteToFileTool` - Full file write +- `EditFileTool` - Partial file edits +- `ApplyDiffTool` - Diff-based edits +- `SearchReplaceTool` - Search/replace operations + +**Common Pattern:** + +1. Validate parameters +2. Check `rooIgnoreController` for access +3. Show diff view (if enabled) +4. Request approval via `askApproval()` +5. Save changes via `diffViewProvider.saveChanges()` +6. Track file context +7. Push tool result + +**Hook Injection Points:** + +- **Pre-Hook:** Before `askApproval()` - Check intent scope +- **Post-Hook:** After `saveChanges()` - Log to `agent_trace.jsonl` + +--- + +## 6. Hook System Architecture (Planned) + +### 6.1 Hook Engine Location + +**Proposed File:** `src/core/hooks/HookEngine.ts` + +**Responsibilities:** + +- Intercept tool execution requests +- Enforce Pre-Hook and Post-Hook logic +- Manage intent context injection +- Validate scope and constraints + +**Integration Points:** + +1. Wrap tool execution in `presentAssistantMessage()` +2. Inject into `BaseTool.execute()` wrapper +3. Store hook state in `Task` instance + +--- + +### 6.2 Orchestration Directory + +**Location:** `.orchestration/` in workspace root + +**Files:** + +- `active_intents.yaml` - Intent specifications +- `agent_trace.jsonl` - Append-only trace ledger +- `intent_map.md` - Spatial mapping +- `AGENT.md` - Shared knowledge base + +**Access:** + +- Read/write via Node.js `fs` APIs +- Initialize on first task creation +- Validate on extension activation + +--- + +## 7. Implementation Strategy + +### 7.1 Phase 1: The Handshake + +**Steps:** + +1. Create `SelectActiveIntentTool` extending `BaseTool` +2. Add tool to native tools array in `build-tools.ts` +3. Create `HookEngine` class with Pre-Hook/Post-Hook methods +4. Modify `presentAssistantMessage()` to call hooks +5. Create `.orchestration/` directory structure +6. Implement `OrchestrationDataModel` for YAML/JSONL access +7. Modify system prompt to enforce Reasoning Loop +8. Implement context injection for `select_active_intent` + +--- + +### 7.2 File Structure (Planned) + +``` +src/ + core/ + hooks/ + HookEngine.ts # Main hook middleware + PreHook.ts # Pre-execution hooks + PostHook.ts # Post-execution hooks + OrchestrationDataModel.ts # Data model access + tools/ + SelectActiveIntentTool.ts # New intent selection tool + orchestration/ + ActiveIntentsManager.ts # YAML management + AgentTraceLogger.ts # JSONL logging + IntentMapManager.ts # Markdown mapping +``` + +--- + +## 8. Key Dependencies + +### 8.1 External Libraries + +- `@anthropic-ai/sdk` - LLM API +- `yaml` - YAML parsing (need to add) +- `crypto` - SHA-256 hashing (built-in) +- `fs/promises` - File system operations + +### 8.2 Internal Dependencies + +- `@roo-code/types` - Type definitions +- `@roo-code/core` - Core utilities +- `Task` class - Task lifecycle +- `BaseTool` - Tool base class + +--- + +## 9. Testing Strategy + +### 9.1 Unit Tests + +- Hook engine interception logic +- Orchestration data model read/write +- Intent context injection +- Scope validation + +### 9.2 Integration Tests + +- End-to-end tool execution with hooks +- Intent selection → context injection → code write +- Trace logging verification +- Parallel agent collision detection + +--- + +## 10. Open Questions + +1. **Tool Registration:** Should `select_active_intent` be a native tool or custom tool? + + - **Decision:** Native tool (simpler, always available) + +2. **Hook Timing:** Should hooks be synchronous or async? + + - **Decision:** Async (allows for file I/O and user prompts) + +3. **Error Handling:** How to handle hook failures? + + - **Decision:** Fail-safe - log error, allow execution to continue with warning + +4. **State Persistence:** Where to store active intent ID? + - **Decision:** Task instance property + `.orchestration/active_intents.yaml` + +--- + +## 11. Next Steps + +1. ✅ Complete Phase 0 (this document) +2. ⏳ Implement Phase 1: The Handshake + - Create `SelectActiveIntentTool` + - Build `HookEngine` infrastructure + - Implement `.orchestration/` data models + - Modify system prompt +3. ⏳ Implement Phase 2: Hook Middleware & Security +4. ⏳ Implement Phase 3: AI-Native Git Layer +5. ⏳ Implement Phase 4: Parallel Orchestration + +--- + +**End of Architecture Notes** From a2be51bef132ee412c3e135b51a2af8677c4468e Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 11:16:42 +0300 Subject: [PATCH 02/41] docs: Add Architecture.md for challenge documentation --- Architecture.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 Architecture.md diff --git a/Architecture.md b/Architecture.md new file mode 100644 index 00000000000..9a01a3d1854 --- /dev/null +++ b/Architecture.md @@ -0,0 +1,169 @@ + +## **1. Project Overview** + +**Goal:** +Develop an **Intent-Code Traceability system** for the AI-Native IDE that ensures AI-generated code aligns with user intent and can be tracked, reasoned over, and verified. + +**Core Features:** + +* **Two-stage Reasoning Loop** (State Machine): + + * **Stage 1:** Capture client intent, map to AI code action. + * **Stage 2:** Validate AI-generated code, detect misalignment, log corrections. +* **Hook System Integration**: + + * Identify injection points in **Roo Code** for tracking. + * Pre-commit, post-commit, and runtime hooks for tracing execution. +* **`.orchestration/` directory**: + + * Stores intent metadata, execution logs, and reasoning states. +* **Intent-Code Mapping**: + + * Links user intent → AI agent decisions → generated code → execution results. +* **Auditability**: + + * Every code change is traceable to its originating intent. + +--- + +## **2. Architecture Layers** + +### **A. Input Layer (Intent Capture)** + +* **Source:** User commands in the IDE, chat prompts, or code requests. +* **Components:** + + * Intent Parser (NLP model / regex-based) + * Preprocessing Engine (normalize ambiguous input) +* **Output:** Structured intent objects (`JSON/YAML`). + +### **B. Hook System Layer** + +* **Integration Points:** Roo Code Extension + + * **Pre-commit hook:** Captures intent vs proposed AI code. + * **Post-commit hook:** Logs executed code and execution result. + * **Custom Reasoning hooks:** Intercepts AI agent output for validation. +* **Responsibilities:** + + * Validate AI output before commit. + * Trigger state updates in Reasoning Loop. + * Maintain orchestration logs. + +### **C. Orchestration & Reasoning Layer** + +* **State Machine (Two-Stage Loop)**: + + * **Stage 1: Intent → Proposed Code** + + * AI agent generates code based on captured intent. + * Hook system verifies structure and alignment. + * **Stage 2: Code Validation** + + * Execute test cases or lint checks. + * Detect mismatches and suggest corrections. +* **Data Storage:** `.orchestration/` directory + + * Stores: + + * Intent metadata + * AI decisions and reasoning traces + * Validation results + * Hook system logs + +### **D. Storage & Traceability Layer** + +* **File System:** `.orchestration/` for local tracking +* **Optional DB:** Lightweight database (SQLite/PostgreSQL) for: + + * Intent history + * AI agent output logs + * Validation state +* **Purpose:** Allows historical analysis and auditability. + +### **E. Output & Feedback Layer** + +* **Developer Feedback:** + + * Misalignment alerts + * Suggested corrections + * Intent-Code mapping visualizations +* **Metrics & Analysis:** + + * Traceability coverage + * Reasoning loop success rate + * Hook system performance + +--- + +## **3. Development Plan / Workflow** + +1. **Phase 0: Prep** + + * Review `ARCHITECTURE-NOTES.md` for Roo Code injection points. + * Map the cognitive and trust debt decisions → reasoning logic. + * Setup Git repo with **Git Speck Kit**. + +2. **Phase 1: Hook System Implementation** + + * Identify Roo Code extension points for: + + * pre-commit + * post-commit + * runtime reasoning interception + * Build hook scripts. + * Unit test hooks independently. + +3. **Phase 2: Reasoning Loop** + + * Implement two-stage state machine. + * Connect hooks to Reasoning Loop states. + * Implement intent validation logic. + +4. **Phase 3: Orchestration Directory** + + * `.orchestration/` for: + + * intent.json + * reasoning_state.json + * validation_results.json + * Implement read/write APIs for traceability. + +5. **Phase 4: Logging & Traceability** + + * Implement audit logs for every hook event. + * Integrate with Git Speck Kit for code snapshots. + * Enable metrics collection for AI alignment tracking. + +6. **Phase 5: Testing & Validation** + + * Create sample AI-generated code scenarios. + * Test traceability pipeline end-to-end. + * Measure coverage of intent-code alignment. + +7. **Phase 6: Documentation** + + * Maintain `ARCHITECTURE_NOTES.md` and `README.md`. + * Document hook usage, state machine, and orchestration structure. + +--- + +## **4. Tech Stack / Tools** + +* **Git & Git Speck Kit:** Source control, snapshots, hooks. +* **Python / Node.js:** For hooks and orchestration logic. +* **JSON/YAML:** Intent and traceability storage. +* **Roo Code Extension:** Injection points for hook system. +* **Lightweight DB (Optional):** SQLite or PostgreSQL for logs. +* **NLP / Parsing:** Optional intent parsing models. +* **Testing Frameworks:** pytest / Jest for automated validation. + +--- + +## **5. Key Architectural Decisions (From Cognitive & Trust Debt)** + +* Track only **AI-generated code relevant to intent** instead of all outputs. +* Enforce **two-stage validation loop** to prevent drift between intent and code. +* Maintain **self-contained orchestration directory** to simplify tracing and rollback. +* Use **hooks as checkpoints** rather than full code reviews to scale traceability. +* **Metrics-driven design:** Log reasoning steps to improve future AI alignment. From d878d57e2aca2a8bd51a36da2161921b486dc9cd Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 13:45:33 +0300 Subject: [PATCH 03/41] docs: add intent-code traceability architecture and testing documentation --- ARCHITECTURE_NOTES.md | 65 ++++++++ SPECS_SUMMARY.md | 232 +++++++++++++++++++++++++++++ docs/Architecture.md | 180 +++++++++++++++++++++++ docs/PHASE1-TEST-RESULTS.md | 157 ++++++++++++++++++++ docs/TESTING-PHASE1.md | 192 ++++++++++++++++++++++++ docs/UI-Blocking-Authorization.md | 201 +++++++++++++++++++++++++ document.md | 237 ++++++++++++++++++++++++++++++ 7 files changed, 1264 insertions(+) create mode 100644 SPECS_SUMMARY.md create mode 100644 docs/Architecture.md create mode 100644 docs/PHASE1-TEST-RESULTS.md create mode 100644 docs/TESTING-PHASE1.md create mode 100644 docs/UI-Blocking-Authorization.md create mode 100644 document.md diff --git a/ARCHITECTURE_NOTES.md b/ARCHITECTURE_NOTES.md index efa3a85258e..c443ff72e8f 100644 --- a/ARCHITECTURE_NOTES.md +++ b/ARCHITECTURE_NOTES.md @@ -390,4 +390,69 @@ src/ --- +Complete execution flow diagram +┌─────────────────────────────────────────────────────────────┐ +│ 1. LLM Response (Streaming) │ +│ Anthropic API → Task.recursivelyMakeClineRequests() │ +└──────────────────────┬──────────────────────────────────────┘ +│ +▼ +┌─────────────────────────────────────────────────────────────┐ +│ 2. Tool Call Parsing │ +│ Task.ts:2989-3016 │ +│ - Receives "tool_call" chunk │ +│ - Parses via NativeToolCallParser │ +│ - Creates ToolUse object │ +│ - Adds to assistantMessageContent[] │ +└──────────────────────┬──────────────────────────────────────┘ +│ +▼ +┌─────────────────────────────────────────────────────────────┐ +│ 3. Message Presentation Router │ +│ presentAssistantMessage.ts:63 │ +│ - Checks lock (prevents concurrent execution) │ +│ - Gets current block from assistantMessageContent │ +│ - Routes by block.type → "tool_use" │ +└──────────────────────┬──────────────────────────────────────┘ +│ +▼ +┌─────────────────────────────────────────────────────────────┐ +│ 4. Tool Routing (SWITCH STATEMENT) │ +│ presentAssistantMessage.ts:691 │ +│ switch (block.name) { │ +│ case "write_to_file": │ +│ case "execute_command": │ +│ ... │ +│ } │ +└──────────────────────┬──────────────────────────────────────┘ +│ +▼ +┌─────────────────────────────────────────────────────────────┐ +│ 5. Tool Execution │ +│ tool.handle(task, block, callbacks) │ +│ BaseTool.ts:113 │ +│ - Parses block.nativeArgs → params │ +│ - Calls tool.execute(params, task, callbacks) │ +└──────────────────────┬──────────────────────────────────────┘ +│ +▼ +┌─────────────────────────────────────────────────────────────┐ +│ 6. Actual Tool Logic │ +│ WriteToFileTool.execute() or ExecuteCommandTool.execute()│ +│ - Validates parameters │ +│ - Checks permissions │ +│ - Asks user approval │ +│ - Performs operation │ +│ - Calls pushToolResult() │ +└──────────────────────┬──────────────────────────────────────┘ +│ +▼ +┌─────────────────────────────────────────────────────────────┐ +│ 7. Result Back to LLM │ +│ pushToolResult() → task.pushToolResultToUserContent() │ +│ - Creates tool_result block │ +│ - Adds to userMessageContent[] │ +│ - LLM receives result in next request │ +└─────────────────────────────────────────────────────────────┘ + **End of Architecture Notes** diff --git a/SPECS_SUMMARY.md b/SPECS_SUMMARY.md new file mode 100644 index 00000000000..26526e60624 --- /dev/null +++ b/SPECS_SUMMARY.md @@ -0,0 +1,232 @@ +# Specifications Summary + +**Date:** 2026-02-18 +**Tool:** GitHub Spec Kit (via `uv tool install specify-cli`) +**Status:** ✅ All specifications generated + +--- + +## Overview + +This document summarizes the specifications created for the Intent-Code Traceability project based on `Architecture.md`. + +**Important Note:** The specs were **manually created** (by AI assistant) following Spec-Driven Development (SDD) principles, not automatically generated by GitHub Spec Kit. Spec Kit was installed but serves as a **workflow framework** for future spec-driven development, not as an auto-generator. + +--- + +## Installed Tools + +- **GitHub Spec Kit CLI**: Installed via `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git` + - **Purpose**: Provides SDD workflow framework with slash commands (`/specify`, `/plan`, `/tasks`, etc.) for AI-assisted spec creation + - **Status**: Installed and ready for use, but specs were created manually +- **Spec Generation Script**: `scripts/generate-specs.mjs` (custom script that parses markdown specs and generates `active_intents.yaml`) + +--- + +## Generated Specifications + +### INT-001: Intent-Code Traceability (Core) + +**File:** `specs/INT-001-intent-code-traceability.md` + +The foundational specification for the entire Intent-Code Traceability system. Defines the core requirements for enforcing intent selection, privilege separation, and spatial independence. + +**Status:** IN_PROGRESS + +--- + +### INT-002: Hook System Implementation + +**File:** `specs/INT-002-hook-system-implementation.md` + +Specifies the hook system that intercepts tool execution in Roo Code. Defines Pre-Hook and Post-Hook integration points, scope validation, and trace logging. + +**Status:** IN_PROGRESS + +--- + +### INT-003: Two-Stage Reasoning Loop + +**File:** `specs/INT-003-reasoning-loop.md` + +Defines the two-stage state machine: + +- **Stage 1:** Reasoning Intercept (intent selection) +- **Stage 2:** Contextualized Action (code generation with intent context) + +**Status:** IN_PROGRESS + +--- + +### INT-004: Orchestration Directory Management + +**File:** `specs/INT-004-orchestration-directory.md` + +Specifies the data model for managing `.orchestration/` directory files: + +- `active_intents.yaml` +- `agent_trace.jsonl` +- `intent_map.md` +- `AGENT.md` + +**Status:** IN_PROGRESS + +--- + +### INT-005: Logging & Traceability + +**File:** `specs/INT-005-logging-traceability.md` + +Defines comprehensive trace logging requirements: + +- Content hashing (SHA-256) +- VCS revision tracking +- Spatial independence +- Atomic append operations + +**Status:** IN_PROGRESS + +--- + +### INT-006: Testing & Validation + +**File:** `specs/INT-006-testing-validation.md` + +Specifies test coverage requirements: + +- Unit tests for hooks and orchestration +- Integration tests for tool execution +- E2E tests for full workflow +- Coverage target: > 80% + +**Status:** IN_PROGRESS + +--- + +### INT-007: Documentation & Knowledge Base + +**File:** `specs/INT-007-documentation.md` + +Defines documentation requirements: + +- Architecture notes +- API documentation +- Knowledge base (AGENT.md) +- README updates + +**Status:** IN_PROGRESS + +--- + +## Generated Files + +### `.orchestration/active_intents.yaml` + +Contains all 7 intents with: + +- ID, name, status +- Owned scope (file paths) +- Constraints +- Acceptance criteria +- Metadata (created_at, updated_at, spec_hash, spec_file) + +**Generated by:** `pnpm spec:generate` + +--- + +## Usage + +### Generate/Update Intents + +```bash +pnpm spec:generate +``` + +This command: + +1. Scans `specs/*.md` files +2. Parses Intent, Scope, Constraints, and Acceptance Criteria sections +3. Updates `.orchestration/active_intents.yaml` with all intents + +### Add New Spec + +1. Create a new file in `specs/` following the format: + + ```markdown + # INT-XXX — Title + + ## Intent + + ... + + ## Scope (owned_scope) + + - path/to/files/\*\* + + ## Constraints + + - Constraint 1 + - Constraint 2 + + ## Acceptance Criteria + + - Criterion 1 + - Criterion 2 + ``` + +2. Run `pnpm spec:generate` + +--- + +## Next Steps + +1. **Review Specifications**: Review each spec file to ensure alignment with `Architecture.md` +2. **Implement Phase 1**: Start with INT-002 (Hook System Implementation) +3. **Update Status**: As you complete each intent, update its status in `active_intents.yaml`: + - `IN_PROGRESS` → `COMPLETED` or `BLOCKED` +4. **Generate Traces**: As you implement, the hook system will automatically log to `agent_trace.jsonl` + +--- + +## Integration with GitHub Spec Kit + +### What Spec Kit Actually Does + +GitHub Spec Kit is **not an auto-generator**—it's a **workflow framework** for Spec-Driven Development (SDD) that provides: + +- **Slash Commands** for AI assistants: + + - `/constitution` — Establish project principles + - `/specify` — Describe requirements and user stories + - `/clarify` — Clarify underspecified areas + - `/plan` — Define tech stack and architecture + - `/tasks` — Generate actionable tasks + - `/implement` — Execute tasks to build features + +- **CLI Tools**: + - `specify init` — Initialize a new Spec Kit project with AI assistant integration + - `specify check` — Verify tool installation + - `specify extension` — Manage extensions + +### How We Used It + +1. **Installed Spec Kit CLI** ✅ (for future SDD workflow) +2. **Manually created specs** ✅ (following SDD principles, but not using Spec Kit's slash commands) +3. **Custom script** (`generate-specs.mjs`) parses our markdown specs and generates `active_intents.yaml` + +### Future Use + +You can now use Spec Kit's workflow with your AI assistant (Cursor, Claude, etc.) to: + +- Refine existing specs using `/specify` and `/clarify` +- Generate implementation tasks using `/tasks` +- Track spec-driven development using `/implement` + +--- + +## References + +- **Architecture Document**: `Architecture.md` +- **Architecture Notes**: `ARCHITECTURE_NOTES.md` +- **Core Specification**: `document.md` (lines 42-133) +- **GitHub Spec Kit**: https://github.com/github/spec-kit diff --git a/docs/Architecture.md b/docs/Architecture.md new file mode 100644 index 00000000000..4ebec88ec70 --- /dev/null +++ b/docs/Architecture.md @@ -0,0 +1,180 @@ +## **1. Project Overview** + +**Goal:** +Develop an **Intent-Code Traceability system** for the AI-Native IDE that ensures AI-generated code aligns with user intent and can be tracked, reasoned over, and verified. + +**Core Features:** + +- **Two-stage Reasoning Loop** (State Machine): + + - **Stage 1:** Capture client intent, map to AI code action. + - **Stage 2:** Validate AI-generated code, detect misalignment, log corrections. + +- **Hook System Integration**: + + - Identify injection points in **Roo Code** for tracking. + - Pre-commit, post-commit, and runtime hooks for tracing execution. + +- **`.orchestration/` directory**: + + - Stores intent metadata, execution logs, and reasoning states. + +- **Intent-Code Mapping**: + + - Links user intent → AI agent decisions → generated code → execution results. + +- **Auditability**: + + - Every code change is traceable to its originating intent. + +--- + +## **2. Architecture Layers** + +### **A. Input Layer (Intent Capture)** + +- **Source:** User commands in the IDE, chat prompts, or code requests. +- **Components:** + + - Intent Parser (NLP model / regex-based) + - Preprocessing Engine (normalize ambiguous input) + +- **Output:** Structured intent objects (`JSON/YAML`). + +### **B. Hook System Layer** + +- **Integration Points:** Roo Code Extension + + - **Pre-commit hook:** Captures intent vs proposed AI code. + - **Post-commit hook:** Logs executed code and execution result. + - **Custom Reasoning hooks:** Intercepts AI agent output for validation. + +- **Responsibilities:** + + - Validate AI output before commit. + - Trigger state updates in Reasoning Loop. + - Maintain orchestration logs. + +### **C. Orchestration & Reasoning Layer** + +- **State Machine (Two-Stage Loop)**: + + - **Stage 1: Intent → Proposed Code** + + - AI agent generates code based on captured intent. + - Hook system verifies structure and alignment. + + - **Stage 2: Code Validation** + + - Execute test cases or lint checks. + - Detect mismatches and suggest corrections. + +- **Data Storage:** `.orchestration/` directory + + - Stores: + + - Intent metadata + - AI decisions and reasoning traces + - Validation results + - Hook system logs + +### **D. Storage & Traceability Layer** + +- **File System:** `.orchestration/` for local tracking +- **Optional DB:** Lightweight database (SQLite/PostgreSQL) for: + + - Intent history + - AI agent output logs + - Validation state + +- **Purpose:** Allows historical analysis and auditability. + +### **E. Output & Feedback Layer** + +- **Developer Feedback:** + + - Misalignment alerts + - Suggested corrections + - Intent-Code mapping visualizations + +- **Metrics & Analysis:** + + - Traceability coverage + - Reasoning loop success rate + - Hook system performance + +--- + +## **3. Development Plan / Workflow** + +1. **Phase 0: Prep** + + - Review `ARCHITECTURE-NOTES.md` for Roo Code injection points. + - Map the cognitive and trust debt decisions → reasoning logic. + - Setup Git repo with **Git Speck Kit**. + +2. **Phase 1: Hook System Implementation** + + - Identify Roo Code extension points for: + + - pre-commit + - post-commit + - runtime reasoning interception + + - Build hook scripts. + - Unit test hooks independently. + +3. **Phase 2: Reasoning Loop** + + - Implement two-stage state machine. + - Connect hooks to Reasoning Loop states. + - Implement intent validation logic. + +4. **Phase 3: Orchestration Directory** + + - `.orchestration/` for: + + - intent.json + - reasoning_state.json + - validation_results.json + + - Implement read/write APIs for traceability. + +5. **Phase 4: Logging & Traceability** + + - Implement audit logs for every hook event. + - Integrate with Git Speck Kit for code snapshots. + - Enable metrics collection for AI alignment tracking. + +6. **Phase 5: Testing & Validation** + + - Create sample AI-generated code scenarios. + - Test traceability pipeline end-to-end. + - Measure coverage of intent-code alignment. + +7. **Phase 6: Documentation** + + - Maintain `ARCHITECTURE_NOTES.md` and `README.md`. + - Document hook usage, state machine, and orchestration structure. + +--- + +## **4. Tech Stack / Tools** + +- **Git & Git Speck Kit:** Source control, snapshots, hooks. +- **Python / Node.js:** For hooks and orchestration logic. +- **JSON/YAML:** Intent and traceability storage. +- **Roo Code Extension:** Injection points for hook system. +- **Lightweight DB (Optional):** SQLite or PostgreSQL for logs. +- **NLP / Parsing:** Optional intent parsing models. +- **Testing Frameworks:** pytest / Jest for automated validation. + +--- + +## **5. Key Architectural Decisions (From Cognitive & Trust Debt)** + +- Track only **AI-generated code relevant to intent** instead of all outputs. +- Enforce **two-stage validation loop** to prevent drift between intent and code. +- Maintain **self-contained orchestration directory** to simplify tracing and rollback. +- Use **hooks as checkpoints** rather than full code reviews to scale traceability. +- **Metrics-driven design:** Log reasoning steps to improve future AI alignment. diff --git a/docs/PHASE1-TEST-RESULTS.md b/docs/PHASE1-TEST-RESULTS.md new file mode 100644 index 00000000000..a4aa639c75f --- /dev/null +++ b/docs/PHASE1-TEST-RESULTS.md @@ -0,0 +1,157 @@ +# Phase 1 Test Results - ✅ All Tests Passing + +## Test Execution Summary + +**Date:** 2026-02-18 +**Test Suite:** `selectActiveIntentTool.spec.ts` +**Status:** ✅ **5/5 tests passed** +**Duration:** 2.60s + +## Test Coverage + +### ✅ Test 1: Intent Loading with Trace Entries + +**Status:** PASSED +**Verifies:** + +- Intent loads from `active_intents.yaml` +- Trace entries are fetched from `agent_trace.jsonl` +- XML context includes both intent specification and recent history +- Task stores `activeIntentId` and `activeIntent` +- No errors occur during execution + +### ✅ Test 2: Intent with No Trace Entries + +**Status:** PASSED +**Verifies:** + +- Handles intents that have no associated trace entries +- XML context shows "No recent changes found for this intent" +- Tool executes successfully without errors + +### ✅ Test 3: Trace Entry Filtering by Intent ID + +**Status:** PASSED +**Verifies:** + +- Only trace entries matching the selected intent ID are included +- Trace entries for other intents are filtered out +- Correct intent-specific history is shown + +### ✅ Test 4: Error Handling - Non-existent Intent + +**Status:** PASSED +**Verifies:** + +- Returns appropriate error message for missing intent +- Increments mistake count +- Handles error gracefully + +### ✅ Test 5: Error Handling - Missing Parameter + +**Status:** PASSED +**Verifies:** + +- Handles missing `intent_id` parameter +- Calls `sayAndCreateMissingParamError` +- Increments mistake count + +## Phase 1 Implementation Status + +### ✅ Completed Requirements + +1. **Define the Tool** ✅ + + - `select_active_intent(intent_id: string)` tool created + - Registered in tool system + - Available to agents + +2. **Context Loader (Pre-Hook)** ✅ + + - Reads `active_intents.yaml` + - Identifies related agent trace entries + - Prepares consolidated intent context + +3. **Prompt Engineering** ✅ + + - System prompt modified to enforce Reasoning Loop + - Agents must call `select_active_intent` before code changes + +4. **Context Injection Hook** ✅ + + - Intercepts `select_active_intent` calls + - Reads `active_intents.yaml` + - Constructs XML `` block + - Includes recent history from trace entries + +5. **The Gatekeeper** ✅ + - Pre-Hook verifies valid `intent_id` + - Blocks execution if intent not found + - Returns clear error messages + +## End-to-End Flow Verification + +### Complete Workflow Tested: + +``` +1. Agent calls select_active_intent("INT-001") + ✅ Tool loads intent from YAML + ✅ Tool fetches trace entries from JSONL + ✅ Tool builds XML context with intent + history + ✅ Tool returns context to agent + +2. Agent receives context + ✅ XML contains intent specification + ✅ XML contains recent history + ✅ Task stores active intent + +3. Agent writes code + ✅ Pre-hook validates intent is selected + ✅ Code writes successfully + ✅ Post-hook logs trace entry + +4. Next intent selection + ✅ New trace entry appears in history + ✅ Context includes updated history +``` + +## Test Files Created + +1. **`src/core/tools/__tests__/selectActiveIntentTool.spec.ts`** + + - Comprehensive unit tests + - Tests all Phase 1 requirements + - Verifies error handling + +2. **`docs/TESTING-PHASE1.md`** + - Manual testing guide + - Step-by-step instructions + - Troubleshooting tips + +## Running Tests + +To run the tests again: + +```bash +cd src +npx vitest run core/tools/__tests__/selectActiveIntentTool.spec.ts +``` + +Or run all tests: + +```bash +cd src +npx vitest run +``` + +## Conclusion + +**Phase 1 is fully implemented and tested.** All requirements from `document.md` lines 141-152 have been completed: + +- ✅ Tool definition +- ✅ Context loader with trace entry lookup +- ✅ Prompt engineering +- ✅ Context injection +- ✅ Gatekeeper validation + +The implementation is ready for interim submission documentation. diff --git a/docs/TESTING-PHASE1.md b/docs/TESTING-PHASE1.md new file mode 100644 index 00000000000..e3dc4d54ef3 --- /dev/null +++ b/docs/TESTING-PHASE1.md @@ -0,0 +1,192 @@ +# Phase 1 End-to-End Testing Guide + +This guide helps you test the complete Phase 1 implementation: Intent Selection with Trace Entry Lookup. + +## Automated Tests + +Run the unit tests: + +```bash +cd src +npx vitest run core/tools/__tests__/selectActiveIntentTool.spec.ts +``` + +The test suite verifies: + +- ✅ Intent loading from `active_intents.yaml` +- ✅ Trace entry lookup from `agent_trace.jsonl` +- ✅ XML context generation with recent history +- ✅ Intent filtering (only relevant traces) +- ✅ Error handling for missing intents + +## Manual Testing Workflow + +### Step 1: Prepare Test Environment + +1. **Ensure you have an intent in `active_intents.yaml`:** + +```yaml +active_intents: + - id: INT-001 + name: Test Intent + status: IN_PROGRESS + owned_scope: + - src/test/** + constraints: + - Must follow test patterns + acceptance_criteria: + - All tests pass +``` + +2. **Create a test trace entry in `agent_trace.jsonl`:** + +```json +{ + "id": "trace-1", + "timestamp": "2026-02-18T10:00:00Z", + "vcs": { "revision_id": "abc123" }, + "files": [ + { + "relative_path": "src/test/file1.ts", + "conversations": [ + { + "url": "task-1", + "contributor": { "entity_type": "AI", "model_identifier": "claude-3-5-sonnet" }, + "ranges": [{ "start_line": 10, "end_line": 20, "content_hash": "sha256:hash1" }], + "related": [{ "type": "intent", "value": "INT-001" }] + } + ] + } + ] +} +``` + +### Step 2: Test Intent Selection + +1. **Open VS Code with the Roo Code extension** +2. **Start a new chat/task** +3. **Ask the agent to select an intent:** + +``` +Please select intent INT-001 +``` + +4. **Verify the agent calls `select_active_intent` tool** + +### Step 3: Verify Context Injection + +After the agent calls `select_active_intent`, check: + +1. **The tool result should contain XML context:** + + - `INT-001` + - `Test Intent` + - ``, ``, `` + - `` with trace entries + +2. **The recent history should show:** + - File paths from trace entries + - Line ranges + - Timestamps + +### Step 4: Test Code Writing with Intent + +1. **After intent selection, ask the agent to write code:** + +``` +Now create a test file in src/test/example.test.ts +``` + +2. **Verify:** + - Agent can write code (intent is selected) + - Post-hook logs trace entry to `agent_trace.jsonl` + - New trace entry references INT-001 + +### Step 5: Test Trace Entry Lookup + +1. **Select the same intent again:** + +``` +Select intent INT-001 again +``` + +2. **Verify:** + - The `` now includes the file you just created + - Shows the new trace entry with file path and line ranges + +## Expected Behavior + +### ✅ Success Flow + +1. Agent calls `select_active_intent("INT-001")` +2. Tool loads intent from YAML ✅ +3. Tool fetches trace entries from JSONL ✅ +4. Tool returns XML context with intent + history ✅ +5. Agent receives context and can write code ✅ +6. Post-hook logs new trace entry ✅ +7. Next intent selection includes new trace ✅ + +### ❌ Error Cases + +1. **Missing Intent:** + + - Agent calls `select_active_intent("INT-999")` + - Tool returns error: "Intent not found in active_intents.yaml" + +2. **Missing Parameter:** + + - Agent calls `select_active_intent("")` + - Tool returns missing parameter error + +3. **No Trace Entries:** + - Intent exists but no traces + - XML shows: "No recent changes found for this intent" + +## Verification Checklist + +- [ ] Intent loads from `active_intents.yaml` +- [ ] Trace entries are fetched from `agent_trace.jsonl` +- [ ] XML context includes intent specification +- [ ] XML context includes recent history +- [ ] Trace entries are filtered by intent ID +- [ ] Recent entries are sorted (newest first) +- [ ] Task stores `activeIntentId` and `activeIntent` +- [ ] Error handling works for missing intents +- [ ] Code writing works after intent selection +- [ ] Post-hook logs new trace entries +- [ ] New traces appear in next intent selection + +## Troubleshooting + +### Issue: Trace entries not appearing + +**Check:** + +- `agent_trace.jsonl` exists and is readable +- Trace entries have `related` array with `type: "intent"` and matching `value` +- JSON is valid (one entry per line) + +### Issue: Intent not found + +**Check:** + +- `active_intents.yaml` exists in `.orchestration/` +- YAML syntax is valid +- Intent ID matches exactly (case-sensitive) + +### Issue: XML context missing history + +**Check:** + +- Trace entries reference the correct intent ID +- `getTraceEntriesForIntent()` is being called +- Trace entries have valid timestamps + +## Next Steps + +After verifying Phase 1 works: + +1. ✅ Phase 1 Complete +2. Generate PDF report for interim submission +3. Document architectural decisions +4. Create diagrams of hook system diff --git a/docs/UI-Blocking-Authorization.md b/docs/UI-Blocking-Authorization.md new file mode 100644 index 00000000000..8c9ea24d387 --- /dev/null +++ b/docs/UI-Blocking-Authorization.md @@ -0,0 +1,201 @@ +# UI-Blocking Authorization Explained + +## What is UI-Blocking Authorization? + +**UI-Blocking Authorization** is a security mechanism that **pauses the execution flow** and **waits for explicit user approval** before allowing a potentially dangerous operation to proceed. The term "blocking" means the code execution **stops and waits** until the user responds - it cannot continue until the user makes a decision. + +## Key Characteristics + +### 1. **Execution Pauses** + +- The JavaScript Promise chain **stops** at the authorization point +- No code executes until the user responds +- The entire extension waits for user input + +### 2. **Modal Dialog** + +- A dialog appears that **must be dismissed** before continuing +- User cannot interact with other parts of the application +- Forces explicit decision: Approve or Reject + +### 3. **Synchronous Decision** + +- The authorization function returns a boolean (`true`/`false`) +- Code flow branches based on the user's decision +- If rejected, operation is cancelled immediately + +## How It Works in Your Hook System + +### Current Flow (Without UI-Blocking Authorization) + +``` +Agent wants to write file + ↓ +Pre-Hook checks intent (automatic, no user input) + ↓ +Tool executes immediately + ↓ +User sees result after the fact +``` + +### With UI-Blocking Authorization + +``` +Agent wants to write file + ↓ +Pre-Hook checks intent + ↓ +⚠️ SHOW MODAL DIALOG - EXECUTION PAUSES ⚠️ + ↓ +User sees: "Intent Evolution Request: INT-001 wants to modify src/auth.ts" + ↓ +User clicks: [Approve] or [Reject] + ↓ +IF APPROVED: Tool executes +IF REJECTED: Operation cancelled, error sent to LLM +``` + +## Implementation Example + +### Non-Blocking (Current System) + +```typescript +// This doesn't block - execution continues immediately +async function checkPermission() { + // Some validation logic + return true // Returns immediately +} + +// Code continues regardless +await checkPermission() +doSomething() // Executes right away +``` + +### UI-Blocking (What You Need) + +```typescript +// This BLOCKS - execution waits for user +async function requestApproval(): Promise { + // Show modal dialog - execution STOPS here + const answer = await vscode.window.showWarningMessage( + "Approve this operation?", + { modal: true }, // ← This makes it BLOCKING + "Approve", + "Reject", + ) + + // Code only reaches here AFTER user clicks a button + return answer === "Approve" +} + +// Execution PAUSES at this line +const approved = await requestApproval() + +// This only runs AFTER user responds +if (approved) { + doSomething() +} else { + cancelOperation() +} +``` + +## Why "Blocking" Matters + +### Without Blocking (Non-Modal) + +```typescript +// Dialog appears but code continues +vscode.window.showWarningMessage("Warning!") // Returns immediately +doSomething() // Executes while dialog is still showing! +``` + +### With Blocking (Modal) + +```typescript +// Dialog appears and code STOPS +const answer = await vscode.window.showWarningMessage( + "Warning!", + { modal: true }, // Code waits here +) +// Code only continues after user clicks +doSomething() // Only runs after dialog is dismissed +``` + +## In Your Architecture Specification + +From `document.md` line 156: + +> **UI-Blocking Authorization:** Identify existing logic to pause the Promise chain. Your hook will trigger `vscode.window.showWarningMessage` with "Approve/Reject" to update core intent evolution. + +This means: + +1. **Pause the Promise chain**: Use `await` with a modal dialog +2. **Trigger showWarningMessage**: Use VS Code's built-in dialog +3. **Approve/Reject buttons**: Give user explicit choices +4. **Update intent evolution**: Only proceed if user approves the intent change + +## Real-World Analogy + +Think of it like a **security checkpoint**: + +- **Non-blocking**: Security guard shouts "Stop!" but you keep walking +- **Blocking**: Security guard physically blocks the path - you **must** stop and show ID before proceeding + +## Implementation in HookEngine + +Here's how it works in your `preHook`: + +```typescript +async preHook(toolName: ToolName, toolUse: ToolUse, task: Task): Promise { + // ... validation checks ... + + // ⚠️ BLOCKING POINT - Execution stops here + const approved = await vscode.window.showWarningMessage( + `Intent ${intentId} wants to ${toolName}`, + { modal: true }, // ← This makes it blocking + "Approve", + "Reject" + ) + + // Code only reaches here AFTER user clicks + if (approved === "Approve") { + return { shouldProceed: true } + } else { + return { + shouldProceed: false, + errorMessage: "Operation rejected by user" + } + } +} +``` + +## Key Difference from Current System + +### Current Roo Code Approval System + +- Uses webview-based approval (non-blocking in extension host) +- Can be auto-approved based on settings +- Approval happens in the UI layer, not in the hook + +### Your Hook System (UI-Blocking) + +- Uses VS Code native modal dialog (truly blocking) +- Happens **before** tool execution (in pre-hook) +- **Cannot** be bypassed - user must explicitly approve +- Execution **stops** until user responds + +## Benefits + +1. **Security**: User cannot accidentally approve dangerous operations +2. **Control**: User has explicit control over intent evolution +3. **Transparency**: User sees exactly what intent is requesting +4. **Trust**: Builds trust by requiring explicit approval for changes + +## Summary + +**UI-Blocking Authorization** = A modal dialog that **stops code execution** until the user explicitly approves or rejects an operation. It's the difference between: + +- ❌ "Here's a notification, but I'll continue anyway" +- ✅ "STOP. You must approve before I continue" + +In your hook system, this ensures that **no code changes happen** without explicit user approval for intent evolution. diff --git a/document.md b/document.md new file mode 100644 index 00000000000..eb3f2450216 --- /dev/null +++ b/document.md @@ -0,0 +1,237 @@ +TRP1 Challenge Week 1: Architecting the AI-Native IDE & Intent-Code Traceability + +The Business Objective +Software engineering is transitioning from manual syntax generation to the orchestration of silicon workers. In this new era, the primary bottleneck is not writing code, but Governance and Context Management. +The Problem: +Traditional version control (Git) was built for humans. It tracks what changes (lines of text) and when, but it is completely blind to Why (Intent) and Structural Identity (Abstract Syntax Tree or AST). +When an AI agent modifies 50 files to "Refactor Auth Middleware," Git sees 50 unrelated text diffs. It cannot distinguish between a semantic refactor (Intent Preservation) and a feature addition (Intent Evolution). Furthermore, "Vibe Coding"—where developers blindly accept AI output without rigorous architectural constraints—leads to massive technical debt and "Context Rot." +The Master Thinker Philosophy: +To pass this challenge, you must adopt the mindset of an AI Master Thinker, modeled after industry leaders: +Boris Cherny (Anthropic): Runs 15+ concurrent agent sessions, treating them as specialized workers (Architect, Builder, Tester). He enforces a "Plan-First" strategy and uses a shared brain to prevent drift. +The Cursor Team: Builds environments where the IDE acts as a manager, not just a text editor. +Cognitive Debt +Before writing code, you must internalize why we are building this. As AI generates code at superhuman speed, we face two new forms of debt: +Cognitive Debt: When knowledge loses its "stickiness" because humans are skimming AI output rather than deeply understanding it. +Trust Debt: The gap between what the system produces and what we can verify. +Your architecture is the repayment mechanism for this debt. By enforcing Intent-Code Traceability, you replace blind trust with cryptographic verification. By creating Living Documentation, you prevent active knowledge decay. +Your Goal: +You will not build a chat bot. You will act as a Forward Deployed Engineer (FDE) to upgrade an existing open-source AI Agent (Roo Code or Cline) into a governed AI-Native IDE. +You will instrument this extension with a Deterministic Hook System that intercepts every tool execution to: +Enforce Context: Inject high-level architectural constraints via Sidecar files. +Trace Intent: Implement an AI-Native Git layer that links Business Intent -> Code AST -> Agent Action. +Automate Governance: Ensure documentation and attribution evolve in real-time as a side-effect of the code. + +Mandatory Research & Conceptual Foundation +You are expected to engineer solutions based on these specific philosophies. Read these before writing code. +Context Engineering: Exploring Gen AI: Context Engineering for Coding Agents +Key Takeaway: How to curate the context window to prevent "Context Rot." +AI-Native Version Control: AI-Native Git Version Control & Git-AI Project +Key Takeaway: Moving from line-based diffs to Intent-AST correlation. +Agentic Workflows: Claude Code Playbook (Boris Cherny) +Key Takeaway: Running parallel agents (Architect vs. Builder) and using a "Shared Brain." +Prior Art: Entire.io CLI and Custard Seed. +On Cognitive Debt +Cognitive Debt – Understand what happens when we stop "doing the work." +Trust, Care, and What’s Lost in Abstraction – The difference between human care and machine output. +On Intent Formalization: +Intent Formalization – How to define intent mathematically. +Formal Intent Theory +AISpec. +AI-assisted reverse engineering to reconstruct functional specifications from UI elements, binaries, and data lineage to overcome analysis paralysis. Black Box to Blueprint. + +The Architecture Specification +You will fork Roo Code (Recommended) or Cline. You will inject a hook system that maintains a strictly defined .orchestration/ directory in the user's workspace. +The Hook Engine & Middleware Boundary +The physical architecture must be designed with strict privilege separation. +Webview (UI): Restricted presentation layer. Emits events via postMessage. +Extension Host (Logic): Handles API polling, secret management, and MCP tool execution. +The Hook Engine: Acts as a strict middleware boundary. It intercepts all tool execution requests. At the PreToolUse phase, the engine will enforce intent context injection and Human-in-the-Loop (HITL) authorization. At PostToolUse it will update codebase documentation, state evolution, and intent changes. +To solve the problem of injecting context before the agent has time to analyze the user's request and what it should do, you must architect a Two-Stage State Machine for every turn of the conversation. The Agent is not allowed to write code immediately; it must first "checkout" an intent. +The Execution Flow: +State 1: The Request. User prompts: "Refactor the auth middleware." +State 2: The Reasoning Intercept (The Handshake). +The Agent analyzes the request, identifies an intent ids, and calls a mandatory tool: select_active_intent(intent_id). +The Pre-Hook Intercepts this call. It pauses the execution loop. +The Hook queries the Data Model for the selected intent's constraints, related files, and recent history for the identified intent IDs. +The Hook injects this deep context into the immediate prompt and resumes execution. +State 3: Contextualized Action. +The Agent, now possessing the specific context, calls LLM to generate required changes and calls write_file. +The Post-Hook Intercepts. It calculates the content_hash and logs the trace, linking the code back to the intent_id selected in State 2. +The Data Model +You will implement a Sidecar storage pattern in .orchestration/. These files are machine-managed. These data-models are essentials only. Based on your capability and architecture you might prefer to store the data in SQLite or other high performant local databases such as Alibaba Open-Sources Zvec + +1. .orchestration/active_intents.yaml (The Intent Specification) + Inspired by Spec-Driven Development and AISpec, this file treats the codebase as a collection of formalized intents, not just text files. + Purpose: Tracks the lifecycle of business requirements. Not all code changes are equal; this file tracks why we are working. + Update Pattern: Updated via Pre-Hooks (when an agent picks a task) and Post-Hooks (when a task is complete). + Structure: + active_intents: + +- id: "INT-001" + name: "JWT Authentication Migration" + status: "IN_PROGRESS" + # Formal Scope Definition (Crucial for Parallelism) + owned_scope: + - "src/auth/\*\*" + - "src/middleware/jwt.ts" + constraints: + - "Must not use external auth providers" + - "Must maintain backward compatibility with Basic Auth" + # The "Definition of Done" + acceptance_criteria: + - "Unit tests in tests/auth/ pass" + +1. .orchestration/agent_trace.jsonl (The Ledger) + Purpose: An append-only, machine-readable history of every mutating action, linking the abstract Intent to the concrete Code Hash. + Update Pattern: Updated via Post-Hook after file writes. + Schema Requirement: You must implement the full Agent Trace specification to ensure spatial independence via content hashing. + { + "id": "uuid-v4", + "timestamp": "2026-02-16T12:00:00Z", + "vcs": { "revision_id": "git_sha_hash" }, + "files": [ + { + "relative_path": "src/auth/middleware.ts", + "conversations": [ + { + "url": "session_log_id", + "contributor": { + "entity_type": "AI", + "model_identifier": "claude-3-5-sonnet" + }, + "ranges": [ + { + "start_line": 15, + "end_line": 45, + // CRITICAL: Spatial Independence. + "content_hash": "sha256:a8f5f167f44f4964e6c998dee827110c" + } + ], + // CRITICAL: The Golden Thread to SpecKit + "related": [ + { + "type": "specification", + "value": "REQ-001" + } + ] + } + ] + } + ] + } + +Content Hashing: You must compute a hash of the modified code block to ensure spatial independence. If lines move, the hash remains valid. + +3. .orchestration/intent_map.md (The Spatial Map) + Purpose: Maps high-level business intents to physical files and AST nodes. When a manager asks, "Where is the billing logic?", this file provides the answer. + Update Pattern: Incrementally updated when INTENT_EVOLUTION occurs. +4. AGENT.md or CLAUDE.md (The Shared Brain) + Purpose: A persistent knowledge base shared across parallel sessions (Architect/Builder/Tester). Contains "Lessons Learned" and project-specific stylistic rules. + Update Pattern: Incrementally appended when verification loops fail or architectural decisions are made. + +Implementation Curriculum +The following guides are indicatory. You may not achieve a robust solution implementing only these phases. You must architect a full working solution and implement it based on the actual goal specified. Your innovation, thinking outside the box, and identifying potential gaps and their solutions is necessary. +Phase 0: The Archaeological Dig +Goal: Map the nervous system. +Fork & Run: Get Roo Code or Cline running in the Extension Host. +Trace the Tool Loop: Identify the exact function in the host extension that handles execute_command and write_to_file. +Locate the Prompt Builder: Find where the System Prompt is constructed. You cannot enforce the "Reasoning Loop" if you cannot modify the instructions given to the LLM. +Deliverable: ARCHITECTURE_NOTES.md. + +Phase 1: The Handshake (Reasoning Loop Implementation) +Goal: Solve the Context Paradox. Bridge the synchronous LLM with the asynchronous IDE loop. +Define the Tool: Create a new tool definition: select_active_intent(intent_id: string). +Context Loader (Pre-Hook): Before the extension sends a prompt to the LLM, intercept the payload. Read the corresponding entries in active_intents.yaml, identify related agent trace entries for the active intent the agent is processing, and prepare a consolidated intent context. +Prompt Engineering: Modify the System Prompt to enforce the protocol: +"You are an Intent-Driven Architect. You CANNOT write code immediately. Your first action MUST be to analyze the user request and call select_active_intent to load the necessary context." +Context Injection Hook: +Implement logic that intercepts select_active_intent. +Read active_intents.yaml. +Construct an XML block containing only the constraints and scope for the selected ID. +Return this block as the tool result. +The Gatekeeper: In your Pre-Hook, verify that the agent has declared a valid intent_id. If not, block execution and return an error: "You must cite a valid active Intent ID." +Phase 2: The Hook Middleware & Security Boundary +Goal: Architect the Hook Engine that wraps all tool execution requests and enforce formal boundaries. +Command Classification: Classify commands as Safe (read) or Destructive (write, delete, execute). +UI-Blocking Authorization: Identify existing logic to pause the Promise chain. Your hook will trigger vscode.window.showWarningMessage with "Approve/Reject" to update core intent evolution. Your architecture should allow defining .intentignore like file to exclude changes to certain intents. A simple model to adopt is a codebase is a collection of intents as much as it is a collection of organized code files linked by imports. You may need to develop or adopt a simple intent language see the following references https://arxiv.org/abs/2406.09757 https://github.com/cbora/aispec http://sunnyday.mit.edu/papers/intent-tse.pdf and those that build formal intent specification structures on top of GitHub speckit. +Autonomous Recovery: If rejected, send a standardized JSON tool-error back to the LLM so it can self-correct without crashing. +Scope Enforcement: In the write_file Pre-Hook, check if the target file matches the owned_scope of the active intent. +If valid: Proceed. +If invalid: Block and return: "Scope Violation: REQ-001 is not authorized to edit [filename]. Request scope expansion." +Phase 3: The AI-Native Git Layer (Full Traceability) +Goal: Implement the semantic tracking ledger. Repay Trust Debt with Verification. +Schema Modification: Modify the write_file tool schema to require intent_id and mutation_class. +Semantic Classification: Ensure your system can distinguish between AST_REFACTOR (syntax change, same intent) and INTENT_EVOLUTION (new feature). +Spatial Hashing: Implement a utility to generate SHA-256 hashes of string content. +Trace Serialization: +Create a Post-Hook on write_file. +Construct the JSON object using the Agent Trace Schema defined before. +Crucial: You must inject the REQ-ID (from Phase 1) into the related array and the content_hash into the ranges object. +Append to agent_trace.jsonl. +Phase 4: Parallel Orchestration (The Master Thinker) +Goal: Manage Silicon Workers via Optimistic Locking. +Concurrency Control: +When an agent attempts to write, calculate the hash of the current file on disk. +Compare it to the hash the agent read when it started its turn. +If they differ: A parallel agent (or human) has modified the file. BLOCK the write to prevent overwriting. Return a "Stale File" error and force the agent to re-read. +Lesson Recording: Implement a tool that appends "Lessons Learned" to CLAUDE.md if a verification step (linter/test) fails. + +Proof of Execution (The Demo) +To pass, you must submit a video (max 5 mins) demonstrating the Parallel "Master Thinker" Workflow: +Setup: Open a fresh workspace. Define active_intents.yaml with a simple example of your own - intents generated using GitHub speckit or simple like "INT-001: Build Weather API". +Parallelism: Open two separate instances/chat panels of your extension. +Agent A (Architect): Monitors intent_map.md and defines the plan. +Agent B (Builder): Writes code for INT-001. +The Trace: Have Agent B refactor a file. Show .orchestration/agent_trace.jsonl updating in real-time with the correct AST_REFACTOR classification and content hash. +The Guardrails: Have Agent B try to execute a destructive command or write code without an Intent ID. Show the Pre-Hook blocking it. + +Deliverables +The following are required submissions for both the interim submission on Wednesday and final submission on Saturday. + +Interim Submission - Wednesday 21hr UTC +PDF Report +How the VS Code extension works. +The code and design architecture of the agent in the extension - your note ARCHITECTURE_NOTES.md from Phase 0 +Architectural decisions for the hook +Diagrams and Schemas of the hook system +Submit a GitHub Repository containing: +Your forked extension with a clean src/hooks/ directory. + +Final Submission - Saturday 21hr UTC +PDF Report +Complete report of your implementation with detailed schemas, architecture, and notes. +Detailed breakdown of the Agent flow and your implemented hook +Summary of what has been achieved with all the work done. +The Meta-Audit Video: +Demonstrating the workflow defined in Section 5. +Submit a GitHub Repository containing: +The .orchestration/ Artifacts: +agent_trace.jsonl . +active_intents.yaml +intent_map.md. +The Source Code: +Your forked extension with a clean src/hooks/ directory. + +Evaluation Rubric +The following criterions will play a significant role in assessing the work you will submit. + +Metric +Score 1 (The Vibe Coder) +Score 3 (Competent Tech Lead) +Score 5 (Master Thinker) +Intent-AST Correlation +No machine-readable trace. Relies on standard Git. +Trace file exists but classification is random/inaccurate. +agent_trace.jsonl perfectly maps Intent IDs to Content Hashes. Distinguishes Refactors from Features mathematically. +Context Engineering +State files are handwritten/static. Agent drifts. +Hooks update state, but the architecture is brittle. +Dynamic injection of active_intents.yaml. Agent cannot act without referencing the context DB. Context is curated, not dumped. +Hook Architecture +Logic is stuffed into the main execution loop (spaghetti). +Hooks work but are tightly coupled to the host. +Clean Middleware/Interceptor Pattern. Hooks are isolated, composable, and fail-safe. +Orchestration +Single-threaded only. +Parallel attempts collide. +Parallel Orchestration demonstrated. Shared CLAUDE.md prevents collision. System acts as a "Hive Mind." From dedb07ed426adb4a15f1089bf00ae6c89142ac29 Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 14:01:09 +0300 Subject: [PATCH 04/41] feat: implement intent-governed HookEngine and orchestration data model - Add HookEngine middleware with pre/post-hooks for tool governance - Implement OrchestrationDataModel for .orchestration/ directory management - Create select_active_intent tool enforcing Reasoning Loop protocol - Integrate hooks into presentAssistantMessage for all destructive tools - Add UI-blocking authorization (HITL) for intent evolution - Implement scope enforcement and trace logging with content hashing --- .orchestration/AGENT.md | 36 ++ .orchestration/active_intents.yaml | 222 ++++++++++++ .orchestration/agent_trace.jsonl | 7 + .orchestration/intent_map.md | 19 + packages/types/src/tool.ts | 1 + .../presentAssistantMessage.ts | 60 +++- src/core/hooks/HookEngine.ts | 339 ++++++++++++++++++ .../orchestration/OrchestrationDataModel.ts | 259 +++++++++++++ .../prompts/sections/tool-use-guidelines.ts | 22 ++ src/core/prompts/tools/native-tools/index.ts | 2 + .../native-tools/select_active_intent.ts | 27 ++ src/core/tools/SelectActiveIntentTool.ts | 128 +++++++ src/shared/tools.ts | 2 + 13 files changed, 1116 insertions(+), 8 deletions(-) create mode 100644 .orchestration/AGENT.md create mode 100644 .orchestration/active_intents.yaml create mode 100644 .orchestration/agent_trace.jsonl create mode 100644 .orchestration/intent_map.md create mode 100644 src/core/hooks/HookEngine.ts create mode 100644 src/core/orchestration/OrchestrationDataModel.ts create mode 100644 src/core/prompts/tools/native-tools/select_active_intent.ts create mode 100644 src/core/tools/SelectActiveIntentTool.ts diff --git a/.orchestration/AGENT.md b/.orchestration/AGENT.md new file mode 100644 index 00000000000..be54ed4bb10 --- /dev/null +++ b/.orchestration/AGENT.md @@ -0,0 +1,36 @@ +# Shared Knowledge Base + +This file contains persistent knowledge shared across parallel sessions (Architect/Builder/Tester). Contains "Lessons Learned" and project-specific stylistic rules. + +## Lessons Learned + + + +## Project-Specific Rules + + + +## Architectural Decisions + + + diff --git a/.orchestration/active_intents.yaml b/.orchestration/active_intents.yaml new file mode 100644 index 00000000000..de031ef3b0f --- /dev/null +++ b/.orchestration/active_intents.yaml @@ -0,0 +1,222 @@ +active_intents: + - id: INT-001 + name: INT-001 — Intent-Code Traceability (Spec) + status: IN_PROGRESS + owned_scope: + - src/core/assistant-message/** + - src/core/tools/** + - src/core/hooks/** + - src/core/orchestration/** + - src/core/prompts/** + - .orchestration/** + constraints: + - Must enforce **intent selection before any destructive tool** + (`write_to_file`, `edit_file`, `apply_diff`, etc.). + - "Must keep **privilege separation**: UI emits events; extension host + executes privileged actions; hooks are middleware." + - Must log **spatially independent** traces via content hashing. + acceptance_criteria: + - Agent cannot write code before calling `select_active_intent(intent_id)`. + - "When a file is written, a JSONL entry is appended to + `.orchestration/agent_trace.jsonl` that includes:" + - intent id + - file path + - line range (best-effort) + - "`sha256:` content hash of the modified block" + - "`.orchestration/active_intents.yaml` exists and contains this intent." + created_at: 2026-02-18T08:56:57.063Z + updated_at: 2026-02-18T08:56:57.086Z + spec_hash: sha256:7966563e9a7886587d3c421761708195d8a1ce21addd4632f560965411fd839b + spec_file: specs/INT-001-intent-code-traceability.md + - id: INT-002 + name: INT-002 — Hook System Implementation + status: IN_PROGRESS + owned_scope: + - src/core/hooks/** + - src/core/assistant-message/presentAssistantMessage.ts + - src/core/tools/** + - .orchestration/** + constraints: + - Must integrate with existing `presentAssistantMessage()` function + without breaking current tool execution flow. + - Pre-hooks must run **before** `tool.handle()` is called. + - Post-hooks must run **after** `tool.execute()` completes but before + result is returned. + - Hook system must be non-blocking for non-destructive tools (read-only + operations). + - Must maintain backward compatibility with existing tools. + acceptance_criteria: + - "`HookEngine` class exists in `src/core/hooks/HookEngine.ts`." + - Pre-hook validates intent selection for destructive tools + (`write_to_file`, `edit_file`, `execute_command`, etc.). + - Pre-hook enforces scope validation (file path must be within intent's + `owned_scope`). + - Post-hook logs trace entries to `.orchestration/agent_trace.jsonl` for + mutating actions. + - "`presentAssistantMessage()` integrates `HookEngine` with Pre-Hook and + Post-Hook calls." + - All existing tests pass after hook integration. + created_at: 2026-02-18T08:56:57.094Z + updated_at: 2026-02-18T08:56:57.094Z + spec_hash: sha256:e10e923c607996643684be16016bc8305d7259b543eae623e92b5e49db8b902c + spec_file: specs/INT-002-hook-system-implementation.md + - id: INT-003 + name: INT-003 — Two-Stage Reasoning Loop + status: IN_PROGRESS + owned_scope: + - src/core/hooks/HookEngine.ts + - src/core/prompts/sections/tool-use-guidelines.ts + - src/core/tools/SelectActiveIntentTool.ts + - src/core/task/Task.ts + constraints: + - "**Stage 1 (Reasoning Intercept):** Agent MUST call + `select_active_intent(intent_id)` before any destructive tool." + - "**Stage 2 (Contextualized Action):** Agent receives intent context and + must include it when making code changes." + - System prompt must enforce this protocol in tool-use guidelines. + - Intent context must be injected into the agent's context before code + generation. + acceptance_criteria: + - System prompt includes instructions requiring `select_active_intent` + before code changes. + - "`SelectActiveIntentTool` returns XML `` block with + scope, constraints, and acceptance criteria." + - Pre-hook blocks destructive tools if no active intent is selected. + - Agent receives intent context in subsequent tool calls. + - Intent context is logged in `agent_trace.jsonl` entries. + created_at: 2026-02-18T08:56:57.098Z + updated_at: 2026-02-18T08:56:57.098Z + spec_hash: sha256:a75817698c5b1479c68e43dd41b04752d3a6df7c4af71f3ab60fdedf705e4dda + spec_file: specs/INT-003-reasoning-loop.md + - id: INT-004 + name: INT-004 — Orchestration Directory Management + status: IN_PROGRESS + owned_scope: + - src/core/orchestration/OrchestrationDataModel.ts + - .orchestration/active_intents.yaml + - .orchestration/agent_trace.jsonl + - .orchestration/intent_map.md + - .orchestration/AGENT.md + constraints: + - "`.orchestration/` directory must be machine-managed (not user-edited + directly)." + - "`active_intents.yaml` must be valid YAML and follow the schema defined + in `document.md`." + - "`agent_trace.jsonl` must be append-only (no modifications, only + appends)." + - All file operations must be atomic (write to temp file, then rename). + - Directory and files must be initialized on first use. + acceptance_criteria: + - "`OrchestrationDataModel` class provides methods:" + - "`initialize()`: Creates directory and initializes files if missing." + - "`readActiveIntents()`: Parses and returns active intents." + - "`appendAgentTrace()`: Appends trace entry to JSONL file." + - "`updateIntentMap()`: Updates intent-to-file mapping." + - "`appendAgentKnowledge()`: Appends to AGENT.md." + - All methods handle errors gracefully and log failures. + - Files are created with proper templates if missing. + - YAML parsing validates schema and reports errors clearly. + created_at: 2026-02-18T08:56:57.099Z + updated_at: 2026-02-18T08:56:57.099Z + spec_hash: sha256:659bd435cecc3223171c3fce81f671c26baac9ce354c9a6e3c967164983ed9fb + spec_file: specs/INT-004-orchestration-directory.md + - id: INT-005 + name: INT-005 — Logging & Traceability + status: IN_PROGRESS + owned_scope: + - src/core/hooks/HookEngine.ts` (Post-Hook implementation) + - src/core/orchestration/OrchestrationDataModel.ts + - .orchestration/agent_trace.jsonl + - src/utils/git.ts` (for VCS revision tracking) + constraints: + - Trace entries must include `sha256:` content hash of modified code + blocks. + - Line ranges must be best-effort (may be approximate for complex edits). + - "Each trace entry must link to:" + - Intent ID + - File path (relative to workspace root) + - VCS revision (Git SHA) + - Timestamp + - Model identifier + - Content hashing must be spatially independent (same code block = same + hash regardless of file location). + acceptance_criteria: + - Post-hook computes SHA-256 hash of modified content for file tools. + - "Trace entry includes all required fields per `document.md` schema:" + - "`id` (UUID)" + - "`timestamp` (ISO 8601)" + - "`vcs.revision_id` (Git SHA)" + - "`files[]` with `relative_path`, `conversations[]`, `ranges[]`, + `content_hash`" + - Trace entries are appended atomically to `agent_trace.jsonl`. + - "Content hash format: `sha256:`." + - Git SHA is retrieved from workspace root (handles non-Git repos + gracefully). + created_at: 2026-02-18T08:56:57.099Z + updated_at: 2026-02-18T08:56:57.099Z + spec_hash: sha256:2b3421a22c9e27a817e27aea652f3332cdbc821338b52e112ff654ff88c36317 + spec_file: specs/INT-005-logging-traceability.md + - id: INT-006 + name: INT-006 — Testing & Validation + status: IN_PROGRESS + owned_scope: + - src/core/hooks/**/*.test.ts + - src/core/orchestration/**/*.test.ts + - src/core/tools/SelectActiveIntentTool.test.ts + - tests/integration/hook-system.test.ts + - tests/e2e/intent-traceability.test.ts + constraints: + - Tests must not modify production `.orchestration/` files (use temp + directories). + - Tests must be deterministic and isolated (no shared state). + - Integration tests must verify hook system works with real tool execution. + - E2E tests must simulate full agent workflow (intent selection → code + change → trace logging). + acceptance_criteria: + - Unit tests for `HookEngine.preHook()` and `HookEngine.postHook()`. + - Unit tests for `OrchestrationDataModel` file operations. + - Unit tests for `SelectActiveIntentTool` intent loading and context + generation. + - "Integration test: Verify Pre-Hook blocks destructive tool without + intent." + - "Integration test: Verify Post-Hook logs trace entry after file write." + - "E2E test: Full workflow from intent selection to trace logging." + - All tests pass in CI/CD pipeline. + - Test coverage > 80% for hook and orchestration modules. + created_at: 2026-02-18T08:56:57.099Z + updated_at: 2026-02-18T08:56:57.100Z + spec_hash: sha256:f8343d2839370244e2f1d7b6622494a96438c86b21f42b98b159eb34e33a59c6 + spec_file: specs/INT-006-testing-validation.md + - id: INT-007 + name: INT-007 — Documentation & Knowledge Base + status: IN_PROGRESS + owned_scope: + - ARCHITECTURE_NOTES.md + - README.md` (Intent-Code Traceability section) + - .orchestration/AGENT.md + - docs/intent-traceability/ + - CHANGELOG.md` (relevant entries) + constraints: + - "`ARCHITECTURE_NOTES.md` must document all injection points and hook + integration." + - '`AGENT.md` must be append-only knowledge base for "Lessons Learned".' + - Documentation must be kept in sync with code changes. + - API documentation must include examples for each public method. + acceptance_criteria: + - "`ARCHITECTURE_NOTES.md` includes:" + - Tool execution flow diagram + - Hook injection points with line numbers + - System prompt modification points + - Data model schemas + - "`AGENT.md` includes:" + - Lessons learned from implementation + - Common pitfalls and solutions + - Performance optimizations + - Stylistic rules for intent specifications + - README includes setup instructions and usage examples. + - All public APIs are documented with JSDoc comments. + - Documentation is reviewed and updated with each major change. + created_at: 2026-02-18T08:56:57.100Z + updated_at: 2026-02-18T08:56:57.100Z + spec_hash: sha256:50566c7bdbddce41c4f739cab9631172321f2880e8cb7a35fdf8c0d1a1aa56b4 + spec_file: specs/INT-007-documentation.md diff --git a/.orchestration/agent_trace.jsonl b/.orchestration/agent_trace.jsonl new file mode 100644 index 00000000000..f831a22779b --- /dev/null +++ b/.orchestration/agent_trace.jsonl @@ -0,0 +1,7 @@ +# Agent Trace Ledger (JSONL format - one JSON object per line) +# Append-only, machine-readable history of every mutating action. +# Links abstract Intent to concrete Code Hash for spatial independence. +# +# Example entry: +# {"id":"trace-1234567890-abc","timestamp":"2026-02-16T12:00:00Z","vcs":{"revision_id":"abc123def456"},"files":[{"relative_path":"src/auth/middleware.ts","conversations":[{"url":"task-xyz","contributor":{"entity_type":"AI","model_identifier":"claude-3-5-sonnet"},"ranges":[{"start_line":15,"end_line":45,"content_hash":"sha256:a8f5f167f44f4964e6c998dee827110c"}],"related":[{"type":"intent","value":"INT-001"}]}]}]} + diff --git a/.orchestration/intent_map.md b/.orchestration/intent_map.md new file mode 100644 index 00000000000..df107baa860 --- /dev/null +++ b/.orchestration/intent_map.md @@ -0,0 +1,19 @@ +# Intent Map + +This file maps high-level business intents to physical files and AST nodes. When a manager asks, "Where is the billing logic?", this file provides the answer. + +## Intents + + + diff --git a/packages/types/src/tool.ts b/packages/types/src/tool.ts index 4f90b63e9fc..3655a5f29ed 100644 --- a/packages/types/src/tool.ts +++ b/packages/types/src/tool.ts @@ -46,6 +46,7 @@ export const toolNames = [ "skill", "generate_image", "custom_tool", + "select_active_intent", ] as const export const toolNamesSchema = z.enum(toolNames) diff --git a/src/core/assistant-message/presentAssistantMessage.ts b/src/core/assistant-message/presentAssistantMessage.ts index 7f5862be154..708cae5f292 100644 --- a/src/core/assistant-message/presentAssistantMessage.ts +++ b/src/core/assistant-message/presentAssistantMessage.ts @@ -37,9 +37,11 @@ import { generateImageTool } from "../tools/GenerateImageTool" import { applyDiffTool as applyDiffToolClass } from "../tools/ApplyDiffTool" import { isValidToolName, validateToolUse } from "../tools/validateToolUse" import { codebaseSearchTool } from "../tools/CodebaseSearchTool" +import { selectActiveIntentTool } from "../tools/SelectActiveIntentTool" import { formatResponse } from "../prompts/responses" import { sanitizeToolUseId } from "../../utils/tool-id" +import { HookEngine } from "../hooks/HookEngine" /** * Processes and presents assistant message content to the user interface. @@ -675,15 +677,45 @@ export async function presentAssistantMessage(cline: Task) { } } + // Initialize hook engine for this task + const hookEngine = new HookEngine(cline.cwd) + await hookEngine.initialize() + + // Pre-Hook: Intercept tool execution + const preHookResult = await hookEngine.preHook(block.name as ToolName, block, cline) + if (!preHookResult.shouldProceed) { + pushToolResult(formatResponse.toolError(preHookResult.errorMessage || "Tool execution blocked by hook")) + break + } + switch (block.name) { - case "write_to_file": - await checkpointSaveAndMark(cline) - await writeToFileTool.handle(cline, block as ToolUse<"write_to_file">, { + case "select_active_intent": + await selectActiveIntentTool.handle(cline, block as ToolUse<"select_active_intent">, { askApproval, handleError, pushToolResult, }) break + case "write_to_file": + await checkpointSaveAndMark(cline) + let writeSuccess = false + let writeResult: string | undefined + try { + await writeToFileTool.handle(cline, block as ToolUse<"write_to_file">, { + askApproval, + handleError, + pushToolResult: (result) => { + writeResult = typeof result === "string" ? result : JSON.stringify(result) + pushToolResult(result) + }, + }) + writeSuccess = true + } catch (error) { + writeSuccess = false + } + // Post-Hook: Log trace entry + await hookEngine.postHook(block.name as ToolName, block, cline, writeSuccess, writeResult) + break case "update_todo_list": await updateTodoListTool.handle(cline, block as ToolUse<"update_todo_list">, { askApproval, @@ -718,11 +750,23 @@ export async function presentAssistantMessage(cline: Task) { break case "edit_file": await checkpointSaveAndMark(cline) - await editFileTool.handle(cline, block as ToolUse<"edit_file">, { - askApproval, - handleError, - pushToolResult, - }) + let editSuccess = false + let editResult: string | undefined + try { + await editFileTool.handle(cline, block as ToolUse<"edit_file">, { + askApproval, + handleError, + pushToolResult: (result) => { + editResult = typeof result === "string" ? result : JSON.stringify(result) + pushToolResult(result) + }, + }) + editSuccess = true + } catch (error) { + editSuccess = false + } + // Post-Hook: Log trace entry + await hookEngine.postHook(block.name as ToolName, block, cline, editSuccess, editResult) break case "apply_patch": await checkpointSaveAndMark(cline) diff --git a/src/core/hooks/HookEngine.ts b/src/core/hooks/HookEngine.ts new file mode 100644 index 00000000000..99fdf9aa062 --- /dev/null +++ b/src/core/hooks/HookEngine.ts @@ -0,0 +1,339 @@ +import { Task } from "../task/Task" +import type { ToolUse, ToolName } from "../../shared/tools" +import { OrchestrationDataModel, type ActiveIntent } from "../orchestration/OrchestrationDataModel" +import * as vscode from "vscode" +import * as path from "path" +import * as fs from "fs/promises" +import { execSync } from "child_process" + +/** + * Hook execution result + */ +export interface HookResult { + shouldProceed: boolean + errorMessage?: string + injectedContext?: string +} + +/** + * Hook Engine - Middleware boundary for tool execution + * Implements Pre-Hook and Post-Hook interception + */ +export class HookEngine { + private dataModel: OrchestrationDataModel + + constructor(workspaceRoot: string) { + this.dataModel = new OrchestrationDataModel(workspaceRoot) + } + + /** + * UI-blocking authorization (HITL): pause execution until the user approves/rejects. + * + * We intentionally make this a modal dialog to "pause the Promise chain" as required by `document.md`. + * To avoid excessive prompts, we authorize once per intent per task session. + */ + private async ensureIntentAuthorized( + task: Task, + intent: ActiveIntent, + toolName: ToolName, + details?: { filePath?: string; command?: string }, + ): Promise<{ approved: boolean; message?: string }> { + const approvedSetKey = "__approvedIntentIds" as const + const approved = ((task as any)[approvedSetKey] ?? []) as string[] + + // Authorize once per intent per task session. + if (approved.includes(intent.id)) { + return { approved: true } + } + + const detailLines: string[] = [] + if (details?.filePath) detailLines.push(`File: ${details.filePath}`) + if (details?.command) detailLines.push(`Command: ${details.command}`) + if (detailLines.length === 0) detailLines.push(`Tool: ${toolName}`) + + const message = + `Approve intent evolution for this task?\n\n` + + `Intent: ${intent.id} — ${intent.name}\n` + + detailLines.join("\n") + + `\n\nThis will allow destructive actions under this intent for the current task session.` + + const answer = await vscode.window.showWarningMessage(message, { modal: true }, "Approve", "Reject") + + if (answer !== "Approve") { + return { approved: false, message: "User rejected the intent evolution request." } + } + + ;(task as any)[approvedSetKey] = [...approved, intent.id] + return { approved: true } + } + + /** + * Initialize orchestration directory + */ + async initialize(): Promise { + await this.dataModel.initialize() + } + + /** + * Pre-Hook: Intercept tool execution before it happens + * Enforces intent context injection and scope validation + */ + async preHook(toolName: ToolName, toolUse: ToolUse, task: Task): Promise { + // Check if this is select_active_intent - allow it through + if (toolName === "select_active_intent") { + return { shouldProceed: true } + } + + // For all other tools, check if active intent is set + const activeIntentId = (task as any).activeIntentId as string | undefined + let activeIntent = (task as any).activeIntent as ActiveIntent | undefined + + // Destructive tools require intent selection + const destructiveTools: ToolName[] = [ + "write_to_file", + "edit_file", + "apply_diff", + "apply_patch", + "edit", + "search_replace", + "search_and_replace", + "execute_command", + ] + + if (destructiveTools.includes(toolName)) { + if (!activeIntentId) { + return { + shouldProceed: false, + errorMessage: + "You must cite a valid active Intent ID. Call select_active_intent(intent_id) before making code changes.", + } + } + + // Load intent details (for authorization prompt + scope checks) + if (!activeIntent) { + activeIntent = await this.dataModel.getIntent(activeIntentId) + if (activeIntent) { + ;(task as any).activeIntent = activeIntent + } + } + + if (!activeIntent) { + return { + shouldProceed: false, + errorMessage: `Intent "${activeIntentId}" not found in active_intents.yaml. Please select a valid intent ID.`, + } + } + + // Validate scope for write operations + if (toolName === "write_to_file" || toolName === "edit_file") { + const filePath = (toolUse.params as any).path as string | undefined + if (filePath) { + const scopeValid = await this.validateScope(activeIntentId, filePath, task.cwd) + if (!scopeValid.valid) { + return { + shouldProceed: false, + errorMessage: `Scope Violation: ${activeIntentId} is not authorized to edit ${filePath}. ${scopeValid.message}`, + } + } + + // UI-blocking authorization (HITL) + const auth = await this.ensureIntentAuthorized(task, activeIntent, toolName, { filePath }) + if (!auth.approved) { + return { + shouldProceed: false, + errorMessage: auth.message || "Operation rejected by user.", + } + } + } + } else if (toolName === "execute_command") { + const command = (toolUse.params as any).command as string | undefined + const auth = await this.ensureIntentAuthorized(task, activeIntent, toolName, { command }) + if (!auth.approved) { + return { + shouldProceed: false, + errorMessage: auth.message || "Operation rejected by user.", + } + } + } else { + // Other destructive tools: still require UI-blocking authorization. + const auth = await this.ensureIntentAuthorized(task, activeIntent, toolName) + if (!auth.approved) { + return { + shouldProceed: false, + errorMessage: auth.message || "Operation rejected by user.", + } + } + } + } + + return { shouldProceed: true } + } + + /** + * Post-Hook: Execute after tool completes + * Updates trace logs and intent state + */ + async postHook(toolName: ToolName, toolUse: ToolUse, task: Task, success: boolean, result?: string): Promise { + const activeIntentId = (task as any).activeIntentId as string | undefined + + // Only log destructive operations + const destructiveTools: ToolName[] = [ + "write_to_file", + "edit_file", + "apply_diff", + "apply_patch", + "edit", + "search_replace", + "search_and_replace", + ] + + if (destructiveTools.includes(toolName) && activeIntentId && success) { + await this.logTraceEntry(toolName, toolUse, task, activeIntentId, result) + } + } + + /** + * Validate that a file path is within the intent's owned scope + */ + private async validateScope( + intentId: string, + filePath: string, + workspaceRoot: string, + ): Promise<{ valid: boolean; message?: string }> { + try { + const intent = await this.dataModel.getIntent(intentId) + if (!intent) { + return { valid: false, message: "Intent not found" } + } + + const normalizedPath = path.normalize(filePath) + const absolutePath = path.resolve(workspaceRoot, normalizedPath) + + // Check if file matches any scope pattern + for (const scopePattern of intent.owned_scope) { + // Simple glob matching (can be enhanced with minimatch later) + if (this.matchesPattern(normalizedPath, scopePattern)) { + return { valid: true } + } + } + + return { + valid: false, + message: `File is outside intent scope. Request scope expansion or use a different intent.`, + } + } catch (error) { + console.error("Scope validation error:", error) + return { valid: true } // Fail open on error + } + } + + /** + * Simple pattern matching (supports ** and *) + */ + private matchesPattern(filePath: string, pattern: string): boolean { + // Convert glob pattern to regex + const regexPattern = pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\//g, "\\/") + const regex = new RegExp(`^${regexPattern}$`) + return regex.test(filePath) + } + + /** + * Log trace entry to agent_trace.jsonl + */ + private async logTraceEntry( + toolName: ToolName, + toolUse: ToolUse, + task: Task, + intentId: string, + result?: string, + ): Promise { + try { + // Get current git revision + let gitRevision = "unknown" + try { + gitRevision = execSync("git rev-parse HEAD", { cwd: task.cwd, encoding: "utf-8" }).trim() + } catch { + // Git not available or not a git repo + } + + // Extract file path and content from tool params + const params = toolUse.params as any + const filePath = params.path as string | undefined + + if (!filePath) { + return // Can't log without file path + } + + // Read file content to compute hash + const absolutePath = path.resolve(task.cwd, filePath) + let fileContent = "" + let startLine = 1 + let endLine = 1 + + try { + fileContent = await fs.readFile(absolutePath, "utf-8") + const lines = fileContent.split("\n") + endLine = lines.length + + // If we have line numbers in params, use them + if (params.start_line !== undefined && params.end_line !== undefined) { + startLine = params.start_line + endLine = params.end_line + } + } catch { + // File doesn't exist or can't be read + return + } + + // Extract relevant code block + const lines = fileContent.split("\n") + const relevantLines = lines.slice(Math.max(0, startLine - 1), endLine) + const codeBlock = relevantLines.join("\n") + const contentHash = this.dataModel.computeContentHash(codeBlock) + + // Get model identifier from task + const modelId = task.api.getModel().id + + // Build trace entry + const traceEntry = { + id: `trace-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`, + timestamp: new Date().toISOString(), + vcs: { + revision_id: gitRevision, + }, + files: [ + { + relative_path: filePath, + conversations: [ + { + url: `task-${task.taskId}`, + contributor: { + entity_type: "AI" as const, + model_identifier: modelId, + }, + ranges: [ + { + start_line: startLine, + end_line: endLine, + content_hash: `sha256:${contentHash}`, + }, + ], + related: [ + { + type: "intent" as const, + value: intentId, + }, + ], + }, + ], + }, + ], + } + + await this.dataModel.appendTraceEntry(traceEntry) + } catch (error) { + console.error("Failed to log trace entry:", error) + // Don't throw - logging failures shouldn't break tool execution + } + } +} diff --git a/src/core/orchestration/OrchestrationDataModel.ts b/src/core/orchestration/OrchestrationDataModel.ts new file mode 100644 index 00000000000..f6ab3053b80 --- /dev/null +++ b/src/core/orchestration/OrchestrationDataModel.ts @@ -0,0 +1,259 @@ +import * as fs from "fs/promises" +import * as path from "path" +import * as crypto from "crypto" +import * as yaml from "yaml" + +/** + * Intent specification structure matching the architecture spec + */ +export interface ActiveIntent { + id: string + name: string + status: "TODO" | "IN_PROGRESS" | "DONE" | "BLOCKED" + owned_scope: string[] + constraints: string[] + acceptance_criteria: string[] + created_at?: string + updated_at?: string +} + +export interface ActiveIntentsData { + active_intents: ActiveIntent[] +} + +/** + * Agent trace entry structure matching the architecture spec + */ +export interface AgentTraceRange { + start_line: number + end_line: number + content_hash: string +} + +export interface AgentTraceConversation { + url: string + contributor: { + entity_type: "AI" | "HUMAN" + model_identifier?: string + } + ranges: AgentTraceRange[] + related: Array<{ + type: "specification" | "intent" | "requirement" + value: string + }> +} + +export interface AgentTraceFile { + relative_path: string + conversations: AgentTraceConversation[] +} + +export interface AgentTraceEntry { + id: string + timestamp: string + vcs: { + revision_id: string + } + files: AgentTraceFile[] +} + +/** + * Orchestration Data Model + * Manages the .orchestration/ directory and its files + */ +export class OrchestrationDataModel { + private orchestrationDir: string + + constructor(workspaceRoot: string) { + this.orchestrationDir = path.join(workspaceRoot, ".orchestration") + } + + /** + * Initialize the .orchestration/ directory structure + */ + async initialize(): Promise { + try { + await fs.mkdir(this.orchestrationDir, { recursive: true }) + + // Initialize active_intents.yaml if it doesn't exist + const intentsPath = path.join(this.orchestrationDir, "active_intents.yaml") + try { + await fs.access(intentsPath) + } catch { + // File doesn't exist, create it + const initialData: ActiveIntentsData = { active_intents: [] } + await fs.writeFile(intentsPath, yaml.stringify(initialData), "utf-8") + } + + // Initialize agent_trace.jsonl if it doesn't exist + const tracePath = path.join(this.orchestrationDir, "agent_trace.jsonl") + try { + await fs.access(tracePath) + } catch { + // File doesn't exist, create empty file + await fs.writeFile(tracePath, "", "utf-8") + } + + // Initialize intent_map.md if it doesn't exist + const mapPath = path.join(this.orchestrationDir, "intent_map.md") + try { + await fs.access(mapPath) + } catch { + // File doesn't exist, create it with header + const header = `# Intent Map + +This file maps high-level business intents to physical files and AST nodes. + +## Intents + +` + await fs.writeFile(mapPath, header, "utf-8") + } + + // Initialize AGENT.md if it doesn't exist + const agentPath = path.join(this.orchestrationDir, "AGENT.md") + try { + await fs.access(agentPath) + } catch { + // File doesn't exist, create it with header + const header = `# Shared Knowledge Base + +This file contains persistent knowledge shared across parallel sessions (Architect/Builder/Tester). + +## Lessons Learned + +` + await fs.writeFile(agentPath, header, "utf-8") + } + } catch (error) { + console.error("Failed to initialize orchestration directory:", error) + throw error + } + } + + /** + * Read active intents from YAML file + */ + async readActiveIntents(): Promise { + const intentsPath = path.join(this.orchestrationDir, "active_intents.yaml") + try { + const content = await fs.readFile(intentsPath, "utf-8") + return yaml.parse(content) as ActiveIntentsData + } catch (error) { + console.error("Failed to read active_intents.yaml:", error) + return { active_intents: [] } + } + } + + /** + * Write active intents to YAML file + */ + async writeActiveIntents(data: ActiveIntentsData): Promise { + const intentsPath = path.join(this.orchestrationDir, "active_intents.yaml") + await fs.writeFile(intentsPath, yaml.stringify(data), "utf-8") + } + + /** + * Get a specific intent by ID + */ + async getIntent(intentId: string): Promise { + const data = await this.readActiveIntents() + return data.active_intents.find((intent) => intent.id === intentId) || null + } + + /** + * Update an intent (create if doesn't exist) + */ + async updateIntent(intent: ActiveIntent): Promise { + const data = await this.readActiveIntents() + const index = data.active_intents.findIndex((i) => i.id === intent.id) + + intent.updated_at = new Date().toISOString() + if (!intent.created_at) { + intent.created_at = intent.updated_at + } + + if (index >= 0) { + data.active_intents[index] = intent + } else { + data.active_intents.push(intent) + } + + await this.writeActiveIntents(data) + } + + /** + * Append a trace entry to agent_trace.jsonl + */ + async appendTraceEntry(entry: AgentTraceEntry): Promise { + const tracePath = path.join(this.orchestrationDir, "agent_trace.jsonl") + const line = JSON.stringify(entry) + "\n" + await fs.appendFile(tracePath, line, "utf-8") + } + + /** + * Get recent trace entries for a specific intent ID + * Returns the most recent entries (up to limit) that reference this intent + * This is used for Phase 1: Context Loader to provide recent history + */ + async getTraceEntriesForIntent(intentId: string, limit: number = 10): Promise { + const tracePath = path.join(this.orchestrationDir, "agent_trace.jsonl") + + try { + const content = await fs.readFile(tracePath, "utf-8") + const lines = content.trim().split("\n").filter((line) => line.trim() && !line.startsWith("#")) + + const entries: AgentTraceEntry[] = [] + + // Parse each line and filter by intent ID + for (const line of lines) { + try { + const entry = JSON.parse(line) as AgentTraceEntry + + // Check if any file's conversation references this intent + const referencesIntent = entry.files.some((file) => + file.conversations.some((conv) => + conv.related.some( + (rel) => rel.type === "intent" && rel.value === intentId, + ), + ), + ) + + if (referencesIntent) { + entries.push(entry) + } + } catch (error) { + // Skip invalid JSON lines (comments, etc.) + continue + } + } + + // Sort by timestamp (most recent first) and return up to limit + entries.sort((a, b) => { + const timeA = new Date(a.timestamp).getTime() + const timeB = new Date(b.timestamp).getTime() + return timeB - timeA // Descending order (newest first) + }) + + return entries.slice(0, limit) + } catch (error) { + // File doesn't exist or can't be read - return empty array + console.error("Failed to read agent_trace.jsonl:", error) + return [] + } + } + + /** + * Compute SHA-256 hash of content for spatial independence + */ + computeContentHash(content: string): string { + return crypto.createHash("sha256").update(content).digest("hex") + } + + /** + * Get orchestration directory path + */ + getOrchestrationDir(): string { + return this.orchestrationDir + } +} diff --git a/src/core/prompts/sections/tool-use-guidelines.ts b/src/core/prompts/sections/tool-use-guidelines.ts index 78193372cc8..131595ba429 100644 --- a/src/core/prompts/sections/tool-use-guidelines.ts +++ b/src/core/prompts/sections/tool-use-guidelines.ts @@ -1,6 +1,28 @@ export function getToolUseGuidelinesSection(): string { return `# Tool Use Guidelines +## Intent-Driven Architecture (Reasoning Loop) + +You are an Intent-Driven Architect. You CANNOT write code immediately. Your first action MUST be to analyze the user request and call select_active_intent(intent_id) to load the necessary context. + +**CRITICAL PROTOCOL:** +1. When the user requests code changes (refactoring, new features, bug fixes), you MUST first: + - Analyze the request to identify which intent it relates to + - Call select_active_intent(intent_id) with a valid intent ID from active_intents.yaml + - Wait for the intent context to be loaded + - Only then proceed with code changes + +2. You CANNOT use write_to_file, edit_file, apply_diff, or any other code modification tools without first calling select_active_intent. + +3. If you attempt to write code without selecting an intent, the system will block your action and return an error. + +4. The intent context will provide you with: + - Owned scope (which files/directories you can modify) + - Constraints (rules you must follow) + - Acceptance criteria (definition of done) + +## General Tool Use + 1. Assess what information you already have and what information you need to proceed with the task. 2. Choose the most appropriate tool based on the task and the tool descriptions provided. Assess if you need additional information to proceed, and which of the available tools would be most effective for gathering this information. For example using the list_files tool is more effective than running a command like \`ls\` in the terminal. It's critical that you think about each available tool and use the one that best fits the current step in the task. 3. If multiple actions are needed, you may use multiple tools in a single message when appropriate, or use tools iteratively across messages. Each tool use should be informed by the results of previous tool uses. Do not assume the outcome of any tool use. Each step must be informed by the previous step's result. diff --git a/src/core/prompts/tools/native-tools/index.ts b/src/core/prompts/tools/native-tools/index.ts index 758914d2d65..82915152b27 100644 --- a/src/core/prompts/tools/native-tools/index.ts +++ b/src/core/prompts/tools/native-tools/index.ts @@ -20,6 +20,7 @@ import searchFiles from "./search_files" import switchMode from "./switch_mode" import updateTodoList from "./update_todo_list" import writeToFile from "./write_to_file" +import selectActiveIntent from "./select_active_intent" export { getMcpServerTools } from "./mcp_server" export { convertOpenAIToolToAnthropic, convertOpenAIToolsToAnthropic } from "./converters" @@ -47,6 +48,7 @@ export function getNativeTools(options: NativeToolsOptions = {}): OpenAI.Chat.Ch } return [ + selectActiveIntent, // Must be first - required before code changes accessMcpResource, apply_diff, applyPatch, diff --git a/src/core/prompts/tools/native-tools/select_active_intent.ts b/src/core/prompts/tools/native-tools/select_active_intent.ts new file mode 100644 index 00000000000..86d1f29bf61 --- /dev/null +++ b/src/core/prompts/tools/native-tools/select_active_intent.ts @@ -0,0 +1,27 @@ +import type OpenAI from "openai" + +/** + * Tool for selecting an active intent before making code changes. + * This enforces the Reasoning Loop protocol. + */ +const selectActiveIntent: OpenAI.Chat.ChatCompletionFunctionTool = { + type: "function", + function: { + name: "select_active_intent", + description: + "Select an active intent from active_intents.yaml before making code changes. This is REQUIRED before using any code modification tools (write_to_file, edit_file, etc.). The intent provides context about scope, constraints, and acceptance criteria.", + parameters: { + type: "object", + properties: { + intent_id: { + type: "string", + description: + "The ID of the intent to activate (e.g., 'INT-001'). Must exist in .orchestration/active_intents.yaml", + }, + }, + required: ["intent_id"], + }, + }, +} + +export default selectActiveIntent diff --git a/src/core/tools/SelectActiveIntentTool.ts b/src/core/tools/SelectActiveIntentTool.ts new file mode 100644 index 00000000000..59105fd682e --- /dev/null +++ b/src/core/tools/SelectActiveIntentTool.ts @@ -0,0 +1,128 @@ +import { Task } from "../task/Task" +import { formatResponse } from "../prompts/responses" +import { BaseTool, ToolCallbacks } from "./BaseTool" +import type { ToolUse } from "../../shared/tools" +import { OrchestrationDataModel } from "../orchestration/OrchestrationDataModel" + +interface SelectActiveIntentParams { + intent_id: string +} + +/** + * Tool for selecting an active intent before code changes. + * This enforces the Reasoning Loop: agents must select an intent before writing code. + */ +export class SelectActiveIntentTool extends BaseTool<"select_active_intent"> { + readonly name = "select_active_intent" as const + + async execute(params: SelectActiveIntentParams, task: Task, callbacks: ToolCallbacks): Promise { + const { intent_id } = params + const { pushToolResult, handleError } = callbacks + + try { + if (!intent_id) { + task.consecutiveMistakeCount++ + task.recordToolError("select_active_intent") + pushToolResult(await task.sayAndCreateMissingParamError("select_active_intent", "intent_id")) + return + } + + // Initialize orchestration data model + const dataModel = new OrchestrationDataModel(task.cwd) + await dataModel.initialize() + + // Load the intent from active_intents.yaml + const intent = await dataModel.getIntent(intent_id) + + if (!intent) { + task.consecutiveMistakeCount++ + task.recordToolError("select_active_intent") + pushToolResult( + formatResponse.toolError( + `Intent "${intent_id}" not found in active_intents.yaml. Please use a valid intent ID.`, + ), + ) + return + } + + // Get recent trace entries for this intent (Phase 1 requirement: Context Loader) + // This provides recent history to help the agent understand what has been done + const traceEntries = await dataModel.getTraceEntriesForIntent(intent_id, 5) + + // Store active intent in task instance + ;(task as any).activeIntentId = intent_id + ;(task as any).activeIntent = intent + + // Build context XML block for injection into prompt (now includes trace entries) + const contextXml = this.buildIntentContextXml(intent, traceEntries) + + // Reset mistake count on success + task.consecutiveMistakeCount = 0 + + // Return context as tool result (will be injected into next prompt) + pushToolResult(contextXml) + + return + } catch (error) { + await handleError("selecting active intent", error as Error) + return + } + } + + /** + * Build XML block containing intent context for prompt injection + * Now includes recent trace entries for context (Phase 1: Context Loader) + */ + private buildIntentContextXml(intent: any, traceEntries: any[] = []): string { + const scopeList = intent.owned_scope.map((s: string) => ` - ${s}`).join("\n") + const constraintsList = intent.constraints.map((c: string) => ` - ${c}`).join("\n") + const criteriaList = intent.acceptance_criteria.map((c: string) => ` - ${c}`).join("\n") + + // Build recent history section from trace entries + let recentHistorySection = "" + if (traceEntries.length > 0) { + const historyItems = traceEntries.map((entry) => { + const files = entry.files + .map((f: any) => { + const ranges = f.conversations[0]?.ranges?.[0] + if (ranges) { + return ` - ${f.relative_path} (lines ${ranges.start_line}-${ranges.end_line})` + } + return ` - ${f.relative_path}` + }) + .join("\n") + const timestamp = new Date(entry.timestamp).toISOString().split("T")[0] + return ` - ${timestamp}: Modified files:\n${files}` + }) + recentHistorySection = ` +${historyItems.join("\n")} +` + } else { + recentHistorySection = ` + No recent changes found for this intent. +` + } + + return ` +${intent.id} +${intent.name} +${intent.status} + +${scopeList} + + +${constraintsList} + + +${criteriaList} + +${recentHistorySection} +` + } + + override async handlePartial(task: Task, block: ToolUse<"select_active_intent">): Promise { + // No partial handling needed for intent selection + } +} + +export const selectActiveIntentTool = new SelectActiveIntentTool() diff --git a/src/shared/tools.ts b/src/shared/tools.ts index 491ba693611..6ae8eecfc32 100644 --- a/src/shared/tools.ts +++ b/src/shared/tools.ts @@ -265,6 +265,7 @@ export type ToolGroupConfig = { } export const TOOL_DISPLAY_NAMES: Record = { + select_active_intent: "select active intent", execute_command: "run commands", read_file: "read files", read_command_output: "read command output", @@ -314,6 +315,7 @@ export const TOOL_GROUPS: Record = { // Tools that are always available to all modes. export const ALWAYS_AVAILABLE_TOOLS: ToolName[] = [ + "select_active_intent", "ask_followup_question", "attempt_completion", "switch_mode", From 379a61e1c81d8ec9332af77c4ced2b4e4bbe0647 Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 14:01:19 +0300 Subject: [PATCH 05/41] chore: add specs and generator script for active_intents.yaml --- .gitignore | 2 +- package.json | 5 + pnpm-lock.yaml | 9 +- scripts/generate-specs.mjs | 105 ++++++++++++++++++++ specs/INT-001-intent-code-traceability.md | 28 ++++++ specs/INT-002-hook-system-implementation.md | 26 +++++ specs/INT-003-reasoning-loop.md | 24 +++++ specs/INT-004-orchestration-directory.md | 30 ++++++ specs/INT-005-logging-traceability.md | 33 ++++++ specs/INT-006-testing-validation.md | 28 ++++++ specs/INT-007-documentation.md | 33 ++++++ 11 files changed, 320 insertions(+), 3 deletions(-) create mode 100644 scripts/generate-specs.mjs create mode 100644 specs/INT-001-intent-code-traceability.md create mode 100644 specs/INT-002-hook-system-implementation.md create mode 100644 specs/INT-003-reasoning-loop.md create mode 100644 specs/INT-004-orchestration-directory.md create mode 100644 specs/INT-005-logging-traceability.md create mode 100644 specs/INT-006-testing-validation.md create mode 100644 specs/INT-007-documentation.md diff --git a/.gitignore b/.gitignore index 1dbcdc6a362..e403b7eaa90 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,7 @@ node_modules package-lock.json coverage/ mock/ - +TRP1 Challenge Week 1_ Architecting the AI-Native IDE & Intent-Code Traceability.docx .DS_Store # IDEs diff --git a/package.json b/package.json index de8dff751cb..28eb2076403 100644 --- a/package.json +++ b/package.json @@ -26,6 +26,8 @@ "knip": "knip --include files", "evals": "dotenvx run -f packages/evals/.env.development packages/evals/.env.local -- docker compose -f packages/evals/docker-compose.yml --profile server --profile runner up --build --scale runner=0", "npm:publish:types": "pnpm --filter @roo-code/types npm:publish" + , + "spec:generate": "node scripts/generate-specs.mjs" }, "devDependencies": { "@changesets/cli": "^2.27.10", @@ -70,5 +72,8 @@ "@types/react-dom": "^18.3.5", "zod": "3.25.76" } + }, + "dependencies": { + "yaml": "^2.8.0" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 6b461926f5e..094759332e2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -19,6 +19,10 @@ overrides: importers: .: + dependencies: + yaml: + specifier: ^2.8.0 + version: 2.8.0 devDependencies: '@changesets/cli': specifier: ^2.27.10 @@ -6927,6 +6931,7 @@ packages: glob@11.1.0: resolution: {integrity: sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==} engines: {node: 20 || >=22} + deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me hasBin: true global-agent@3.0.0: @@ -10101,7 +10106,7 @@ packages: tar@7.4.3: resolution: {integrity: sha512-5S7Va8hKfV7W5U6g3aYxXmlPoZVAwUMy9AOKyF2fVuZa2UD3qZjg578OrLRt8PcNN1PleVaL/5/yYATNL0ICUw==} engines: {node: '>=18'} - deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exhorbitant rates) by contacting i@izs.me + deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me term-size@2.2.1: resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==} @@ -15073,7 +15078,7 @@ snapshots: sirv: 3.0.1 tinyglobby: 0.2.14 tinyrainbow: 2.0.0 - vitest: 3.2.4(@types/debug@4.1.12)(@types/node@24.2.1)(@vitest/ui@3.2.4)(jiti@2.4.2)(jsdom@26.1.0)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0) + vitest: 3.2.4(@types/debug@4.1.12)(@types/node@20.17.57)(@vitest/ui@3.2.4)(jiti@2.4.2)(jsdom@26.1.0)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0) '@vitest/utils@3.2.4': dependencies: diff --git a/scripts/generate-specs.mjs b/scripts/generate-specs.mjs new file mode 100644 index 00000000000..a0d9a964c4b --- /dev/null +++ b/scripts/generate-specs.mjs @@ -0,0 +1,105 @@ +import fs from "node:fs/promises" +import path from "node:path" +import crypto from "node:crypto" +import * as yaml from "yaml" + +function sha256(text) { + return crypto.createHash("sha256").update(text).digest("hex") +} + +function parseSpecMarkdown(md) { + // Extremely small “SpecKit-like” parser: extracts the 4 sections we need. + // Sections are identified by headings: + // - "## Intent" + // - "## Scope (owned_scope)" + // - "## Constraints" + // - "## Acceptance Criteria" + const getSection = (title) => { + const re = new RegExp(`^##\\s+${title}\\s*$`, "m") + const m = md.match(re) + if (!m) return "" + const start = m.index + m[0].length + const rest = md.slice(start) + const next = rest.search(/^##\s+/m) + return (next === -1 ? rest : rest.slice(0, next)).trim() + } + + const intent = getSection("Intent").trim() + const scope = getSection("Scope \\(owned_scope\\)") + .split("\n") + .map((l) => l.trim()) + .filter((l) => l.startsWith("- ")) + .map((l) => l.slice(2).trim().replace(/^`|`$/g, "")) + + const constraints = getSection("Constraints") + .split("\n") + .map((l) => l.trim()) + .filter((l) => l.startsWith("- ")) + .map((l) => l.slice(2).trim()) + + const acceptance = getSection("Acceptance Criteria") + .split("\n") + .map((l) => l.trim()) + .filter((l) => l.startsWith("- ")) + .map((l) => l.slice(2).trim()) + + return { intent, scope, constraints, acceptance } +} + +async function main() { + const repoRoot = process.cwd() + const specsDir = path.join(repoRoot, "specs") + const orchestrationDir = path.join(repoRoot, ".orchestration") + + await fs.mkdir(specsDir, { recursive: true }) + await fs.mkdir(orchestrationDir, { recursive: true }) + + const specFiles = (await fs.readdir(specsDir)).filter((f) => f.endsWith(".md")) + if (specFiles.length === 0) { + console.log("No spec files found in ./specs. Add at least one *.md spec and rerun.") + process.exit(1) + } + + const activeIntentsPath = path.join(orchestrationDir, "active_intents.yaml") + const existingYaml = await fs.readFile(activeIntentsPath, "utf-8").catch(() => "active_intents: []\n") + const existing = (yaml.parse(existingYaml) ?? {}) || {} + const active_intents = Array.isArray(existing.active_intents) ? existing.active_intents : [] + + for (const file of specFiles) { + const full = path.join(specsDir, file) + const md = await fs.readFile(full, "utf-8") + + const idMatch = file.match(/^(INT-\d+)/i) + const id = idMatch ? idMatch[1].toUpperCase() : `INT-${sha256(file).slice(0, 3).toUpperCase()}` + const name = md.split("\n").find((l) => l.startsWith("# "))?.replace(/^#\s+/, "").trim() || file + + const parsed = parseSpecMarkdown(md) + + const intentEntry = { + id, + name, + status: "IN_PROGRESS", + owned_scope: parsed.scope, + constraints: parsed.constraints, + acceptance_criteria: parsed.acceptance, + created_at: new Date().toISOString(), + updated_at: new Date().toISOString(), + spec_hash: `sha256:${sha256(md)}`, + spec_file: `specs/${file}`, + } + + const i = active_intents.findIndex((x) => x?.id === id) + if (i >= 0) active_intents[i] = intentEntry + else active_intents.push(intentEntry) + } + + await fs.writeFile(activeIntentsPath, yaml.stringify({ active_intents }), "utf-8") + console.log(`Updated .orchestration/active_intents.yaml with ${active_intents.length} intent(s).`) +} + +main().catch((err) => { + console.error(err) + process.exit(1) +}) + + diff --git a/specs/INT-001-intent-code-traceability.md b/specs/INT-001-intent-code-traceability.md new file mode 100644 index 00000000000..701ac6e8c9d --- /dev/null +++ b/specs/INT-001-intent-code-traceability.md @@ -0,0 +1,28 @@ +# INT-001 — Intent-Code Traceability (Spec) + +## Intent +Build an Intent-Code Traceability system for Roo Code that enforces a two-stage reasoning loop and produces durable, auditable traces linking intents to code changes. + +## Scope (owned_scope) +- `src/core/assistant-message/**` +- `src/core/tools/**` +- `src/core/hooks/**` +- `src/core/orchestration/**` +- `src/core/prompts/**` +- `.orchestration/**` + +## Constraints +- Must enforce **intent selection before any destructive tool** (`write_to_file`, `edit_file`, `apply_diff`, etc.). +- Must keep **privilege separation**: UI emits events; extension host executes privileged actions; hooks are middleware. +- Must log **spatially independent** traces via content hashing. + +## Acceptance Criteria +- Agent cannot write code before calling `select_active_intent(intent_id)`. +- When a file is written, a JSONL entry is appended to `.orchestration/agent_trace.jsonl` that includes: + - intent id + - file path + - line range (best-effort) + - `sha256:` content hash of the modified block +- `.orchestration/active_intents.yaml` exists and contains this intent. + + diff --git a/specs/INT-002-hook-system-implementation.md b/specs/INT-002-hook-system-implementation.md new file mode 100644 index 00000000000..df6546ba2ff --- /dev/null +++ b/specs/INT-002-hook-system-implementation.md @@ -0,0 +1,26 @@ +# INT-002 — Hook System Implementation + +## Intent +Implement a hook system that intercepts tool execution in Roo Code to enforce intent selection and validate AI-generated code before execution. + +## Scope (owned_scope) +- `src/core/hooks/**` +- `src/core/assistant-message/presentAssistantMessage.ts` +- `src/core/tools/**` +- `.orchestration/**` + +## Constraints +- Must integrate with existing `presentAssistantMessage()` function without breaking current tool execution flow. +- Pre-hooks must run **before** `tool.handle()` is called. +- Post-hooks must run **after** `tool.execute()` completes but before result is returned. +- Hook system must be non-blocking for non-destructive tools (read-only operations). +- Must maintain backward compatibility with existing tools. + +## Acceptance Criteria +- `HookEngine` class exists in `src/core/hooks/HookEngine.ts`. +- Pre-hook validates intent selection for destructive tools (`write_to_file`, `edit_file`, `execute_command`, etc.). +- Pre-hook enforces scope validation (file path must be within intent's `owned_scope`). +- Post-hook logs trace entries to `.orchestration/agent_trace.jsonl` for mutating actions. +- `presentAssistantMessage()` integrates `HookEngine` with Pre-Hook and Post-Hook calls. +- All existing tests pass after hook integration. + diff --git a/specs/INT-003-reasoning-loop.md b/specs/INT-003-reasoning-loop.md new file mode 100644 index 00000000000..dbf600e1a4e --- /dev/null +++ b/specs/INT-003-reasoning-loop.md @@ -0,0 +1,24 @@ +# INT-003 — Two-Stage Reasoning Loop + +## Intent +Implement a two-stage state machine that enforces intent selection before code generation and validates AI output against intent constraints. + +## Scope (owned_scope) +- `src/core/hooks/HookEngine.ts` +- `src/core/prompts/sections/tool-use-guidelines.ts` +- `src/core/tools/SelectActiveIntentTool.ts` +- `src/core/task/Task.ts` + +## Constraints +- **Stage 1 (Reasoning Intercept):** Agent MUST call `select_active_intent(intent_id)` before any destructive tool. +- **Stage 2 (Contextualized Action):** Agent receives intent context and must include it when making code changes. +- System prompt must enforce this protocol in tool-use guidelines. +- Intent context must be injected into the agent's context before code generation. + +## Acceptance Criteria +- System prompt includes instructions requiring `select_active_intent` before code changes. +- `SelectActiveIntentTool` returns XML `` block with scope, constraints, and acceptance criteria. +- Pre-hook blocks destructive tools if no active intent is selected. +- Agent receives intent context in subsequent tool calls. +- Intent context is logged in `agent_trace.jsonl` entries. + diff --git a/specs/INT-004-orchestration-directory.md b/specs/INT-004-orchestration-directory.md new file mode 100644 index 00000000000..baaa68eec8d --- /dev/null +++ b/specs/INT-004-orchestration-directory.md @@ -0,0 +1,30 @@ +# INT-004 — Orchestration Directory Management + +## Intent +Implement a robust data model for managing `.orchestration/` directory files with proper initialization, validation, and atomic updates. + +## Scope (owned_scope) +- `src/core/orchestration/OrchestrationDataModel.ts` +- `.orchestration/active_intents.yaml` +- `.orchestration/agent_trace.jsonl` +- `.orchestration/intent_map.md` +- `.orchestration/AGENT.md` + +## Constraints +- `.orchestration/` directory must be machine-managed (not user-edited directly). +- `active_intents.yaml` must be valid YAML and follow the schema defined in `document.md`. +- `agent_trace.jsonl` must be append-only (no modifications, only appends). +- All file operations must be atomic (write to temp file, then rename). +- Directory and files must be initialized on first use. + +## Acceptance Criteria +- `OrchestrationDataModel` class provides methods: + - `initialize()`: Creates directory and initializes files if missing. + - `readActiveIntents()`: Parses and returns active intents. + - `appendAgentTrace()`: Appends trace entry to JSONL file. + - `updateIntentMap()`: Updates intent-to-file mapping. + - `appendAgentKnowledge()`: Appends to AGENT.md. +- All methods handle errors gracefully and log failures. +- Files are created with proper templates if missing. +- YAML parsing validates schema and reports errors clearly. + diff --git a/specs/INT-005-logging-traceability.md b/specs/INT-005-logging-traceability.md new file mode 100644 index 00000000000..84665bcfd65 --- /dev/null +++ b/specs/INT-005-logging-traceability.md @@ -0,0 +1,33 @@ +# INT-005 — Logging & Traceability + +## Intent +Implement comprehensive trace logging that links intents to code changes via content hashing, enabling spatial independence and auditability. + +## Scope (owned_scope) +- `src/core/hooks/HookEngine.ts` (Post-Hook implementation) +- `src/core/orchestration/OrchestrationDataModel.ts` +- `.orchestration/agent_trace.jsonl` +- `src/utils/git.ts` (for VCS revision tracking) + +## Constraints +- Trace entries must include `sha256:` content hash of modified code blocks. +- Line ranges must be best-effort (may be approximate for complex edits). +- Each trace entry must link to: + - Intent ID + - File path (relative to workspace root) + - VCS revision (Git SHA) + - Timestamp + - Model identifier +- Content hashing must be spatially independent (same code block = same hash regardless of file location). + +## Acceptance Criteria +- Post-hook computes SHA-256 hash of modified content for file tools. +- Trace entry includes all required fields per `document.md` schema: + - `id` (UUID) + - `timestamp` (ISO 8601) + - `vcs.revision_id` (Git SHA) + - `files[]` with `relative_path`, `conversations[]`, `ranges[]`, `content_hash` +- Trace entries are appended atomically to `agent_trace.jsonl`. +- Content hash format: `sha256:`. +- Git SHA is retrieved from workspace root (handles non-Git repos gracefully). + diff --git a/specs/INT-006-testing-validation.md b/specs/INT-006-testing-validation.md new file mode 100644 index 00000000000..f77f7498be4 --- /dev/null +++ b/specs/INT-006-testing-validation.md @@ -0,0 +1,28 @@ +# INT-006 — Testing & Validation + +## Intent +Create comprehensive test coverage for the Intent-Code Traceability system, including unit tests, integration tests, and end-to-end validation scenarios. + +## Scope (owned_scope) +- `src/core/hooks/**/*.test.ts` +- `src/core/orchestration/**/*.test.ts` +- `src/core/tools/SelectActiveIntentTool.test.ts` +- `tests/integration/hook-system.test.ts` +- `tests/e2e/intent-traceability.test.ts` + +## Constraints +- Tests must not modify production `.orchestration/` files (use temp directories). +- Tests must be deterministic and isolated (no shared state). +- Integration tests must verify hook system works with real tool execution. +- E2E tests must simulate full agent workflow (intent selection → code change → trace logging). + +## Acceptance Criteria +- Unit tests for `HookEngine.preHook()` and `HookEngine.postHook()`. +- Unit tests for `OrchestrationDataModel` file operations. +- Unit tests for `SelectActiveIntentTool` intent loading and context generation. +- Integration test: Verify Pre-Hook blocks destructive tool without intent. +- Integration test: Verify Post-Hook logs trace entry after file write. +- E2E test: Full workflow from intent selection to trace logging. +- All tests pass in CI/CD pipeline. +- Test coverage > 80% for hook and orchestration modules. + diff --git a/specs/INT-007-documentation.md b/specs/INT-007-documentation.md new file mode 100644 index 00000000000..851e87dd85a --- /dev/null +++ b/specs/INT-007-documentation.md @@ -0,0 +1,33 @@ +# INT-007 — Documentation & Knowledge Base + +## Intent +Maintain comprehensive documentation for the Intent-Code Traceability system, including architecture notes, API documentation, and a persistent knowledge base. + +## Scope (owned_scope) +- `ARCHITECTURE_NOTES.md` +- `README.md` (Intent-Code Traceability section) +- `.orchestration/AGENT.md` +- `docs/intent-traceability/` +- `CHANGELOG.md` (relevant entries) + +## Constraints +- `ARCHITECTURE_NOTES.md` must document all injection points and hook integration. +- `AGENT.md` must be append-only knowledge base for "Lessons Learned". +- Documentation must be kept in sync with code changes. +- API documentation must include examples for each public method. + +## Acceptance Criteria +- `ARCHITECTURE_NOTES.md` includes: + - Tool execution flow diagram + - Hook injection points with line numbers + - System prompt modification points + - Data model schemas +- `AGENT.md` includes: + - Lessons learned from implementation + - Common pitfalls and solutions + - Performance optimizations + - Stylistic rules for intent specifications +- README includes setup instructions and usage examples. +- All public APIs are documented with JSDoc comments. +- Documentation is reviewed and updated with each major change. + From 2ccde1e260e23668420eeb6f83101d72cd5339e2 Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 14:01:30 +0300 Subject: [PATCH 06/41] test: add Phase 1 test suite for select_active_intent with trace entry lookup --- .../__tests__/selectActiveIntentTool.spec.ts | 323 ++++++++++++++++++ 1 file changed, 323 insertions(+) create mode 100644 src/core/tools/__tests__/selectActiveIntentTool.spec.ts diff --git a/src/core/tools/__tests__/selectActiveIntentTool.spec.ts b/src/core/tools/__tests__/selectActiveIntentTool.spec.ts new file mode 100644 index 00000000000..10a54d8492a --- /dev/null +++ b/src/core/tools/__tests__/selectActiveIntentTool.spec.ts @@ -0,0 +1,323 @@ +// npx vitest run src/core/tools/__tests__/selectActiveIntentTool.spec.ts + +import * as fs from "fs/promises" +import * as path from "path" +import * as os from "os" + +import { selectActiveIntentTool } from "../SelectActiveIntentTool" +import type { ToolUse } from "../../../shared/tools" +import type { AgentTraceEntry } from "../../orchestration/OrchestrationDataModel" + +describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { + let testWorkspaceDir: string + let mockTask: any + let mockPushToolResult: ReturnType + let mockHandleError: ReturnType + let mockSayAndCreateMissingParamError: ReturnType + + beforeEach(async () => { + // Create a temporary directory for testing + testWorkspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "roo-test-")) + + // Setup mock task + mockTask = { + cwd: testWorkspaceDir, + consecutiveMistakeCount: 0, + recordToolError: vi.fn(), + sayAndCreateMissingParamError: vi.fn().mockResolvedValue("Missing parameter error"), + } + + mockPushToolResult = vi.fn() + mockHandleError = vi.fn() + mockSayAndCreateMissingParamError = vi.fn().mockResolvedValue("Missing parameter error") + mockTask.sayAndCreateMissingParamError = mockSayAndCreateMissingParamError + + // Initialize .orchestration directory + const orchestrationDir = path.join(testWorkspaceDir, ".orchestration") + await fs.mkdir(orchestrationDir, { recursive: true }) + }) + + afterEach(async () => { + // Clean up temporary directory + try { + await fs.rm(testWorkspaceDir, { recursive: true, force: true }) + } catch (error) { + // Ignore cleanup errors + } + }) + + describe("Phase 1: Context Loader with Trace Entries", () => { + it("should load intent and include trace entries in context XML", async () => { + // Setup: Create active_intents.yaml + const intentsYaml = `active_intents: + - id: INT-001 + name: Test Intent + status: IN_PROGRESS + owned_scope: + - src/test/** + constraints: + - Must follow test patterns + acceptance_criteria: + - All tests pass +` + + const intentsPath = path.join(testWorkspaceDir, ".orchestration", "active_intents.yaml") + await fs.writeFile(intentsPath, intentsYaml, "utf-8") + + // Setup: Create agent_trace.jsonl with entries for INT-001 + const traceEntry1: AgentTraceEntry = { + id: "trace-1", + timestamp: "2026-02-18T10:00:00Z", + vcs: { revision_id: "abc123" }, + files: [ + { + relative_path: "src/test/file1.ts", + conversations: [ + { + url: "task-1", + contributor: { entity_type: "AI", model_identifier: "claude-3-5-sonnet" }, + ranges: [{ start_line: 10, end_line: 20, content_hash: "sha256:hash1" }], + related: [{ type: "intent", value: "INT-001" }], + }, + ], + }, + ], + } + + const traceEntry2: AgentTraceEntry = { + id: "trace-2", + timestamp: "2026-02-18T11:00:00Z", + vcs: { revision_id: "def456" }, + files: [ + { + relative_path: "src/test/file2.ts", + conversations: [ + { + url: "task-2", + contributor: { entity_type: "AI", model_identifier: "claude-3-5-sonnet" }, + ranges: [{ start_line: 5, end_line: 15, content_hash: "sha256:hash2" }], + related: [{ type: "intent", value: "INT-001" }], + }, + ], + }, + ], + } + + const tracePath = path.join(testWorkspaceDir, ".orchestration", "agent_trace.jsonl") + await fs.writeFile( + tracePath, + JSON.stringify(traceEntry1) + "\n" + JSON.stringify(traceEntry2) + "\n", + "utf-8", + ) + + // Execute: Call select_active_intent + const toolUse: ToolUse<"select_active_intent"> = { + type: "tool_use", + id: "tool-1", + name: "select_active_intent", + params: { intent_id: "INT-001" }, + } + + await selectActiveIntentTool.execute( + { intent_id: "INT-001" }, + mockTask, + { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }, + ) + + // Verify: pushToolResult was called with XML context + expect(mockPushToolResult).toHaveBeenCalledTimes(1) + const contextXml = mockPushToolResult.mock.calls[0][0] + + // Verify: XML contains intent information + expect(contextXml).toContain("INT-001") + expect(contextXml).toContain("Test Intent") + expect(contextXml).toContain("IN_PROGRESS") + expect(contextXml).toContain("src/test/**") + expect(contextXml).toContain("Must follow test patterns") + expect(contextXml).toContain("All tests pass") + + // Verify: XML contains recent history from trace entries + expect(contextXml).toContain("") + expect(contextXml).toContain("src/test/file1.ts") + expect(contextXml).toContain("src/test/file2.ts") + expect(contextXml).toContain("lines 10-20") + expect(contextXml).toContain("lines 5-15") + expect(contextXml).toContain("2026-02-18") + + // Verify: Task has active intent stored + expect((mockTask as any).activeIntentId).toBe("INT-001") + expect((mockTask as any).activeIntent).toBeDefined() + expect((mockTask as any).activeIntent.id).toBe("INT-001") + + // Verify: No errors occurred + expect(mockHandleError).not.toHaveBeenCalled() + expect(mockTask.consecutiveMistakeCount).toBe(0) + }) + + it("should handle intent with no trace entries", async () => { + // Setup: Create active_intents.yaml + const intentsYaml = `active_intents: + - id: INT-002 + name: New Intent + status: TODO + owned_scope: + - src/new/** + constraints: [] + acceptance_criteria: [] +` + + const intentsPath = path.join(testWorkspaceDir, ".orchestration", "active_intents.yaml") + await fs.writeFile(intentsPath, intentsYaml, "utf-8") + + // Setup: Create empty agent_trace.jsonl + const tracePath = path.join(testWorkspaceDir, ".orchestration", "agent_trace.jsonl") + await fs.writeFile(tracePath, "", "utf-8") + + // Execute + await selectActiveIntentTool.execute( + { intent_id: "INT-002" }, + mockTask, + { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }, + ) + + // Verify: XML contains "No recent changes" message + const contextXml = mockPushToolResult.mock.calls[0][0] + expect(contextXml).toContain("") + expect(contextXml).toContain("No recent changes found for this intent") + }) + + it("should filter trace entries by intent ID", async () => { + // Setup: Create active_intents.yaml + const intentsYaml = `active_intents: + - id: INT-001 + name: Intent One + status: IN_PROGRESS + owned_scope: [] + constraints: [] + acceptance_criteria: [] + - id: INT-002 + name: Intent Two + status: IN_PROGRESS + owned_scope: [] + constraints: [] + acceptance_criteria: [] +` + + const intentsPath = path.join(testWorkspaceDir, ".orchestration", "active_intents.yaml") + await fs.writeFile(intentsPath, intentsYaml, "utf-8") + + // Setup: Create trace entries for different intents + const traceEntry1: AgentTraceEntry = { + id: "trace-1", + timestamp: "2026-02-18T10:00:00Z", + vcs: { revision_id: "abc123" }, + files: [ + { + relative_path: "src/file1.ts", + conversations: [ + { + url: "task-1", + contributor: { entity_type: "AI" }, + ranges: [{ start_line: 1, end_line: 10, content_hash: "sha256:hash1" }], + related: [{ type: "intent", value: "INT-001" }], + }, + ], + }, + ], + } + + const traceEntry2: AgentTraceEntry = { + id: "trace-2", + timestamp: "2026-02-18T11:00:00Z", + vcs: { revision_id: "def456" }, + files: [ + { + relative_path: "src/file2.ts", + conversations: [ + { + url: "task-2", + contributor: { entity_type: "AI" }, + ranges: [{ start_line: 1, end_line: 10, content_hash: "sha256:hash2" }], + related: [{ type: "intent", value: "INT-002" }], + }, + ], + }, + ], + } + + const tracePath = path.join(testWorkspaceDir, ".orchestration", "agent_trace.jsonl") + await fs.writeFile( + tracePath, + JSON.stringify(traceEntry1) + "\n" + JSON.stringify(traceEntry2) + "\n", + "utf-8", + ) + + // Execute: Select INT-001 + await selectActiveIntentTool.execute( + { intent_id: "INT-001" }, + mockTask, + { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }, + ) + + // Verify: Only INT-001 trace entry is included + const contextXml = mockPushToolResult.mock.calls[0][0] + expect(contextXml).toContain("src/file1.ts") + expect(contextXml).not.toContain("src/file2.ts") + }) + + it("should return error for non-existent intent", async () => { + // Setup: Create empty active_intents.yaml + const intentsYaml = `active_intents: []` + + const intentsPath = path.join(testWorkspaceDir, ".orchestration", "active_intents.yaml") + await fs.writeFile(intentsPath, intentsYaml, "utf-8") + + // Execute + await selectActiveIntentTool.execute( + { intent_id: "INT-999" }, + mockTask, + { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }, + ) + + // Verify: Error was returned + expect(mockPushToolResult).toHaveBeenCalled() + const errorMessage = mockPushToolResult.mock.calls[0][0] + expect(errorMessage).toContain("not found in active_intents.yaml") + expect(mockTask.consecutiveMistakeCount).toBeGreaterThan(0) + }) + + it("should handle missing intent_id parameter", async () => { + // Execute without intent_id + await selectActiveIntentTool.execute( + { intent_id: "" }, + mockTask, + { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }, + ) + + // Verify: Missing parameter error + expect(mockSayAndCreateMissingParamError).toHaveBeenCalledWith("select_active_intent", "intent_id") + expect(mockTask.consecutiveMistakeCount).toBeGreaterThan(0) + }) + }) +}) + From f16167ef4ab1d689970188cb86a2f066736942f6 Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 14:01:43 +0300 Subject: [PATCH 07/41] docs: document TRP1 intent-traceability implementation in README --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/README.md b/README.md index 75f37762f93..c0ee304bafe 100644 --- a/README.md +++ b/README.md @@ -155,6 +155,46 @@ We use [changesets](https://github.com/changesets/changesets) for versioning and --- +## TRP1 Challenge – Intent-Code Traceability Hook System + +This fork implements an AI-Native Intent-Code Traceability layer for the TRP1 Week 1 challenge, adding governance and semantic tracking to Roo Code's AI agent workflow. + +### Phase 0 – Archaeological Dig +- Documented extension architecture and tool execution flow in [`ARCHITECTURE_NOTES.md`](ARCHITECTURE_NOTES.md) +- Mapped tool routing (`presentAssistantMessage`) and system prompt builder (`SYSTEM_PROMPT`) +- Identified hook injection points for middleware integration + +### Phase 1 – Reasoning Loop & Context Loader ✅ +- **New Native Tool**: `select_active_intent(intent_id)` enforces two-stage state machine (intent selection → contextualized action) +- **Hook Middleware**: `HookEngine` wraps all destructive tools with pre/post-hooks for governance and traceability +- **Orchestration Sidecar**: `.orchestration/` directory implements AI-native Git layer: + - `active_intents.yaml` – Intent specifications with scope, constraints, acceptance criteria + - `agent_trace.jsonl` – Append-only ledger linking Intent → Code Hash + - `intent_map.md` – Spatial mapping of intents to files + - `AGENT.md` – Shared knowledge base +- **Context Loader**: `select_active_intent` returns `` XML with intent specs + recent history from trace entries + +### Phase 2 – Hook Middleware & Security (Partial) +- **Command Classification**: Safe (read) vs Destructive (write/execute) tools +- **UI-Blocking Authorization**: Modal approval required for intent evolution (Human-in-the-Loop) +- **Scope Enforcement**: File paths validated against intent's `owned_scope` patterns +- **Post-Hook Trace Logging**: Automatic logging to `agent_trace.jsonl` with content hashing + +### Documentation & Testing +- [`docs/Architecture.md`](docs/Architecture.md) – High-level architecture overview +- [`ARCHITECTURE_NOTES.md`](ARCHITECTURE_NOTES.md) – Detailed codebase mapping and injection points +- [`docs/UI-Blocking-Authorization.md`](docs/UI-Blocking-Authorization.md) – HITL governance design +- [`docs/TESTING-PHASE1.md`](docs/TESTING-PHASE1.md) – Manual testing guide +- [`docs/PHASE1-TEST-RESULTS.md`](docs/PHASE1-TEST-RESULTS.md) – Test execution results (5/5 passing) + +### Key Files +- `src/core/hooks/HookEngine.ts` – Hook middleware implementation +- `src/core/orchestration/OrchestrationDataModel.ts` – Data model for `.orchestration/` directory +- `src/core/tools/SelectActiveIntentTool.ts` – Intent selection tool +- `src/core/tools/__tests__/selectActiveIntentTool.spec.ts` – Phase 1 test suite + +--- + ## Disclaimer **Please note** that Roo Code, Inc does **not** make any representations or warranties regarding any code, models, or other tools provided or made available in connection with Roo Code, any associated third-party tools, or any resulting outputs. You assume **all risks** associated with the use of any such tools or outputs; such tools are provided on an **"AS IS"** and **"AS AVAILABLE"** basis. Such risks may include, without limitation, intellectual property infringement, cyber vulnerabilities or attacks, bias, inaccuracies, errors, defects, viruses, downtime, property loss or damage, and/or personal injury. You are solely responsible for your use of any such tools or outputs (including, without limitation, the legality, appropriateness, and results thereof). From 4fe5e0a5f63e7283a51ca2c15c8df687311f8ea3 Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 14:01:57 +0300 Subject: [PATCH 08/41] chore: update pre-commit hook configuration --- .husky/pre-commit | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.husky/pre-commit b/.husky/pre-commit index a0e3a53df53..f28ef3e430e 100644 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -24,4 +24,7 @@ else fi $npx_cmd lint-staged -$pnpm_cmd lint + +# Skip full repo lint on pre-commit (lint-staged already linted staged files) +# Full linting happens in CI for comprehensive coverage +echo "Pre-commit checks complete. Full lint runs in CI." From b0bb6c73dc34c63905346392b752171bb5c1c2cb Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 14:22:24 +0300 Subject: [PATCH 09/41] chore: fix HookEngine typings and add CI workflow --- .github/workflows/ci.yml | 65 +++++++ Architecture.md | 169 ------------------ src/core/hooks/HookEngine.ts | 8 +- .../__tests__/selectActiveIntentTool.spec.ts | 78 +++----- 4 files changed, 95 insertions(+), 225 deletions(-) create mode 100644 .github/workflows/ci.yml delete mode 100644 Architecture.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000000..b87cc142799 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,65 @@ +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + workflow_dispatch: + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup Node.js and pnpm + uses: ./.github/actions/setup-node-pnpm + - name: Run linter + run: pnpm lint + + type-check: + name: Type Check + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup Node.js and pnpm + uses: ./.github/actions/setup-node-pnpm + - name: Check TypeScript types + run: pnpm check-types + + test: + name: Test + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup Node.js and pnpm + uses: ./.github/actions/setup-node-pnpm + - name: Run tests + run: pnpm test + + build: + name: Build + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup Node.js and pnpm + uses: ./.github/actions/setup-node-pnpm + - name: Build project + run: pnpm build + + format-check: + name: Format Check + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Setup Node.js and pnpm + uses: ./.github/actions/setup-node-pnpm + - name: Check code formatting + run: npx prettier --check "**/*.{js,jsx,ts,tsx,json,css,md}" --ignore-path .gitignore || (echo "Code formatting check failed. Run 'pnpm format' to fix." && exit 1) + diff --git a/Architecture.md b/Architecture.md deleted file mode 100644 index 9a01a3d1854..00000000000 --- a/Architecture.md +++ /dev/null @@ -1,169 +0,0 @@ - -## **1. Project Overview** - -**Goal:** -Develop an **Intent-Code Traceability system** for the AI-Native IDE that ensures AI-generated code aligns with user intent and can be tracked, reasoned over, and verified. - -**Core Features:** - -* **Two-stage Reasoning Loop** (State Machine): - - * **Stage 1:** Capture client intent, map to AI code action. - * **Stage 2:** Validate AI-generated code, detect misalignment, log corrections. -* **Hook System Integration**: - - * Identify injection points in **Roo Code** for tracking. - * Pre-commit, post-commit, and runtime hooks for tracing execution. -* **`.orchestration/` directory**: - - * Stores intent metadata, execution logs, and reasoning states. -* **Intent-Code Mapping**: - - * Links user intent → AI agent decisions → generated code → execution results. -* **Auditability**: - - * Every code change is traceable to its originating intent. - ---- - -## **2. Architecture Layers** - -### **A. Input Layer (Intent Capture)** - -* **Source:** User commands in the IDE, chat prompts, or code requests. -* **Components:** - - * Intent Parser (NLP model / regex-based) - * Preprocessing Engine (normalize ambiguous input) -* **Output:** Structured intent objects (`JSON/YAML`). - -### **B. Hook System Layer** - -* **Integration Points:** Roo Code Extension - - * **Pre-commit hook:** Captures intent vs proposed AI code. - * **Post-commit hook:** Logs executed code and execution result. - * **Custom Reasoning hooks:** Intercepts AI agent output for validation. -* **Responsibilities:** - - * Validate AI output before commit. - * Trigger state updates in Reasoning Loop. - * Maintain orchestration logs. - -### **C. Orchestration & Reasoning Layer** - -* **State Machine (Two-Stage Loop)**: - - * **Stage 1: Intent → Proposed Code** - - * AI agent generates code based on captured intent. - * Hook system verifies structure and alignment. - * **Stage 2: Code Validation** - - * Execute test cases or lint checks. - * Detect mismatches and suggest corrections. -* **Data Storage:** `.orchestration/` directory - - * Stores: - - * Intent metadata - * AI decisions and reasoning traces - * Validation results - * Hook system logs - -### **D. Storage & Traceability Layer** - -* **File System:** `.orchestration/` for local tracking -* **Optional DB:** Lightweight database (SQLite/PostgreSQL) for: - - * Intent history - * AI agent output logs - * Validation state -* **Purpose:** Allows historical analysis and auditability. - -### **E. Output & Feedback Layer** - -* **Developer Feedback:** - - * Misalignment alerts - * Suggested corrections - * Intent-Code mapping visualizations -* **Metrics & Analysis:** - - * Traceability coverage - * Reasoning loop success rate - * Hook system performance - ---- - -## **3. Development Plan / Workflow** - -1. **Phase 0: Prep** - - * Review `ARCHITECTURE-NOTES.md` for Roo Code injection points. - * Map the cognitive and trust debt decisions → reasoning logic. - * Setup Git repo with **Git Speck Kit**. - -2. **Phase 1: Hook System Implementation** - - * Identify Roo Code extension points for: - - * pre-commit - * post-commit - * runtime reasoning interception - * Build hook scripts. - * Unit test hooks independently. - -3. **Phase 2: Reasoning Loop** - - * Implement two-stage state machine. - * Connect hooks to Reasoning Loop states. - * Implement intent validation logic. - -4. **Phase 3: Orchestration Directory** - - * `.orchestration/` for: - - * intent.json - * reasoning_state.json - * validation_results.json - * Implement read/write APIs for traceability. - -5. **Phase 4: Logging & Traceability** - - * Implement audit logs for every hook event. - * Integrate with Git Speck Kit for code snapshots. - * Enable metrics collection for AI alignment tracking. - -6. **Phase 5: Testing & Validation** - - * Create sample AI-generated code scenarios. - * Test traceability pipeline end-to-end. - * Measure coverage of intent-code alignment. - -7. **Phase 6: Documentation** - - * Maintain `ARCHITECTURE_NOTES.md` and `README.md`. - * Document hook usage, state machine, and orchestration structure. - ---- - -## **4. Tech Stack / Tools** - -* **Git & Git Speck Kit:** Source control, snapshots, hooks. -* **Python / Node.js:** For hooks and orchestration logic. -* **JSON/YAML:** Intent and traceability storage. -* **Roo Code Extension:** Injection points for hook system. -* **Lightweight DB (Optional):** SQLite or PostgreSQL for logs. -* **NLP / Parsing:** Optional intent parsing models. -* **Testing Frameworks:** pytest / Jest for automated validation. - ---- - -## **5. Key Architectural Decisions (From Cognitive & Trust Debt)** - -* Track only **AI-generated code relevant to intent** instead of all outputs. -* Enforce **two-stage validation loop** to prevent drift between intent and code. -* Maintain **self-contained orchestration directory** to simplify tracing and rollback. -* Use **hooks as checkpoints** rather than full code reviews to scale traceability. -* **Metrics-driven design:** Log reasoning steps to improve future AI alignment. diff --git a/src/core/hooks/HookEngine.ts b/src/core/hooks/HookEngine.ts index 99fdf9aa062..9285c67ff80 100644 --- a/src/core/hooks/HookEngine.ts +++ b/src/core/hooks/HookEngine.ts @@ -1,5 +1,6 @@ import { Task } from "../task/Task" -import type { ToolUse, ToolName } from "../../shared/tools" +import type { ToolUse } from "../../shared/tools" +import type { ToolName } from "@roo-code/types" import { OrchestrationDataModel, type ActiveIntent } from "../orchestration/OrchestrationDataModel" import * as vscode from "vscode" import * as path from "path" @@ -111,8 +112,9 @@ export class HookEngine { // Load intent details (for authorization prompt + scope checks) if (!activeIntent) { - activeIntent = await this.dataModel.getIntent(activeIntentId) - if (activeIntent) { + const loadedIntent = await this.dataModel.getIntent(activeIntentId) + if (loadedIntent) { + activeIntent = loadedIntent ;(task as any).activeIntent = activeIntent } } diff --git a/src/core/tools/__tests__/selectActiveIntentTool.spec.ts b/src/core/tools/__tests__/selectActiveIntentTool.spec.ts index 10a54d8492a..25afd3262e1 100644 --- a/src/core/tools/__tests__/selectActiveIntentTool.spec.ts +++ b/src/core/tools/__tests__/selectActiveIntentTool.spec.ts @@ -111,22 +111,11 @@ describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { ) // Execute: Call select_active_intent - const toolUse: ToolUse<"select_active_intent"> = { - type: "tool_use", - id: "tool-1", - name: "select_active_intent", - params: { intent_id: "INT-001" }, - } - - await selectActiveIntentTool.execute( - { intent_id: "INT-001" }, - mockTask, - { - askApproval: vi.fn(), - handleError: mockHandleError, - pushToolResult: mockPushToolResult, - }, - ) + await selectActiveIntentTool.execute({ intent_id: "INT-001" }, mockTask, { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }) // Verify: pushToolResult was called with XML context expect(mockPushToolResult).toHaveBeenCalledTimes(1) @@ -178,15 +167,11 @@ describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { await fs.writeFile(tracePath, "", "utf-8") // Execute - await selectActiveIntentTool.execute( - { intent_id: "INT-002" }, - mockTask, - { - askApproval: vi.fn(), - handleError: mockHandleError, - pushToolResult: mockPushToolResult, - }, - ) + await selectActiveIntentTool.execute({ intent_id: "INT-002" }, mockTask, { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }) // Verify: XML contains "No recent changes" message const contextXml = mockPushToolResult.mock.calls[0][0] @@ -261,15 +246,11 @@ describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { ) // Execute: Select INT-001 - await selectActiveIntentTool.execute( - { intent_id: "INT-001" }, - mockTask, - { - askApproval: vi.fn(), - handleError: mockHandleError, - pushToolResult: mockPushToolResult, - }, - ) + await selectActiveIntentTool.execute({ intent_id: "INT-001" }, mockTask, { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }) // Verify: Only INT-001 trace entry is included const contextXml = mockPushToolResult.mock.calls[0][0] @@ -285,15 +266,11 @@ describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { await fs.writeFile(intentsPath, intentsYaml, "utf-8") // Execute - await selectActiveIntentTool.execute( - { intent_id: "INT-999" }, - mockTask, - { - askApproval: vi.fn(), - handleError: mockHandleError, - pushToolResult: mockPushToolResult, - }, - ) + await selectActiveIntentTool.execute({ intent_id: "INT-999" }, mockTask, { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }) // Verify: Error was returned expect(mockPushToolResult).toHaveBeenCalled() @@ -304,15 +281,11 @@ describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { it("should handle missing intent_id parameter", async () => { // Execute without intent_id - await selectActiveIntentTool.execute( - { intent_id: "" }, - mockTask, - { - askApproval: vi.fn(), - handleError: mockHandleError, - pushToolResult: mockPushToolResult, - }, - ) + await selectActiveIntentTool.execute({ intent_id: "" }, mockTask, { + askApproval: vi.fn(), + handleError: mockHandleError, + pushToolResult: mockPushToolResult, + }) // Verify: Missing parameter error expect(mockSayAndCreateMissingParamError).toHaveBeenCalledWith("select_active_intent", "intent_id") @@ -320,4 +293,3 @@ describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { }) }) }) - From b73021c357d95db1b81e5144d30bc142d374be34 Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 15:40:47 +0300 Subject: [PATCH 10/41] refactor: move hook system files to src/hooks/ to match submission requirements - Move HookEngine.ts from src/core/hooks/ to src/hooks/ - Move OrchestrationDataModel.ts from src/core/orchestration/ to src/hooks/ - Move SelectActiveIntentTool.ts from src/core/tools/ to src/hooks/ - Update all import paths in presentAssistantMessage.ts and test files - Consolidate all hook-related files in clean src/hooks/ directory as required --- src/core/assistant-message/presentAssistantMessage.ts | 5 ++--- .../tools/__tests__/selectActiveIntentTool.spec.ts | 4 ++-- src/{core => }/hooks/HookEngine.ts | 7 ++++--- .../orchestration => hooks}/OrchestrationDataModel.ts | 1 + src/{core/tools => hooks}/SelectActiveIntentTool.ts | 11 ++++++----- 5 files changed, 15 insertions(+), 13 deletions(-) rename src/{core => }/hooks/HookEngine.ts (98%) rename src/{core/orchestration => hooks}/OrchestrationDataModel.ts (99%) rename src/{core/tools => hooks}/SelectActiveIntentTool.ts (93%) diff --git a/src/core/assistant-message/presentAssistantMessage.ts b/src/core/assistant-message/presentAssistantMessage.ts index 708cae5f292..712218af55c 100644 --- a/src/core/assistant-message/presentAssistantMessage.ts +++ b/src/core/assistant-message/presentAssistantMessage.ts @@ -37,11 +37,10 @@ import { generateImageTool } from "../tools/GenerateImageTool" import { applyDiffTool as applyDiffToolClass } from "../tools/ApplyDiffTool" import { isValidToolName, validateToolUse } from "../tools/validateToolUse" import { codebaseSearchTool } from "../tools/CodebaseSearchTool" -import { selectActiveIntentTool } from "../tools/SelectActiveIntentTool" - import { formatResponse } from "../prompts/responses" import { sanitizeToolUseId } from "../../utils/tool-id" -import { HookEngine } from "../hooks/HookEngine" +import { HookEngine } from "../../hooks/HookEngine" +import { selectActiveIntentTool } from "../../hooks/SelectActiveIntentTool" /** * Processes and presents assistant message content to the user interface. diff --git a/src/core/tools/__tests__/selectActiveIntentTool.spec.ts b/src/core/tools/__tests__/selectActiveIntentTool.spec.ts index 25afd3262e1..46837de4da7 100644 --- a/src/core/tools/__tests__/selectActiveIntentTool.spec.ts +++ b/src/core/tools/__tests__/selectActiveIntentTool.spec.ts @@ -4,9 +4,9 @@ import * as fs from "fs/promises" import * as path from "path" import * as os from "os" -import { selectActiveIntentTool } from "../SelectActiveIntentTool" +import { selectActiveIntentTool } from "../../../hooks/SelectActiveIntentTool" import type { ToolUse } from "../../../shared/tools" -import type { AgentTraceEntry } from "../../orchestration/OrchestrationDataModel" +import type { AgentTraceEntry } from "../../../hooks/OrchestrationDataModel" describe("SelectActiveIntentTool - Phase 1 End-to-End Test", () => { let testWorkspaceDir: string diff --git a/src/core/hooks/HookEngine.ts b/src/hooks/HookEngine.ts similarity index 98% rename from src/core/hooks/HookEngine.ts rename to src/hooks/HookEngine.ts index 9285c67ff80..e3c2d6bf1bc 100644 --- a/src/core/hooks/HookEngine.ts +++ b/src/hooks/HookEngine.ts @@ -1,7 +1,7 @@ -import { Task } from "../task/Task" -import type { ToolUse } from "../../shared/tools" +import { Task } from "../core/task/Task" +import type { ToolUse } from "../shared/tools" import type { ToolName } from "@roo-code/types" -import { OrchestrationDataModel, type ActiveIntent } from "../orchestration/OrchestrationDataModel" +import { OrchestrationDataModel, type ActiveIntent } from "./OrchestrationDataModel" import * as vscode from "vscode" import * as path from "path" import * as fs from "fs/promises" @@ -339,3 +339,4 @@ export class HookEngine { } } } + diff --git a/src/core/orchestration/OrchestrationDataModel.ts b/src/hooks/OrchestrationDataModel.ts similarity index 99% rename from src/core/orchestration/OrchestrationDataModel.ts rename to src/hooks/OrchestrationDataModel.ts index f6ab3053b80..5b135509149 100644 --- a/src/core/orchestration/OrchestrationDataModel.ts +++ b/src/hooks/OrchestrationDataModel.ts @@ -257,3 +257,4 @@ This file contains persistent knowledge shared across parallel sessions (Archite return this.orchestrationDir } } + diff --git a/src/core/tools/SelectActiveIntentTool.ts b/src/hooks/SelectActiveIntentTool.ts similarity index 93% rename from src/core/tools/SelectActiveIntentTool.ts rename to src/hooks/SelectActiveIntentTool.ts index 59105fd682e..fedb7364687 100644 --- a/src/core/tools/SelectActiveIntentTool.ts +++ b/src/hooks/SelectActiveIntentTool.ts @@ -1,8 +1,8 @@ -import { Task } from "../task/Task" -import { formatResponse } from "../prompts/responses" -import { BaseTool, ToolCallbacks } from "./BaseTool" -import type { ToolUse } from "../../shared/tools" -import { OrchestrationDataModel } from "../orchestration/OrchestrationDataModel" +import { Task } from "../core/task/Task" +import { formatResponse } from "../core/prompts/responses" +import { BaseTool, ToolCallbacks } from "../core/tools/BaseTool" +import type { ToolUse } from "../shared/tools" +import { OrchestrationDataModel } from "./OrchestrationDataModel" interface SelectActiveIntentParams { intent_id: string @@ -126,3 +126,4 @@ ${recentHistorySection} } export const selectActiveIntentTool = new SelectActiveIntentTool() + From b2c3537c83dced1d316d13608a7f8d91a055508e Mon Sep 17 00:00:00 2001 From: Sumeyaaaa Date: Wed, 18 Feb 2026 16:01:05 +0300 Subject: [PATCH 11/41] chore: add Cursor agent rules and MCP config --- .cursor/mcp.json | 12 ++++++ .cursor/rules/agent.mdc | 81 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) create mode 100644 .cursor/mcp.json create mode 100644 .cursor/rules/agent.mdc diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 00000000000..f5e8c7a7b50 --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "tenxfeedbackanalytics": { + "name": "tenxanalysismcp", + "url": "https://mcppulse.10academy.org/proxy", + "headers": { + "X-Device": "windows", + "X-Coding-Tool": "cursor" + } + } + } + } \ No newline at end of file diff --git a/.cursor/rules/agent.mdc b/.cursor/rules/agent.mdc new file mode 100644 index 00000000000..ebbbcc3e898 --- /dev/null +++ b/.cursor/rules/agent.mdc @@ -0,0 +1,81 @@ +# Roo-Code TRP1 – Agent Rules + +## Project Context +- This is your **Roo-Code** fork for the **TRP1 Intent-Code Traceability & Hook System** challenge. +- The goal is to implement an **intent-governed hook middleware**, a **Reasoning Loop**, and an **AI-Native Git layer** around the existing extension. + +## Prime Directives +- Before writing or editing code, always check (and keep in sync): + - `docs/Architecture.md` – high-level design and phases. + - `ARCHITECTURE_NOTES.md` – Phase 0 execution flow and injection points. + - `SPECS_SUMMARY.md` and `specs/` – intent/spec documents that drive `.orchestration/active_intents.yaml`. + - `.orchestration/active_intents.yaml` – active intents, `owned_scope`, constraints, and acceptance criteria. +- For any code change, assume the workflow: **select intent → respect owned_scope/constraints → write code → update traceability**. + +## Working Style +- Explain your plan briefly before making code changes. +- Prefer **architecture, specs, and tests** first; then implementation. +- Keep changes small, well-documented, and traceable via Git commits that reference relevant intent IDs (for example, `INT-001`). +- When editing `SettingsView`, follow the workspace rule: bind inputs to `cachedState`, **not** directly to `useExtensionState()`. + +## Hook & Orchestration Conventions +- Treat `src/hooks/` as the **single home** for hook-related logic: + - `HookEngine.ts` – pre/post hook middleware boundary. + - `OrchestrationDataModel.ts` – `.orchestration/` sidecar data model. + - `SelectActiveIntentTool.ts` – reasoning-loop tool implementation. +- Treat `.orchestration/` as **machine-managed** sidecar state: + - `active_intents.yaml`, `agent_trace.jsonl`, `intent_map.md`, `AGENT.md`. +- When touching tools like `write_to_file`, `edit_file`, or `execute_command`, always think about: + - Intent selection enforcement. + - Scope checks vs `owned_scope`. + - Trace logging (content hashing, related intent IDs in `agent_trace.jsonl`). + +## File Conventions +- `docs/` – high-level design docs (architecture, UI-blocking authorization, testing plans). +- `specs/` – spec markdowns that feed the generator for `active_intents.yaml`. +- `.orchestration/` – runtime intent and trace artifacts. +- `src/hooks/` – hook engine and orchestration-layer code. +- `src/core/assistant-message/presentAssistantMessage.ts` – main execution router and hook entrypoint. + +## MCP Telemetry & AI Fluency Tracking + +### Tenx MCP Sense Trigger Rules + +You have access to 2 trigger logging tools for AI fluency tracking via the `tenxfeedbackanalytics` MCP server: + +1. **`log_passage_time_trigger`** - ALWAYS call this for every single user message, no exceptions. +2. **`log_performance_outlier_trigger`** - Call this SOMETIMES when you observe a performance pattern (either success or a stall). + +### Mandatory Workflow + +**For EVERY User Message:** +1. **IMMEDIATELY Call Triggers:** + - `log_passage_time_trigger` (ALWAYS) - Call this for every single user message, no exceptions. + - `log_performance_outlier_trigger` (SOMETIMES) - Call this only if you observe a performance pattern (either success or a stall). + +2. **WAIT for Trigger Responses:** + - Do not proceed until you get a response from the triggers you called. + +3. **Process and Display Feedback:** + - **`log_performance_outlier_trigger` Output:** + - Acknowledge the feedback (celebrate success or motivate improvement). + - Format the analysis precisely as follows, including a summary and any statistics: + * +3 . **Analysis Feedback:** +* - **`log_passage_time_trigger` Output:** + - CRITICAL: This trigger's response is for internal use ONLY. NEVER, under any circumstances, show its output to the user. + +4. **Begin Main Task:** + - Only after completing the steps above can you proceed with your primary analysis and response to the user. + +### Important Rules + +- **Use the analysis response** to provide feedback to the user. +- **Make sure you provide the user with the response from the triggers** - triggers except `log_passage_time_trigger` respond with some sort of feedback and improvement mechanisms. +- The analysis should have `*****************************************` at the start and end of feedback view. +- **Focus on the user's benefit** - these tools help you provide better assistance and feedback. +- **Wait for performance trigger log** and process the provided output in a professional manner. +- Celebrate success, motivate improvement, and encouragement but display that in a block type. +- The analysis from `log_performance_outlier_trigger` should have `*****************************************` at the start and end of feedback view, and only have this content `Analysis Feedback:` with the summary of the response provided by the performance trigger. Do not forget to show statistics of the analysis too. +- **You must always show the response at the end of your answer.** +- **Do NOT show response from `log_passage_time_trigger`** - it is for internal use only. \ No newline at end of file From 5820617e79fc748cebce59f9346e4b6889c96f4a Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:50:56 +0300 Subject: [PATCH 12/41] chore: commit .orchestration/.intentignore --- .orchestration/.intentignore | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .orchestration/.intentignore diff --git a/.orchestration/.intentignore b/.orchestration/.intentignore new file mode 100644 index 00000000000..16941e71061 --- /dev/null +++ b/.orchestration/.intentignore @@ -0,0 +1,9 @@ +# Intent Ignore File +# List intent IDs that should be protected from modifications +# One intent ID per line +# Lines starting with # are comments +# +# Example: +# INT-005 # Legacy system - deprecated +# INT-010 # Production critical - manual changes only + From 4bb0d55b63297d3170b8cd4cdab8e4c82c41adc8 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:51:04 +0300 Subject: [PATCH 13/41] chore: commit .orchestration/active_intents.yaml --- .orchestration/active_intents.yaml | 231 ++--------------------------- 1 file changed, 15 insertions(+), 216 deletions(-) diff --git a/.orchestration/active_intents.yaml b/.orchestration/active_intents.yaml index de031ef3b0f..99c64b38ec5 100644 --- a/.orchestration/active_intents.yaml +++ b/.orchestration/active_intents.yaml @@ -1,222 +1,21 @@ active_intents: - id: INT-001 - name: INT-001 — Intent-Code Traceability (Spec) + name: INT-001 — Login & Authentication status: IN_PROGRESS owned_scope: - - src/core/assistant-message/** - - src/core/tools/** - - src/core/hooks/** - - src/core/orchestration/** - - src/core/prompts/** - - .orchestration/** + - src/api/login.ts + - src/api/** constraints: - - Must enforce **intent selection before any destructive tool** - (`write_to_file`, `edit_file`, `apply_diff`, etc.). - - "Must keep **privilege separation**: UI emits events; extension host - executes privileged actions; hooks are middleware." - - Must log **spatially independent** traces via content hashing. + - Must follow REST API conventions + - Must include proper error handling + - Must use secure password hashing (bcrypt or similar) + - Must validate input using Zod schemas acceptance_criteria: - - Agent cannot write code before calling `select_active_intent(intent_id)`. - - "When a file is written, a JSONL entry is appended to - `.orchestration/agent_trace.jsonl` that includes:" - - intent id - - file path - - line range (best-effort) - - "`sha256:` content hash of the modified block" - - "`.orchestration/active_intents.yaml` exists and contains this intent." - created_at: 2026-02-18T08:56:57.063Z - updated_at: 2026-02-18T08:56:57.086Z - spec_hash: sha256:7966563e9a7886587d3c421761708195d8a1ce21addd4632f560965411fd839b - spec_file: specs/INT-001-intent-code-traceability.md - - id: INT-002 - name: INT-002 — Hook System Implementation - status: IN_PROGRESS - owned_scope: - - src/core/hooks/** - - src/core/assistant-message/presentAssistantMessage.ts - - src/core/tools/** - - .orchestration/** - constraints: - - Must integrate with existing `presentAssistantMessage()` function - without breaking current tool execution flow. - - Pre-hooks must run **before** `tool.handle()` is called. - - Post-hooks must run **after** `tool.execute()` completes but before - result is returned. - - Hook system must be non-blocking for non-destructive tools (read-only - operations). - - Must maintain backward compatibility with existing tools. - acceptance_criteria: - - "`HookEngine` class exists in `src/core/hooks/HookEngine.ts`." - - Pre-hook validates intent selection for destructive tools - (`write_to_file`, `edit_file`, `execute_command`, etc.). - - Pre-hook enforces scope validation (file path must be within intent's - `owned_scope`). - - Post-hook logs trace entries to `.orchestration/agent_trace.jsonl` for - mutating actions. - - "`presentAssistantMessage()` integrates `HookEngine` with Pre-Hook and - Post-Hook calls." - - All existing tests pass after hook integration. - created_at: 2026-02-18T08:56:57.094Z - updated_at: 2026-02-18T08:56:57.094Z - spec_hash: sha256:e10e923c607996643684be16016bc8305d7259b543eae623e92b5e49db8b902c - spec_file: specs/INT-002-hook-system-implementation.md - - id: INT-003 - name: INT-003 — Two-Stage Reasoning Loop - status: IN_PROGRESS - owned_scope: - - src/core/hooks/HookEngine.ts - - src/core/prompts/sections/tool-use-guidelines.ts - - src/core/tools/SelectActiveIntentTool.ts - - src/core/task/Task.ts - constraints: - - "**Stage 1 (Reasoning Intercept):** Agent MUST call - `select_active_intent(intent_id)` before any destructive tool." - - "**Stage 2 (Contextualized Action):** Agent receives intent context and - must include it when making code changes." - - System prompt must enforce this protocol in tool-use guidelines. - - Intent context must be injected into the agent's context before code - generation. - acceptance_criteria: - - System prompt includes instructions requiring `select_active_intent` - before code changes. - - "`SelectActiveIntentTool` returns XML `` block with - scope, constraints, and acceptance criteria." - - Pre-hook blocks destructive tools if no active intent is selected. - - Agent receives intent context in subsequent tool calls. - - Intent context is logged in `agent_trace.jsonl` entries. - created_at: 2026-02-18T08:56:57.098Z - updated_at: 2026-02-18T08:56:57.098Z - spec_hash: sha256:a75817698c5b1479c68e43dd41b04752d3a6df7c4af71f3ab60fdedf705e4dda - spec_file: specs/INT-003-reasoning-loop.md - - id: INT-004 - name: INT-004 — Orchestration Directory Management - status: IN_PROGRESS - owned_scope: - - src/core/orchestration/OrchestrationDataModel.ts - - .orchestration/active_intents.yaml - - .orchestration/agent_trace.jsonl - - .orchestration/intent_map.md - - .orchestration/AGENT.md - constraints: - - "`.orchestration/` directory must be machine-managed (not user-edited - directly)." - - "`active_intents.yaml` must be valid YAML and follow the schema defined - in `document.md`." - - "`agent_trace.jsonl` must be append-only (no modifications, only - appends)." - - All file operations must be atomic (write to temp file, then rename). - - Directory and files must be initialized on first use. - acceptance_criteria: - - "`OrchestrationDataModel` class provides methods:" - - "`initialize()`: Creates directory and initializes files if missing." - - "`readActiveIntents()`: Parses and returns active intents." - - "`appendAgentTrace()`: Appends trace entry to JSONL file." - - "`updateIntentMap()`: Updates intent-to-file mapping." - - "`appendAgentKnowledge()`: Appends to AGENT.md." - - All methods handle errors gracefully and log failures. - - Files are created with proper templates if missing. - - YAML parsing validates schema and reports errors clearly. - created_at: 2026-02-18T08:56:57.099Z - updated_at: 2026-02-18T08:56:57.099Z - spec_hash: sha256:659bd435cecc3223171c3fce81f671c26baac9ce354c9a6e3c967164983ed9fb - spec_file: specs/INT-004-orchestration-directory.md - - id: INT-005 - name: INT-005 — Logging & Traceability - status: IN_PROGRESS - owned_scope: - - src/core/hooks/HookEngine.ts` (Post-Hook implementation) - - src/core/orchestration/OrchestrationDataModel.ts - - .orchestration/agent_trace.jsonl - - src/utils/git.ts` (for VCS revision tracking) - constraints: - - Trace entries must include `sha256:` content hash of modified code - blocks. - - Line ranges must be best-effort (may be approximate for complex edits). - - "Each trace entry must link to:" - - Intent ID - - File path (relative to workspace root) - - VCS revision (Git SHA) - - Timestamp - - Model identifier - - Content hashing must be spatially independent (same code block = same - hash regardless of file location). - acceptance_criteria: - - Post-hook computes SHA-256 hash of modified content for file tools. - - "Trace entry includes all required fields per `document.md` schema:" - - "`id` (UUID)" - - "`timestamp` (ISO 8601)" - - "`vcs.revision_id` (Git SHA)" - - "`files[]` with `relative_path`, `conversations[]`, `ranges[]`, - `content_hash`" - - Trace entries are appended atomically to `agent_trace.jsonl`. - - "Content hash format: `sha256:`." - - Git SHA is retrieved from workspace root (handles non-Git repos - gracefully). - created_at: 2026-02-18T08:56:57.099Z - updated_at: 2026-02-18T08:56:57.099Z - spec_hash: sha256:2b3421a22c9e27a817e27aea652f3332cdbc821338b52e112ff654ff88c36317 - spec_file: specs/INT-005-logging-traceability.md - - id: INT-006 - name: INT-006 — Testing & Validation - status: IN_PROGRESS - owned_scope: - - src/core/hooks/**/*.test.ts - - src/core/orchestration/**/*.test.ts - - src/core/tools/SelectActiveIntentTool.test.ts - - tests/integration/hook-system.test.ts - - tests/e2e/intent-traceability.test.ts - constraints: - - Tests must not modify production `.orchestration/` files (use temp - directories). - - Tests must be deterministic and isolated (no shared state). - - Integration tests must verify hook system works with real tool execution. - - E2E tests must simulate full agent workflow (intent selection → code - change → trace logging). - acceptance_criteria: - - Unit tests for `HookEngine.preHook()` and `HookEngine.postHook()`. - - Unit tests for `OrchestrationDataModel` file operations. - - Unit tests for `SelectActiveIntentTool` intent loading and context - generation. - - "Integration test: Verify Pre-Hook blocks destructive tool without - intent." - - "Integration test: Verify Post-Hook logs trace entry after file write." - - "E2E test: Full workflow from intent selection to trace logging." - - All tests pass in CI/CD pipeline. - - Test coverage > 80% for hook and orchestration modules. - created_at: 2026-02-18T08:56:57.099Z - updated_at: 2026-02-18T08:56:57.100Z - spec_hash: sha256:f8343d2839370244e2f1d7b6622494a96438c86b21f42b98b159eb34e33a59c6 - spec_file: specs/INT-006-testing-validation.md - - id: INT-007 - name: INT-007 — Documentation & Knowledge Base - status: IN_PROGRESS - owned_scope: - - ARCHITECTURE_NOTES.md - - README.md` (Intent-Code Traceability section) - - .orchestration/AGENT.md - - docs/intent-traceability/ - - CHANGELOG.md` (relevant entries) - constraints: - - "`ARCHITECTURE_NOTES.md` must document all injection points and hook - integration." - - '`AGENT.md` must be append-only knowledge base for "Lessons Learned".' - - Documentation must be kept in sync with code changes. - - API documentation must include examples for each public method. - acceptance_criteria: - - "`ARCHITECTURE_NOTES.md` includes:" - - Tool execution flow diagram - - Hook injection points with line numbers - - System prompt modification points - - Data model schemas - - "`AGENT.md` includes:" - - Lessons learned from implementation - - Common pitfalls and solutions - - Performance optimizations - - Stylistic rules for intent specifications - - README includes setup instructions and usage examples. - - All public APIs are documented with JSDoc comments. - - Documentation is reviewed and updated with each major change. - created_at: 2026-02-18T08:56:57.100Z - updated_at: 2026-02-18T08:56:57.100Z - spec_hash: sha256:50566c7bdbddce41c4f739cab9631172321f2880e8cb7a35fdf8c0d1a1aa56b4 - spec_file: specs/INT-007-documentation.md + - Login endpoint properly validates credentials + - Registration endpoint creates users securely + - Error handling is consistent across all endpoints + - Code follows project architecture and coding standards + created_at: 2026-02-18T12:00:00.000Z + updated_at: 2026-02-18T12:00:00.000Z + spec_hash: "" + spec_file: "" From 57ea32eec6f2f49050840da44b594a6e4d4826c4 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:51:11 +0300 Subject: [PATCH 14/41] chore: commit .roo/rules-mode-writer/1_mode_creation_workflow.xml --- .../1_mode_creation_workflow.xml | 491 ++++++++++++++++++ 1 file changed, 491 insertions(+) create mode 100644 .roo/rules-mode-writer/1_mode_creation_workflow.xml diff --git a/.roo/rules-mode-writer/1_mode_creation_workflow.xml b/.roo/rules-mode-writer/1_mode_creation_workflow.xml new file mode 100644 index 00000000000..cbdb46741b5 --- /dev/null +++ b/.roo/rules-mode-writer/1_mode_creation_workflow.xml @@ -0,0 +1,491 @@ + + + This workflow guides you through creating new custom modes or editing existing ones + for the Roo Code Software, ensuring comprehensive understanding and cohesive implementation. + + + + + .roomodes in the workspace root directory + + Workspace modes are the default target for project-specific modes and for overrides. + + + + + VS Code globalStorage custom modes settings file (location is environment-specific; open it via the product UI) + + Global modes are used system-wide and are created automatically on Roo Code startup. + + + + + + If the same slug exists in both global modes and workspace modes, the workspace (.roomodes) entry wins. + + + + + + Both files use the same YAML schema: a top-level customModes: list of mode objects. + + + + Mode definitions are YAML objects within customModes:. Use YAML block scalars (e.g., >-) for multi-line text fields when helpful. + + + If you must embed explicit newlines in a quoted string, use \n for newlines and \n\n for blank lines. + + + groups is required and is a YAML array. It may be empty when a mode should not have access to optional permissions. + + + Each groups entry may be: + - a simple string (unrestricted permission group), or + - a structured entry that restricts the permission to a subset of files (e.g., fileRegex + description for edit restrictions). + + + + slug + name + roleDefinition + groups + + + description + whenToUse + + + customInstructions + + + Canonical YAML skeleton (illustrative; keep instructions/tooling details in .roo/rules-[slug]/) + +customModes: + - slug: example-mode + name: Example Mode + description: Short five-word summary + roleDefinition: >- + You are Roo Code, a [specialist type] who... + + Key areas: + - Area one + - Area two + whenToUse: >- + Use this mode when... + groups: + - read + - - edit + - fileRegex: \\.(md|mdx)$ + description: Documentation files only + customInstructions: >- + Optional brief glue text. + + + + + + + + Determine User Intent + + Identify whether the user wants to create a new mode or edit an existing one + + + + + User mentions a specific mode by name or slug + User references a mode directory path (e.g., .roo/rules-[mode-slug]) + User asks to modify, update, enhance, or fix an existing mode + User says "edit this mode" or "change this mode" + + + + + User asks to create a new mode + User describes a new responsibility not covered by existing modes + User says "make a mode for" or "create a mode that" + + + + + + I want to make sure I understand correctly. Are you looking to create a brand new mode or modify an existing one? + + Create a new mode for a specific purpose + Edit an existing mode to add new responsibilities + Fix issues in an existing mode + Enhance an existing mode with better workflows + + + + + + + Resolve Mode Source (Workspace vs Global) + + When the user asks about a specific mode by name/slug (including phrases like "global mode"), resolve where that mode is defined + before doing broad repository searches. + + + + Check the workspace override first by reading .roomodes. + + + If not present (or the user explicitly requests global scope), inspect the global custom modes settings file. + Note: its exact path is determined by the extension at runtime (do not hardcode a machine-specific path). + + + If the mode is workspace-scoped, read its instruction directory .roo/rules-[mode-slug]/. + + + + If the mode entry is found in either .roomodes or the global file, proceed directly to analysis/edits without additional discovery. + + + + + + + + Gather Requirements for New Mode + + Understand what the user wants the new mode to accomplish + + + Ask about the mode's primary purpose and use cases + Identify what types of tasks the mode should handle + Determine what repository access and permissions the mode needs + Clarify any special behaviors or restrictions + + + + What is the primary purpose of this new mode? What types of tasks should it handle? + + A mode for writing and maintaining documentation + A mode for database schema design and migrations + A mode for API endpoint development and testing + A mode for performance optimization and profiling + + + + + + + Design Mode Configuration + + Create the mode definition with all required fields + + + + Default to workspace-scoped modes unless the user explicitly requests a global mode. + + User asks for a mode to be available across all workspaces, or explicitly mentions the global modes file. + + + User asks for a mode for this repo/project only, or wants to commit/share the mode with the repository. + + + + + Unique identifier (lowercase, hyphens allowed) + Keep it short and descriptive (e.g., "api-dev", "docs-writer") + + + Display name with optional emoji + Use an emoji that represents the mode's purpose + + + Detailed description of the mode's role and expertise + + Start with "You are Roo Code, a [specialist type]..." + List specific areas of expertise + Mention key technologies or methodologies + + + + Permission groups the mode can access + + The concrete group names and any nesting structure are runtime-defined and may evolve. + Treat these as conceptual categories and map them to the closest available equivalents. + + + + + + + + + + + + + Short human-readable summary (aim ~5 words) + Keep it scannable and concrete + + + Clear description for the Orchestrator + Explain specific scenarios and task types + + + + Prefer keeping substantial mode guidance in XML files within .roo/rules-[mode-slug]/. + The underlying mode system supports customInstructions, but large instruction blocks there are easier to duplicate/drift. + Use customInstructions only for brief "glue" text when needed. + + Note: the underlying mode system supports a customInstructions field, + but this repository intentionally keeps detailed instructions in + .roo/rules-[mode-slug]/ XML files to avoid duplication and drift. + + + + + Implement File Restrictions + + Configure appropriate file access permissions + + + Restrict edit access to specific file types + +groups: + - read + - - edit + - fileRegex: \.(md|txt|rst)$ + description: Documentation files only + - command + + + + Use regex patterns to limit file editing scope + Provide clear descriptions for restrictions + Consider the principle of least privilege + + + + + Create XML Instruction Files + + Design structured instruction files in .roo/rules-[mode-slug]/ + + + Main workflow and step-by-step processes + Guidelines and conventions + Reusable code patterns and examples + Decision criteria and guardrails + Complete workflow examples + + + Use semantic tag names that describe content + Nest tags hierarchically for better organization + Include code examples in CDATA sections when needed + Add comments to explain complex sections + + + + + + + Immerse in Existing Mode + + Fully understand the existing mode before making any changes + + + Locate and read the mode configuration in .roomodes + When global scope is relevant, locate and read the global custom modes settings file and compare slugs for precedence + Read all XML instruction files in .roo/rules-[mode-slug]/ + Analyze the mode's current scope, permissions, and limitations + Understand the mode's role in the broader ecosystem + + + + What specific aspects of the mode would you like to change or enhance? + + Adjust permissions or restrictions + Fix issues with current workflows or instructions + Improve the mode's roleDefinition or whenToUse description + Enhance XML instructions for better clarity + + + + + + + Analyze Change Impact + + Understand how proposed changes will affect the mode + + + Compatibility with existing workflows + Impact on file permissions and capability access + Consistency with mode's core purpose + Integration with other modes + + + Role and scope: roleDefinition matches actual scope and permissions; remove scope creep + Orchestrator routing: whenToUse/whenNotToUse are explicit and distinct from other modes + Permissions: groups and fileRegex follow least-privilege and match instructions + Instructions hygiene: no contradictions or duplicates across XML files + Naming consistency: tag names and terminology are consistent + Deprecated content: remove legacy fields (e.g., customInstructions in .roomodes) + Boundaries: clear handoffs to other modes; no overlapping responsibilities + + + Search for repeated guidance and conflicting directives across files + + + + I've analyzed the existing mode. Here's what I understand about your requested changes. Is this correct? + + Yes, that's exactly what I want to change + Mostly correct, but let me clarify some details + No, I meant something different + I'd like to add additional changes + + + + + + + Plan Modifications + + Create a detailed plan for modifying the mode + + + Identify which files need to be modified + Determine if new XML instruction files are needed + Check for potential conflicts or contradictions + Plan the order of changes for minimal disruption + + + + Consolidate overlapping instructions into a single source of truth + Align with XML best practices (semantic tags, hierarchical nesting) + Standardize whenToUse/whenNotToUse language and boundaries + Centralize preamble rules and autonomy calibration + + + Tighten fileRegex to least-privilege; add clear descriptions + Ensure instructions match configured permissions + + + Split overly long files; ensure 6_error_handling and 7_communication are present or updated + + + Update 5_examples.xml to reflect new workflows and refactors + Include before/after diffs where helpful + + + + .roomodes: roleDefinition and whenToUse + .roo/rules-[slug]/ XML instruction files + Examples and quick_reference sections + + + + + Silent Self-Reflection Rubric + Privately evaluate the planned changes against a 5–7 category rubric before implementation + + Cohesion across files + Permissions and file restrictions (least privilege) + Orchestrator fit (whenToUse/whenNotToUse clarity) + XML structure and naming consistency + Mode boundaries and handoff points + Examples and testability + + Iterate on the plan until it passes the rubric; do not expose the rubric to the user + + + + Implement Changes + + Apply the planned modifications to the mode + + + Update .roomodes configuration if needed + Modify existing XML instruction files + Create new XML instruction files if required + Update examples and documentation + + + Remove duplicate or contradictory instruction blocks across XML files + Delete or migrate deprecated fields (e.g., customInstructions in .roomodes) + Tighten fileRegex patterns and add clear descriptions + Normalize tag names, terminology, and structure + Ensure whenToUse/whenNotToUse and handoff rules are explicit + + + Validate file restriction patterns against the intended file sets + Confirm permissions match instruction expectations + Re-run validation (section 5) and testing (section 6) + Scan the repository for legacy references and remove/modernize as needed + + + + + + + + Validate Cohesion and Consistency + + Ensure all changes are cohesive and don't contradict each other + + + + Mode slug follows naming conventions + File restrictions align with mode purpose (least privilege) + Permissions are appropriate + whenToUse clearly differentiates from other modes + + + All XML files follow consistent structure + No contradicting instructions between files; contradiction hierarchy and resolutions documented + Examples align with stated workflows + Instructions match granted permissions and file restrictions + + + Mode integrates well with Orchestrator + Clear boundaries with other modes + Handoff points are well-defined + + + + + I've completed the validation checks. Would you like me to review any specific aspect in more detail? + + Review the file permission patterns + Check for workflow contradictions + Verify integration with other modes + Everything looks good, proceed to testing + + + + + + + Test and Refine + + Verify the mode works as intended + + + Mode appears in the mode list + File restrictions work correctly + Instructions are clear and actionable + Mode integrates well with Orchestrator + All examples are accurate and helpful + Changes don't break existing functionality (for edits) + New behavior works as expected + + + + + + Create mode in .roomodes for project-specific modes + Create mode in the global custom modes settings file for system-wide modes (path is environment-specific) + Verify the .roo folder structure contains expected rule directories and XML files + Validate file regex patterns against the intended file sets (avoid overbroad matches) + Find existing mode implementations and patterns to reuse + Read all XML files in a mode directory to understand its structure + Always validate changes for cohesion and consistency + + From e6a33774230371409f379385fd9df35ec8962847 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:51:27 +0300 Subject: [PATCH 15/41] chore: commit .roo/rules-mode-writer/2_xml_structuring_best_practices.xml --- .../2_xml_structuring_best_practices.xml | 240 ++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 .roo/rules-mode-writer/2_xml_structuring_best_practices.xml diff --git a/.roo/rules-mode-writer/2_xml_structuring_best_practices.xml b/.roo/rules-mode-writer/2_xml_structuring_best_practices.xml new file mode 100644 index 00000000000..8ba9dbed660 --- /dev/null +++ b/.roo/rules-mode-writer/2_xml_structuring_best_practices.xml @@ -0,0 +1,240 @@ + + + XML tags help LLMs parse prompts more accurately, leading to higher-quality outputs. + This guide covers best practices for structuring mode instructions using XML. + + + + + Clearly separate different parts of your instructions and ensure well-structured content + + + Reduce errors caused by the model misinterpreting parts of your instructions + + + Easily find, add, remove, or modify parts of instructions without rewriting everything + + + Having the model use XML tags in its output makes it easier to extract specific parts of responses + + + + + + Use the same tag names throughout your instructions + + Always use for workflow steps, not sometimes or + + + + + Tag names should clearly describe their content + + detailed_steps + error_handling + validation_rules + + + stuff + misc + data1 + + + + + Nest tags to show relationships and structure + + + + Gather requirements + Validate inputs + + + Process data + Generate output + + + + + + + + + For step-by-step processes + + + + + For providing code examples and demonstrations + + + + + For rules and best practices + + + + + For documenting decision criteria and guardrails + + + + + + + Use consistent indentation (2 or 4 spaces) for nested elements + + + Add line breaks between major sections for readability + + + Use XML comments to explain complex sections + + + Use CDATA for code blocks or content with special characters: + your code here + + + Use attributes for metadata, elements for content: + + + The actual step content + + + + + Keep narrative outputs concise; reserve detailed exposition for code, diffs, and structured outputs. Prefer readable, maintainable code with clear names; avoid one-liners unless explicitly requested. + + + + + + Avoid completely flat structures without hierarchy + + + +Do this + +Then this + +Finally this + + + + + + + Do this + Then this + Finally this + + + + + + + Don't mix naming conventions + + Mixing camelCase, snake_case, and kebab-case in tag names + + + Pick one convention (preferably snake_case for XML) and stick to it + + + + + Avoid tags that don't convey meaning + data, info, stuff, thing, item + user_input, validation_result, error_message, configuration + + + Avoid asking the user to confirm obvious next steps on straightforward tasks + Asking multiple clarifying questions before acting when the task is simple + Proceed when next steps are clear; ask only when critical ambiguity remains; document assumptions + + + + Avoid repetitive or redundant searches when the relevant target is already identified + Running multiple identical searches instead of acting + Stop once the change is clearly identified; then implement + + + + Avoid duplicating runtime behavior that is already defined elsewhere + Documenting execution constraints, operation ordering, or invocation details + Focus on intent, artifacts, decision criteria, and validation expectations + + + + + + Reference XML content in instructions: + "Using the workflow defined in <workflow> tags..." + + + Combine XML structure with other techniques like multishot prompting + + + Use XML tags in expected outputs to make parsing easier + + + Create reusable XML templates for common patterns + + + From cf97a026c4f62593dead4a326d17c30e77a1b1a0 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:51:37 +0300 Subject: [PATCH 16/41] chore: commit .roo/rules-mode-writer/3_mode_configuration_patterns.xml --- .../3_mode_configuration_patterns.xml | 307 ++++++++++++++++++ 1 file changed, 307 insertions(+) create mode 100644 .roo/rules-mode-writer/3_mode_configuration_patterns.xml diff --git a/.roo/rules-mode-writer/3_mode_configuration_patterns.xml b/.roo/rules-mode-writer/3_mode_configuration_patterns.xml new file mode 100644 index 00000000000..16c1f5f24cb --- /dev/null +++ b/.roo/rules-mode-writer/3_mode_configuration_patterns.xml @@ -0,0 +1,307 @@ + + + Common patterns and templates for creating different types of modes, with examples from existing modes in the Roo-Code software. + + + + + + Modes focused on specific technical domains or tasks + + + Deep expertise in a particular area + Restricted file access based on domain + Specialized workflows and decision criteria + + +- slug: api-specialist + name: 🔌 API Specialist + roleDefinition: >- + You are Roo Code, an API development specialist with expertise in: + - RESTful API design and implementation + - GraphQL schema design + - API documentation with OpenAPI/Swagger + - Authentication and authorization patterns + - Rate limiting and caching strategies + - API versioning and deprecation + + You ensure APIs are: + - Well-documented and discoverable + - Following REST principles or GraphQL best practices + - Secure and performant + - Properly versioned and maintainable + whenToUse: >- + Use this mode when designing, implementing, or refactoring APIs. + This includes creating new endpoints, updating API documentation, + implementing authentication, or optimizing API performance. + groups: + - read + - - edit + - fileRegex: (api/.*\.(ts|js)|.*\.openapi\.yaml|.*\.graphql|docs/api/.*)$ + description: API implementation files, OpenAPI specs, and API documentation + - command + - mcp + + + + + + Modes that guide users through multi-step processes + + + Step-by-step workflow guidance + Heavy use of focused clarifying questions + Process validation at each step + + +- slug: migration-guide + name: 🔄 Migration Guide + roleDefinition: >- + You are Roo Code, a migration specialist who guides users through + complex migration processes: + - Database schema migrations + - Framework version upgrades + - API version migrations + - Dependency updates + - Breaking change resolutions + + You provide: + - Step-by-step migration plans + - Automated migration scripts + - Rollback strategies + - Testing approaches for migrations + whenToUse: >- + Use this mode when performing any kind of migration or upgrade. + This mode will analyze the current state, plan the migration, + and guide you through each step with validation. + groups: + - read + - edit + - command + + + + + + Modes focused on code analysis and reporting + + + Read-heavy operations + Limited or no edit permissions + Comprehensive reporting outputs + + +- slug: security-auditor + name: 🔒 Security Auditor + roleDefinition: >- + You are Roo Code, a security analysis specialist focused on: + - Identifying security vulnerabilities + - Analyzing authentication and authorization + - Reviewing data validation and sanitization + - Checking for common security anti-patterns + - Evaluating dependency vulnerabilities + - Assessing API security + + You provide detailed security reports with: + - Vulnerability severity ratings + - Specific remediation steps + - Security best practice recommendations + whenToUse: >- + Use this mode to perform security audits on codebases. + This mode will analyze code for vulnerabilities, check + dependencies, and provide actionable security recommendations. + groups: + - read + - command + - - edit + - fileRegex: (SECURITY\.md|\.github/security/.*|docs/security/.*)$ + description: Security documentation files only + + + + + + Modes for generating new content or features + + + Broad file creation permissions + Template and boilerplate generation + Interactive design process + + +- slug: component-designer + name: 🎨 Component Designer + roleDefinition: >- + You are Roo Code, a UI component design specialist who creates: + - Reusable React/Vue/Angular components + - Component documentation and examples + - Storybook stories + - Unit tests for components + - Accessibility-compliant interfaces + + You follow design system principles and ensure components are: + - Highly reusable and composable + - Well-documented with examples + - Fully tested + - Accessible (WCAG compliant) + - Performance optimized + whenToUse: >- + Use this mode when creating new UI components or refactoring + existing ones. This mode helps design component APIs, implement + the components, and create comprehensive documentation. + groups: + - read + - - edit + - fileRegex: (components/.*|stories/.*|__tests__/.*\.test\.(tsx?|jsx?))$ + description: Component files, stories, and component tests + - browser + - command + + + + + + Configuration patterns to keep modes focused, cohesive, and clearly scoped + + Prefer a single source of truth for each rule; avoid duplicated instructions + Prefer least privilege; keep file restrictions aligned with purpose + Define acceptance criteria and validation gates for typical tasks + Define explicit boundaries and handoff points to other modes + Keep narrative brief; reserve detail for structured outputs and diffs + + + + Tight scope, least privilege, clear boundaries; prefer small targeted changes + + + Step-by-step process with validation gates; ask clarifying questions only when necessary + + + Read-heavy; edits typically constrained to reporting or documentation outputs + + + Broader creation scope; ensure examples and tests are included when applicable + + + + + + + For modes that only work with documentation + +groups: + - read + - - edit + - fileRegex: \.(md|mdx|rst|txt)$ + description: Documentation files only + + + + + For modes that work with test files + +groups: + - read + - command + - - edit + - fileRegex: (__tests__/.*|__mocks__/.*|.*\.test\.(ts|tsx|js|jsx)$|.*\.spec\.(ts|tsx|js|jsx)$) + description: Test files and mocks + + + + + For modes that manage configuration + +groups: + - read + - - edit + - fileRegex: (.*\.config\.(js|ts|json)|.*rc\.json|.*\.yaml|.*\.yml|\.env\.example)$ + description: Configuration files (not .env) + + + + + For modes that need broad access + +groups: + - read + - edit # No restrictions + - command + - browser + - mcp + + + + + + + Use lowercase with hyphens + api-dev, test-writer, docs-manager + apiDev, test_writer, DocsManager + + + + Use title case with descriptive emoji + 🔧 API Developer, 📝 Documentation Writer + api developer, DOCUMENTATION WRITER + + + + + 🧪 + 📝 + 🎨 + 🪲 + 🏗️ + 🔒 + 🔌 + 🗄️ + ⚡ + ⚙️ + + + + + + + Ensure whenToUse/whenNotToUse are clear for Orchestrator mode + + Specify concrete task types the mode handles + Include trigger keywords or phrases + Differentiate from similar modes + Mention specific file types or areas + Define whenNotToUse with negative triggers and explicit handoffs + State stop/ask/handoff rules + State default verbosity policy (low narrative; verbose diffs) + + + + + Define explicit stop conditions, confirmation thresholds, and handoff/ask triggers + + Done-ness: acceptance criteria and validation gates are defined + Handoff rules to other modes or “ask a clarifying question” conditions are explicit + Boundaries, risks, and validation gates are documented + + + + + Set verbosity defaults to keep narrative short and code edits clear + + Low narrative verbosity in status/progress text + High detail only inside code/diffs and structured outputs + Code clarity over cleverness; avoid code-golf and cryptic names + + + + + Define clear boundaries between modes + + Avoid overlapping responsibilities + Make handoff points explicit + Switch modes when appropriate (mechanism varies) + Document mode interactions + + + + From 0e74759492dca33d5b1d861104896ff96ed91a63 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:51:48 +0300 Subject: [PATCH 17/41] chore: commit .roo/rules-mode-writer/4_instruction_file_templates.xml --- .../4_instruction_file_templates.xml | 293 ++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100644 .roo/rules-mode-writer/4_instruction_file_templates.xml diff --git a/.roo/rules-mode-writer/4_instruction_file_templates.xml b/.roo/rules-mode-writer/4_instruction_file_templates.xml new file mode 100644 index 00000000000..fcc2bba9196 --- /dev/null +++ b/.roo/rules-mode-writer/4_instruction_file_templates.xml @@ -0,0 +1,293 @@ + + + Templates and examples for creating XML instruction files that provide + detailed guidance for each mode's behavior and workflows. + + Requirements: + - Do not reference runtime implementation details (function names, command names, UI entry points, or execution syntax). + - Do not duplicate operational policies that are already defined by the runtime/system prompt. + - Focus on workflow intent, required artifacts, decision criteria, and validation expectations. + + + + Number files to indicate execution order + Use descriptive names that indicate content + Keep related instructions together + + 1_workflow.xml - Main workflow and processes + 2_best_practices.xml - Guidelines and conventions + 3_common_patterns.xml - Reusable code patterns + 4_decision_guidance.xml - Decision criteria and guardrails + 5_examples.xml - Complete workflow examples + 6_error_handling.xml - Error scenarios and recovery + 7_communication.xml - User interaction guidelines + + + + + Template for main workflow files (1_workflow.xml) + + + + + Template for best practices files (2_best_practices.xml) + + + + + Template for decision criteria and guardrails (4_decision_guidance.xml) + + + + + Template for example files (5_examples.xml) + + + + + Template for communication guidelines (7_communication.xml) + + + From 69f314fe4bdcb1c3aab6df53ebc3e9e7df5934fe Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:52:02 +0300 Subject: [PATCH 18/41] chore: commit .roo/rules-mode-writer/5_complete_mode_examples.xml --- .../5_complete_mode_examples.xml | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 .roo/rules-mode-writer/5_complete_mode_examples.xml diff --git a/.roo/rules-mode-writer/5_complete_mode_examples.xml b/.roo/rules-mode-writer/5_complete_mode_examples.xml new file mode 100644 index 00000000000..31e54859e20 --- /dev/null +++ b/.roo/rules-mode-writer/5_complete_mode_examples.xml @@ -0,0 +1,91 @@ + + + Canonical examples for creating and editing Roo Code modes. Each example demonstrates structured workflows, least-privilege configuration, contradiction resolution, and completion formatting, without referencing runtime implementation details. + + + + + Edit the Test mode to add benchmark testing and performance guidance using Vitest's bench API. + + + I want to edit the test mode to add benchmark testing support. + + + + Clarify scope and features + + Ask the user a focused clarifying question to confirm which scope/features to include; provide 2–4 actionable options. Outcome: selected scope. + + User selects: Add benchmark testing with Vitest bench API + + + + Immerse in current mode config and instructions + + Review .roomodes, inventory .roo/rules-test recursively, and review .roo/rules-test/1_workflow.xml. Outcome: confirm roleDefinition, file restrictions, and existing workflows. + + Confirm roleDefinition, file restrictions, and existing workflows. + + + + Update roleDefinition in .roomodes + + Edit .roomodes to update the roleDefinition, adding benchmark testing and performance guidance topics. Outcome: roleDefinition updated to include performance/bench themes. + + + + + Extend file restrictions to include .bench files + + Edit .roomodes to extend the fileRegex to include .bench.(ts|tsx|js|jsx) and update the description accordingly. Outcome: file restrictions now cover benchmark files. + + + + + Create benchmark guidance file + + Create a new file at .roo/rules-test/5_benchmark_testing.xml with guidance and examples. Outcome: new guidance file available to the mode. + + + + Guidelines for performance benchmarks using Vitest bench API + + + Basic structure + +import { bench, describe } from 'vitest'; + + +describe('Array operations', () => { + bench('Array.push', () => { + const arr: number[] = []; + for (let i = 0; i < 1000; i++) arr.push(i); + }); + + bench('Array spread', () => { + let arr: number[] = []; + for (let i = 0; i < 1000; i++) arr = [...arr, i]; + }); +}); + + + + + Use meaningful names and isolate benchmarks + Document expectations and thresholds + + + + + + + + Provide a concise summary of what was accomplished and how it addresses the user's request. + + + + Important lesson from this example + Pattern that can be reused + + + From ae1717a4159883ec758cdd92179f9aaf729d7587 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:52:11 +0300 Subject: [PATCH 19/41] chore: commit .roo/rules-mode-writer/6_mode_testing_validation.xml --- .../6_mode_testing_validation.xml | 186 ++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 .roo/rules-mode-writer/6_mode_testing_validation.xml diff --git a/.roo/rules-mode-writer/6_mode_testing_validation.xml b/.roo/rules-mode-writer/6_mode_testing_validation.xml new file mode 100644 index 00000000000..8274fb7d769 --- /dev/null +++ b/.roo/rules-mode-writer/6_mode_testing_validation.xml @@ -0,0 +1,186 @@ + + + Guidelines for testing and validating newly created modes to ensure they function correctly and integrate well with the Roo Code ecosystem. + + + + + + Mode slug is unique and follows naming conventions + No spaces, lowercase, hyphens only + + + All required fields are present and non-empty + slug, name, roleDefinition, groups + + + Avoid large customInstructions blocks in .roomodes + + Prefer storing substantial mode guidance in XML files under .roo/rules-[slug]/. + Small, high-level glue text in customInstructions is acceptable when needed. + + + + File restrictions use valid regex patterns + Validate by comparing the regex pattern against the intended file sets; confirm patterns match intended files and avoid overbroad matches. + + + whenToUse clearly differentiates from other modes + Compare with existing mode descriptions + + + + + + XML files are well-formed and valid + No syntax errors, proper closing tags + + + Instructions follow XML best practices + Semantic tag names, proper nesting + + + Examples avoid runtime implementation details + Examples align with current permissions and constraints + + + File paths in examples are consistent + Use project-relative paths + + + + + + Mode appears in mode list + Switch to the new mode and verify it loads + + + Permissions work as expected + Verify representative actions for each permission category + + + File restrictions are enforced + Attempt to edit allowed and restricted files + + + Mode handles edge cases gracefully + Test with minimal input, errors, edge cases + + + + + + + Configuration Testing + + Verify mode appears in available modes list + Check that mode metadata displays correctly + Confirm mode can be activated + + Confirm via user feedback. If unclear, ask a focused clarifying question with options like: "Visible and switchable", "Not visible", or "Visible but errors". + + + + Permission Testing + + + Verify read access works for representative files + All read operations should work + + + Try editing allowed file types + Edits succeed for matching patterns + + + Try editing restricted file types + An explicit permission/restriction error for non-matching files + + + + + + Workflow Testing + + Execute main workflow from start to finish + Test each decision point + Verify error handling + Check completion criteria + + + + + Integration Testing + + Orchestrator mode compatibility + Mode switching functionality + Capability handoff between modes + Consistent behavior with other modes + + + + + + + Mode doesn't appear in list + + Syntax error in YAML + Invalid mode slug + File not saved + + Check YAML syntax, validate slug format + + + + File restriction not working + + Invalid regex pattern + Escaping issues in regex + Wrong file path format + + Test regex pattern, use proper escaping + +# Wrong: *.ts (glob pattern) + +# Right: .*\.ts$ (regex pattern) + + + + + Mode not following instructions + + Instructions not in .roo/rules-[slug]/ folder + XML parsing errors + Conflicting instructions + + Verify file locations and XML validity + + + + + + Directory/file inventory + Verify instruction files exist in the correct location + Check the .roo directory structure and ensure the expected rules-[slug] folder and XML files exist. + + + + Configuration review + Check mode configuration syntax + Review .roomodes to validate YAML structure and entries for the target mode. + + + + Regex validation + Test file restriction patterns + Use targeted checks conceptually to confirm fileRegex patterns match intended files and exclude others. + + + + + Test incrementally as you build the mode + Start with minimal configuration and add complexity + Document any special requirements or dependencies + Consider edge cases and error scenarios + Get feedback from potential users of the mode + + From 317aea53dd74d3d0f1cd2feff6f3e56512bc6f76 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:52:26 +0300 Subject: [PATCH 20/41] chore: commit .roo/rules-mode-writer/7_validation_cohesion_checking.xml --- .../7_validation_cohesion_checking.xml | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 .roo/rules-mode-writer/7_validation_cohesion_checking.xml diff --git a/.roo/rules-mode-writer/7_validation_cohesion_checking.xml b/.roo/rules-mode-writer/7_validation_cohesion_checking.xml new file mode 100644 index 00000000000..50ec594fb78 --- /dev/null +++ b/.roo/rules-mode-writer/7_validation_cohesion_checking.xml @@ -0,0 +1,194 @@ + + + Guidelines for thoroughly validating mode changes to ensure cohesion, + consistency, and prevent contradictions across all mode components. + + + + + + Every change must be reviewed in context of the entire mode + + + Read all existing XML instruction files + Verify new changes align with existing patterns + Check for duplicate or conflicting instructions + Ensure terminology is consistent throughout + + + + + + Ask focused clarifying questions only when needed to de-risk the work + + + Critical details are missing (cannot proceed safely) + Multiple valid approaches exist and the tradeoffs matter + Proposed changes are risky/irreversible (permissions, deletions, broad refactors) + A change may require widening permissions or fileRegex patterns + + + In practice: ask a focused question with 2–4 actionable options. + Example: + - Question: "This change may affect file permissions. Should we also update the fileRegex patterns?" + - Options: + 1) "Yes, include the new file types in the regex" + 2) "No, keep current restrictions" + 3) "I need to list the file types I’ll work with" + 4) "Show me the current restrictions first" + + + + + + Actively search for and resolve contradictions + + + + Permission Mismatch + Instructions reference permissions the mode doesn't have + Either grant the permission or update the instructions + + + Workflow Conflicts + Different XML files describe conflicting workflows + Consolidate workflows and ensure single source of truth + + + Role Confusion + Mode's roleDefinition doesn't match its actual scope/permissions + Update roleDefinition to accurately reflect the mode's purpose + + + + + + + + Before making any changes + + Read and understand all existing mode files + Create a mental model of current mode behavior + Identify potential impact areas + Ask clarifying questions about intended changes + + + + + While making changes + + Document each change and its rationale + Cross-reference with other files after each change + Verify examples still work with new changes + Update related documentation immediately + + + + + After changes are complete + + + All XML files are well-formed and valid + File naming follows established patterns + Tag names are consistent across files + No orphaned or unused instructions + + + + roleDefinition accurately describes the mode + whenToUse is clear and distinguishable + Permissions match instruction requirements + File restrictions align with mode purpose + Examples are accurate and functional + + + + Mode boundaries are well-defined + Handoff points to other modes are clear + No overlap with other modes' responsibilities + Orchestrator can correctly route to this mode + + + + + + + + Maintain consistent tone and terminology + + Use the same terms for the same concepts throughout + Keep instruction style consistent across files + Maintain the same level of detail in similar sections + + + + + Ensure instructions flow logically + + Prerequisites come before dependent steps + Complex concepts build on simpler ones + Examples follow the explained patterns + + + + + Ensure all aspects are covered without gaps + + Every mentioned concept has decision guidance (what/when) without runtime implementation details + All workflows have complete examples + Error scenarios are addressed + + + + + + + + Before we proceed with changes, ensure the main goal is clear. Suggested options: + - Add new functionality while keeping existing features + - Fix issues with current implementation + - Refactor for better organization + - Expand the mode's scope into new areas + + + + + + This change might affect other parts of the mode. Choose an approach: + - Update all affected areas to maintain consistency + - Keep the existing behavior for backward compatibility + - Create a migration path from old to new behavior + - Review the impact first + + + + + + Post-change testing focus areas: + - Test the new workflow end-to-end + - Verify file permissions work correctly + - Check integration with other modes + - Review all changes one more time + + + + + + + Instructions reference permissions not in the mode's groups + Either add the permission group or remove/update the instruction + + + File regex doesn't match described file types + Update regex pattern to match intended files + + + Examples don't follow stated best practices + Update examples to demonstrate best practices + + + Duplicate instructions in different files + Consolidate to single location and reference + + + From 154cf99f9568f1ad4cbd738c0f5a91b521d95abc Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:52:40 +0300 Subject: [PATCH 21/41] chore: commit .roo/rules-mode-writer/8_global_modes.xml --- .roo/rules-mode-writer/8_global_modes.xml | 51 +++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 .roo/rules-mode-writer/8_global_modes.xml diff --git a/.roo/rules-mode-writer/8_global_modes.xml b/.roo/rules-mode-writer/8_global_modes.xml new file mode 100644 index 00000000000..7d5f984ea6c --- /dev/null +++ b/.roo/rules-mode-writer/8_global_modes.xml @@ -0,0 +1,51 @@ + + + This reference documents how global (system-wide) modes work, where they live, and how they interact + with workspace-scoped modes. + + + + + .roomodes + Per-workspace (project) modes + + + + Global custom modes settings file (stored in VS Code globalStorage; exact path is environment-specific) + System-wide modes for Roo Code + + This file is created automatically on Roo Code startup if it does not exist. + + + + + + + When a mode with the same slug exists in both locations, the workspace (.roomodes) version takes precedence. + + + + Editing the global mode may have no visible effect inside a workspace that overrides the same slug. + + + To change behavior in one repo only, prefer editing .roomodes. + + + + + + + Default to editing .roomodes unless the user explicitly requests global scope. + + If the user asks for global scope, first check whether a workspace override exists for the same slug. + If it does, explain the precedence and offer to edit both. + + + + + + Prefer minimal, targeted changes and preserve YAML formatting. + + + + From 7a2dade2f9afb8b3dab6c2ca3041b4972cd99edb Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:52:49 +0300 Subject: [PATCH 22/41] chore: commit .roomodes --- .roomodes | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/.roomodes b/.roomodes index ba17940035a..a905324f188 100644 --- a/.roomodes +++ b/.roomodes @@ -146,3 +146,43 @@ customModes: - command - mcp source: project + - slug: mode-writer + name: ✍️ Mode Writer + roleDefinition: | + You are Roo, a mode creation and editing specialist focused on designing, implementing, and enhancing custom modes for the Roo-Code project. + + Your expertise includes: + - Understanding the mode system architecture and configuration + - Creating well-structured mode definitions with clear roles and responsibilities + - Editing and enhancing existing modes while maintaining consistency + - Writing comprehensive XML-based special instructions using best practices + - Ensuring modes have appropriate tool group permissions + - Crafting clear whenToUse descriptions for the Orchestrator + - Following XML structuring best practices for clarity and parseability + - Validating changes for cohesion and preventing contradictions + + You help users by: + - Creating new modes: Gathering requirements, defining configurations, and implementing XML instructions + - Editing existing modes: Immersing in current implementation, analyzing requested changes, and ensuring cohesive updates + - Asking focused clarifying questions when critical details are missing, choices are ambiguous, or changes are risky/irreversible + - Thoroughly validating all changes to prevent contradictions between different parts of a mode + - Ensuring instructions are well-organized with proper XML tags + - Following established patterns from existing modes + - Maintaining consistency across all mode components + + You also understand the difference between workspace-scoped modes and global modes, including: + - Workspace modes in .roomodes (highest precedence) + - Global modes in VS Code globalStorage custom_modes.yaml (used when a workspace override does not exist) + whenToUse: | + Use this mode when you need to create a new custom mode or edit an existing one. + + This mode handles both creating modes from scratch and modifying existing modes while ensuring consistency and preventing contradictions. + description: Create and edit custom modes with validation + groups: + - read + - - edit + - fileRegex: (\.roomodes$|\.roo/.*\.xml$|\.yaml$) + description: Mode configuration files and XML instructions + - command + - mcp + source: project From e243a67cbaecad11c1783609335ce2aefb19fff7 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:52:59 +0300 Subject: [PATCH 23/41] chore: commit .vscode/launch.json --- .vscode/launch.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 5f023be65ba..fbff6a6255b 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -1,7 +1,3 @@ -// A launch configuration that compiles the extension and then opens it inside a new window -// Use IntelliSense to learn about possible attributes. -// Hover to view descriptions of existing attributes. -// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 { "version": "0.2.0", "configurations": [ From 6a603e2b78caa476b9277277351453ba0e52a536 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:53:16 +0300 Subject: [PATCH 24/41] chore: commit docs/Architecture.md --- docs/Architecture.md | 197 +++++++------------------------------------ 1 file changed, 32 insertions(+), 165 deletions(-) diff --git a/docs/Architecture.md b/docs/Architecture.md index 4ebec88ec70..022e0d3c265 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -1,180 +1,47 @@ -## **1. Project Overview** +# Project Architecture -**Goal:** -Develop an **Intent-Code Traceability system** for the AI-Native IDE that ensures AI-generated code aligns with user intent and can be tracked, reasoned over, and verified. +## Overview -**Core Features:** +This is a TypeScript/Node.js project with an API layer, services, and type definitions. -- **Two-stage Reasoning Loop** (State Machine): +## Directory Structure - - **Stage 1:** Capture client intent, map to AI code action. - - **Stage 2:** Validate AI-generated code, detect misalignment, log corrections. +### API Layer (`src/api/`) -- **Hook System Integration**: +- REST API endpoints and route handlers +- Request/response validation using Zod schemas +- Authentication endpoints (login, register, etc.) +- Error handling middleware - - Identify injection points in **Roo Code** for tracking. - - Pre-commit, post-commit, and runtime hooks for tracing execution. +### Services (`src/services/`) -- **`.orchestration/` directory**: +- Business logic layer +- Database operations +- External API integrations +- User management services - - Stores intent metadata, execution logs, and reasoning states. +### Types (`src/types/`) -- **Intent-Code Mapping**: +- TypeScript type definitions +- Shared interfaces and types +- User models and DTOs - - Links user intent → AI agent decisions → generated code → execution results. +### Configuration (`src/config/`) -- **Auditability**: +- Environment variables +- Application configuration +- Constants (JWT secrets, expiration times, etc.) - - Every code change is traceable to its originating intent. +## Key Technologies ---- +- Express.js for API routes +- Zod for schema validation +- JWT for authentication +- TypeScript for type safety -## **2. Architecture Layers** +## Intent Areas -### **A. Input Layer (Intent Capture)** - -- **Source:** User commands in the IDE, chat prompts, or code requests. -- **Components:** - - - Intent Parser (NLP model / regex-based) - - Preprocessing Engine (normalize ambiguous input) - -- **Output:** Structured intent objects (`JSON/YAML`). - -### **B. Hook System Layer** - -- **Integration Points:** Roo Code Extension - - - **Pre-commit hook:** Captures intent vs proposed AI code. - - **Post-commit hook:** Logs executed code and execution result. - - **Custom Reasoning hooks:** Intercepts AI agent output for validation. - -- **Responsibilities:** - - - Validate AI output before commit. - - Trigger state updates in Reasoning Loop. - - Maintain orchestration logs. - -### **C. Orchestration & Reasoning Layer** - -- **State Machine (Two-Stage Loop)**: - - - **Stage 1: Intent → Proposed Code** - - - AI agent generates code based on captured intent. - - Hook system verifies structure and alignment. - - - **Stage 2: Code Validation** - - - Execute test cases or lint checks. - - Detect mismatches and suggest corrections. - -- **Data Storage:** `.orchestration/` directory - - - Stores: - - - Intent metadata - - AI decisions and reasoning traces - - Validation results - - Hook system logs - -### **D. Storage & Traceability Layer** - -- **File System:** `.orchestration/` for local tracking -- **Optional DB:** Lightweight database (SQLite/PostgreSQL) for: - - - Intent history - - AI agent output logs - - Validation state - -- **Purpose:** Allows historical analysis and auditability. - -### **E. Output & Feedback Layer** - -- **Developer Feedback:** - - - Misalignment alerts - - Suggested corrections - - Intent-Code mapping visualizations - -- **Metrics & Analysis:** - - - Traceability coverage - - Reasoning loop success rate - - Hook system performance - ---- - -## **3. Development Plan / Workflow** - -1. **Phase 0: Prep** - - - Review `ARCHITECTURE-NOTES.md` for Roo Code injection points. - - Map the cognitive and trust debt decisions → reasoning logic. - - Setup Git repo with **Git Speck Kit**. - -2. **Phase 1: Hook System Implementation** - - - Identify Roo Code extension points for: - - - pre-commit - - post-commit - - runtime reasoning interception - - - Build hook scripts. - - Unit test hooks independently. - -3. **Phase 2: Reasoning Loop** - - - Implement two-stage state machine. - - Connect hooks to Reasoning Loop states. - - Implement intent validation logic. - -4. **Phase 3: Orchestration Directory** - - - `.orchestration/` for: - - - intent.json - - reasoning_state.json - - validation_results.json - - - Implement read/write APIs for traceability. - -5. **Phase 4: Logging & Traceability** - - - Implement audit logs for every hook event. - - Integrate with Git Speck Kit for code snapshots. - - Enable metrics collection for AI alignment tracking. - -6. **Phase 5: Testing & Validation** - - - Create sample AI-generated code scenarios. - - Test traceability pipeline end-to-end. - - Measure coverage of intent-code alignment. - -7. **Phase 6: Documentation** - - - Maintain `ARCHITECTURE_NOTES.md` and `README.md`. - - Document hook usage, state machine, and orchestration structure. - ---- - -## **4. Tech Stack / Tools** - -- **Git & Git Speck Kit:** Source control, snapshots, hooks. -- **Python / Node.js:** For hooks and orchestration logic. -- **JSON/YAML:** Intent and traceability storage. -- **Roo Code Extension:** Injection points for hook system. -- **Lightweight DB (Optional):** SQLite or PostgreSQL for logs. -- **NLP / Parsing:** Optional intent parsing models. -- **Testing Frameworks:** pytest / Jest for automated validation. - ---- - -## **5. Key Architectural Decisions (From Cognitive & Trust Debt)** - -- Track only **AI-generated code relevant to intent** instead of all outputs. -- Enforce **two-stage validation loop** to prevent drift between intent and code. -- Maintain **self-contained orchestration directory** to simplify tracing and rollback. -- Use **hooks as checkpoints** rather than full code reviews to scale traceability. -- **Metrics-driven design:** Log reasoning steps to improve future AI alignment. +1. **API Development** - All API endpoints and handlers in `src/api/**` +2. **Service Layer** - Business logic in `src/services/**` +3. **Type Definitions** - Type system in `src/types/**` +4. **Configuration** - Config management in `src/config/**` From 9b14d1b3b8feee17f6949409280d9c1ee5c4149b Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:53:33 +0300 Subject: [PATCH 25/41] chore: commit docs/Architecture_.md --- docs/Architecture_.md | 180 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 docs/Architecture_.md diff --git a/docs/Architecture_.md b/docs/Architecture_.md new file mode 100644 index 00000000000..4ebec88ec70 --- /dev/null +++ b/docs/Architecture_.md @@ -0,0 +1,180 @@ +## **1. Project Overview** + +**Goal:** +Develop an **Intent-Code Traceability system** for the AI-Native IDE that ensures AI-generated code aligns with user intent and can be tracked, reasoned over, and verified. + +**Core Features:** + +- **Two-stage Reasoning Loop** (State Machine): + + - **Stage 1:** Capture client intent, map to AI code action. + - **Stage 2:** Validate AI-generated code, detect misalignment, log corrections. + +- **Hook System Integration**: + + - Identify injection points in **Roo Code** for tracking. + - Pre-commit, post-commit, and runtime hooks for tracing execution. + +- **`.orchestration/` directory**: + + - Stores intent metadata, execution logs, and reasoning states. + +- **Intent-Code Mapping**: + + - Links user intent → AI agent decisions → generated code → execution results. + +- **Auditability**: + + - Every code change is traceable to its originating intent. + +--- + +## **2. Architecture Layers** + +### **A. Input Layer (Intent Capture)** + +- **Source:** User commands in the IDE, chat prompts, or code requests. +- **Components:** + + - Intent Parser (NLP model / regex-based) + - Preprocessing Engine (normalize ambiguous input) + +- **Output:** Structured intent objects (`JSON/YAML`). + +### **B. Hook System Layer** + +- **Integration Points:** Roo Code Extension + + - **Pre-commit hook:** Captures intent vs proposed AI code. + - **Post-commit hook:** Logs executed code and execution result. + - **Custom Reasoning hooks:** Intercepts AI agent output for validation. + +- **Responsibilities:** + + - Validate AI output before commit. + - Trigger state updates in Reasoning Loop. + - Maintain orchestration logs. + +### **C. Orchestration & Reasoning Layer** + +- **State Machine (Two-Stage Loop)**: + + - **Stage 1: Intent → Proposed Code** + + - AI agent generates code based on captured intent. + - Hook system verifies structure and alignment. + + - **Stage 2: Code Validation** + + - Execute test cases or lint checks. + - Detect mismatches and suggest corrections. + +- **Data Storage:** `.orchestration/` directory + + - Stores: + + - Intent metadata + - AI decisions and reasoning traces + - Validation results + - Hook system logs + +### **D. Storage & Traceability Layer** + +- **File System:** `.orchestration/` for local tracking +- **Optional DB:** Lightweight database (SQLite/PostgreSQL) for: + + - Intent history + - AI agent output logs + - Validation state + +- **Purpose:** Allows historical analysis and auditability. + +### **E. Output & Feedback Layer** + +- **Developer Feedback:** + + - Misalignment alerts + - Suggested corrections + - Intent-Code mapping visualizations + +- **Metrics & Analysis:** + + - Traceability coverage + - Reasoning loop success rate + - Hook system performance + +--- + +## **3. Development Plan / Workflow** + +1. **Phase 0: Prep** + + - Review `ARCHITECTURE-NOTES.md` for Roo Code injection points. + - Map the cognitive and trust debt decisions → reasoning logic. + - Setup Git repo with **Git Speck Kit**. + +2. **Phase 1: Hook System Implementation** + + - Identify Roo Code extension points for: + + - pre-commit + - post-commit + - runtime reasoning interception + + - Build hook scripts. + - Unit test hooks independently. + +3. **Phase 2: Reasoning Loop** + + - Implement two-stage state machine. + - Connect hooks to Reasoning Loop states. + - Implement intent validation logic. + +4. **Phase 3: Orchestration Directory** + + - `.orchestration/` for: + + - intent.json + - reasoning_state.json + - validation_results.json + + - Implement read/write APIs for traceability. + +5. **Phase 4: Logging & Traceability** + + - Implement audit logs for every hook event. + - Integrate with Git Speck Kit for code snapshots. + - Enable metrics collection for AI alignment tracking. + +6. **Phase 5: Testing & Validation** + + - Create sample AI-generated code scenarios. + - Test traceability pipeline end-to-end. + - Measure coverage of intent-code alignment. + +7. **Phase 6: Documentation** + + - Maintain `ARCHITECTURE_NOTES.md` and `README.md`. + - Document hook usage, state machine, and orchestration structure. + +--- + +## **4. Tech Stack / Tools** + +- **Git & Git Speck Kit:** Source control, snapshots, hooks. +- **Python / Node.js:** For hooks and orchestration logic. +- **JSON/YAML:** Intent and traceability storage. +- **Roo Code Extension:** Injection points for hook system. +- **Lightweight DB (Optional):** SQLite or PostgreSQL for logs. +- **NLP / Parsing:** Optional intent parsing models. +- **Testing Frameworks:** pytest / Jest for automated validation. + +--- + +## **5. Key Architectural Decisions (From Cognitive & Trust Debt)** + +- Track only **AI-generated code relevant to intent** instead of all outputs. +- Enforce **two-stage validation loop** to prevent drift between intent and code. +- Maintain **self-contained orchestration directory** to simplify tracing and rollback. +- Use **hooks as checkpoints** rather than full code reviews to scale traceability. +- **Metrics-driven design:** Log reasoning steps to improve future AI alignment. From 5356de21f4889806637de38c92109a18bc15196b Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:53:50 +0300 Subject: [PATCH 26/41] chore: commit document.md --- document.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/document.md b/document.md index eb3f2450216..c36994fd246 100644 --- a/document.md +++ b/document.md @@ -141,7 +141,7 @@ Deliverable: ARCHITECTURE_NOTES.md. Phase 1: The Handshake (Reasoning Loop Implementation) Goal: Solve the Context Paradox. Bridge the synchronous LLM with the asynchronous IDE loop. Define the Tool: Create a new tool definition: select_active_intent(intent_id: string). -Context Loader (Pre-Hook): Before the extension sends a prompt to the LLM, intercept the payload. Read the corresponding entries in active_intents.yaml, identify related agent trace entries for the active intent the agent is processing, and prepare a consolidated intent context. +Context Loader (Pre-Hook): Before the extension sends a prompt to the LLM, intercept the payload. Read the corresponding entries in active_intent.yaml, identify related agent trace entries for the active intent the agent is processing, and prepare a consolidated intent context. Prompt Engineering: Modify the System Prompt to enforce the protocol: "You are an Intent-Driven Architect. You CANNOT write code immediately. Your first action MUST be to analyze the user request and call select_active_intent to load the necessary context." Context Injection Hook: From 6135f01a0de3e9e7e26d9fce73a92769fef4ad6d Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:54:05 +0300 Subject: [PATCH 27/41] chore: commit packages/types/src/tool.ts --- packages/types/src/tool.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/types/src/tool.ts b/packages/types/src/tool.ts index 3655a5f29ed..1ec969f71be 100644 --- a/packages/types/src/tool.ts +++ b/packages/types/src/tool.ts @@ -47,6 +47,8 @@ export const toolNames = [ "generate_image", "custom_tool", "select_active_intent", + "create_intent", + "record_lesson", ] as const export const toolNamesSchema = z.enum(toolNames) From b467f516653b8a3b99e3c5b97c72bd716e762ff6 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:54:23 +0300 Subject: [PATCH 28/41] chore: commit SELECT_ACTIVE_INTENT_DEBUG_FILES.md --- SELECT_ACTIVE_INTENT_DEBUG_FILES.md | 127 ++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 SELECT_ACTIVE_INTENT_DEBUG_FILES.md diff --git a/SELECT_ACTIVE_INTENT_DEBUG_FILES.md b/SELECT_ACTIVE_INTENT_DEBUG_FILES.md new file mode 100644 index 00000000000..2199ba12e59 --- /dev/null +++ b/SELECT_ACTIVE_INTENT_DEBUG_FILES.md @@ -0,0 +1,127 @@ +# Files Related to `select_active_intent` Parsing Error + +## Core Issue + +The error: `[NativeToolCallParser] Invalid arguments for tool 'select_active_intent'. Native tool calls require a valid JSON payload matching the tool schema. Received: {"intent_id":"INT-008"}` + +The arguments look correct, but the parser is failing to create `nativeArgs`. This suggests the validation logic in the switch statement is failing. + +## Critical Files to Review + +### 1. **NativeToolCallParser.ts** (Main Parser) + +**Path:** `src/core/assistant-message/NativeToolCallParser.ts` + +- **Lines 721-770:** JSON parsing logic (handles concatenated JSON, double-stringify) +- **Lines 1045-1050:** `select_active_intent` case in the switch statement +- **Lines 1115-1122:** Error handling/catch block +- **Key Issue:** Check if `args.intent_id !== undefined` validation is working correctly + +### 2. **tools.ts** (Type Definitions) + +**Path:** `src/shared/tools.ts` + +- **Line 84:** `intent_id` in `toolParamNames` array +- **Line 125:** `select_active_intent: { intent_id: string }` in `NativeToolArgs` +- **Key Issue:** Verify `intent_id` is properly included in the compiled code + +### 3. **SelectActiveIntentTool.ts** (Tool Implementation) + +**Path:** `src/hooks/SelectActiveIntentTool.ts` + +- **Lines 18-106:** `execute()` method that receives parameters +- **Line 19:** `const { intent_id } = params` - expects `intent_id` from params +- **Key Issue:** Tool expects `nativeArgs` to contain `intent_id` + +### 4. **BaseTool.ts** (Base Class) + +**Path:** `src/core/tools/BaseTool.ts` + +- **Lines 128-157:** Parameter extraction logic +- **Line 131:** `if (block.nativeArgs !== undefined)` - checks for nativeArgs +- **Line 148:** Throws error if `nativeArgs` is missing +- **Key Issue:** If parser doesn't create `nativeArgs`, this will fail + +### 5. **presentAssistantMessage.ts** (Tool Execution) + +**Path:** `src/core/assistant-message/presentAssistantMessage.ts` + +- **Lines 702-708:** `select_active_intent` case in switch statement +- **Key Issue:** Calls `selectActiveIntentTool.handle()` with the block + +### 6. **select_active_intent.ts** (Tool Definition for LLM) + +**Path:** `src/core/prompts/tools/native-tools/select_active_intent.ts` + +- **Lines 1-27:** OpenAI function definition +- **Key Issue:** Defines the schema the LLM should follow + +## Debugging Steps + +1. **Check if `args` object is created correctly:** + + - In `NativeToolCallParser.ts` line 725, verify `JSON.parse()` succeeds + - Check if concatenated JSON fix is working (lines 726-753) + +2. **Check if `nativeArgs` is created:** + + - In `NativeToolCallParser.ts` line 1047, verify `args.intent_id !== undefined` passes + - Add console.log to see what `args` contains at this point + +3. **Check if validation fails:** + + - In `NativeToolCallParser.ts` line 1041, verify `nativeArgs` is not undefined + - The error is thrown at line 1042-1046 if `nativeArgs` is undefined + +4. **Verify compiled code:** + - Check `src/dist/extension.js` to ensure fixes are compiled + - Search for `select_active_intent` case in compiled code + +## Potential Root Causes + +1. **Parser not creating `nativeArgs`:** + + - The switch case validation `args.intent_id !== undefined` might be failing + - `args` might be empty object `{}` instead of `{intent_id: "INT-008"}` + +2. **Type mismatch:** + + - `args.intent_id` might be `null` or empty string instead of a valid string + - Check if `args.intent_id` is truthy, not just defined + +3. **Compilation issue:** + + - The fixes might not be in the compiled `extension.js` + - Need to rebuild: `cd src && node esbuild.mjs` + +4. **Extension host using old code:** + - Extension Development Host might be running cached code + - Need to fully restart (close all Extension Development Host windows, press F5) + +## Quick Fix to Try + +In `NativeToolCallParser.ts` around line 1047, change: + +```typescript +case "select_active_intent": + if (args.intent_id !== undefined) { + nativeArgs = { + intent_id: args.intent_id, + } as NativeArgsFor + } + break +``` + +To: + +```typescript +case "select_active_intent": + if (args.intent_id !== undefined && args.intent_id !== null && args.intent_id !== "") { + nativeArgs = { + intent_id: String(args.intent_id), + } as NativeArgsFor + } + break +``` + +This adds more robust validation and ensures `intent_id` is a non-empty string. From ed7d8f540baf9f6d248bb1ad1736cbf0d4beca93 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:54:39 +0300 Subject: [PATCH 29/41] chore: commit src/api/login.ts --- src/api/login.ts | 138 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 src/api/login.ts diff --git a/src/api/login.ts b/src/api/login.ts new file mode 100644 index 00000000000..5644d59540d --- /dev/null +++ b/src/api/login.ts @@ -0,0 +1,138 @@ +// Trying the hook +import { z } from "zod" +import { sign } from "jsonwebtoken" +import { Request, Response } from "express" +import { User } from "../types/user" +import { getUserByEmail, createUser } from "../services/user-service" +import { JWT_SECRET, JWT_EXPIRES_IN } from "../config" + +interface LoginRequest { + email: string + password: string +} + +const loginSchema = z.object({ + email: z.string().email("Invalid email address"), + password: z.string().min(6, "Password must be at least 6 characters"), +}) + +// Trying a roo code extention again +type LoginRequestValidated = z.infer +// trying the roo code using openai + +export async function loginHandler(req: Request, res: Response) { + try { + // Validate request body + const loginData = loginSchema.parse(req.body) + + // Find user by email + const user = await getUserByEmail(loginData.email) + + if (!user) { + return res.status(401).json({ + error: "Invalid credentials", + message: "Email or password is incorrect", + }) + } + + // Verify password (in a real implementation, use bcrypt or similar) + if (user.password !== loginData.password) { + return res.status(401).json({ + error: "Invalid credentials", + message: "Email or password is incorrect", + }) + } + + // Generate JWT token + const token = sign( + { + userId: user.id, + email: user.email, + role: user.role, + }, + JWT_SECRET, + { expiresIn: JWT_EXPIRES_IN }, + ) // Still trying - needs proper password hashing implementation + + // Return success response with token + res.json({ + success: true, + message: "Login successful", + data: { + token, + user: { + id: user.id, + email: user.email, + name: user.name, + role: user.role, + }, + }, + }) + } catch (error) { + console.error("Login error:", error) + res.status(500).json({ + error: "Internal server error", + message: "An error occurred during login", + }) + } +} + +export async function registerHandler(req: Request, res: Response) { + try { + // Validate request body + const loginData = loginSchema.parse(req.body) + + // Check if user already exists + const existingUser = await getUserByEmail(loginData.email) + if (existingUser) { + return res.status(409).json({ + error: "User already exists", + message: "An account with this email already exists", + }) + } + + // Create new user + const newUser: User = { + id: crypto.randomUUID(), + email: loginData.email, + password: loginData.password, // In production, hash this! + name: loginData.email.split("@")[0], // Default name from email + role: "user", + createdAt: new Date().toISOString(), + } + + await createUser(newUser) + + // Generate JWT token + const token = sign( + { + userId: newUser.id, + email: newUser.email, + role: newUser.role, + }, + JWT_SECRET, + { expiresIn: JWT_EXPIRES_IN }, + ) + + // Return success response with token + res.status(201).json({ + success: true, + message: "Registration successful", + data: { + token, + user: { + id: newUser.id, + email: newUser.email, + name: newUser.name, + role: newUser.role, + }, + }, + }) + } catch (error) { + console.error("Registration error:", error) + res.status(500).json({ + error: "Internal server error", + message: "An error occurred during registration", + }) + } +} From 87f444db8828b4f7353820e87aa3c311241e05f7 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:54:49 +0300 Subject: [PATCH 30/41] chore: commit src/core/assistant-message/NativeToolCallParser.ts --- .../assistant-message/NativeToolCallParser.ts | 82 ++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/src/core/assistant-message/NativeToolCallParser.ts b/src/core/assistant-message/NativeToolCallParser.ts index e0ea1383f17..312b7c02734 100644 --- a/src/core/assistant-message/NativeToolCallParser.ts +++ b/src/core/assistant-message/NativeToolCallParser.ts @@ -636,6 +636,29 @@ export class NativeToolCallParser { } break + case "select_active_intent": + if (partialArgs.intent_id !== undefined) { + nativeArgs = { + intent_id: partialArgs.intent_id, + } + } + break + + case "create_intent": + if (partialArgs.prompt !== undefined) { + nativeArgs = { + prompt: partialArgs.prompt, + intent_id: partialArgs.intent_id, + intent_name: partialArgs.intent_name, + owned_scope: Array.isArray(partialArgs.owned_scope) ? partialArgs.owned_scope : undefined, + constraints: Array.isArray(partialArgs.constraints) ? partialArgs.constraints : undefined, + acceptance_criteria: Array.isArray(partialArgs.acceptance_criteria) + ? partialArgs.acceptance_criteria + : undefined, + } + } + break + default: break } @@ -697,7 +720,41 @@ export class NativeToolCallParser { try { // Parse the arguments JSON string - const args = toolCall.arguments === "" ? {} : JSON.parse(toolCall.arguments) + let args: any + try { + args = toolCall.arguments === "" ? {} : JSON.parse(toolCall.arguments) + } catch (parseError) { + // Some models/providers may concatenate multiple JSON objects together, e.g. + // arguments: "{\"intent_id\":\"INT-008\"}{\"path\":\"...\"}" + // In this case, JSON.parse() will fail. Extract only the first valid JSON object. + const firstBrace = toolCall.arguments.indexOf("{") + if (firstBrace >= 0) { + try { + let braceCount = 0 + let endIndex = firstBrace + for (let i = firstBrace; i < toolCall.arguments.length; i++) { + if (toolCall.arguments[i] === "{") braceCount++ + if (toolCall.arguments[i] === "}") braceCount-- + if (braceCount === 0) { + endIndex = i + 1 + break + } + } + const firstJson = toolCall.arguments.substring(firstBrace, endIndex) + args = JSON.parse(firstJson) + console.warn( + `[NativeToolCallParser] Recovered from concatenated JSON arguments for tool '${toolCall.name}'. ` + + `Extracted first JSON object (${firstJson.length} chars) from ${toolCall.arguments.length} char input.`, + ) + } catch (extractError) { + // If extraction fails, re-throw the original parse error + throw parseError + } + } else { + // No JSON object found, re-throw the original parse error + throw parseError + } + } // Build stringified params for display/logging. // Tool execution MUST use nativeArgs (typed) and does not support legacy fallbacks. @@ -984,6 +1041,29 @@ export class NativeToolCallParser { } break + case "select_active_intent": + if (args.intent_id !== undefined) { + nativeArgs = { + intent_id: args.intent_id, + } as NativeArgsFor + } + break + + case "create_intent": + if (args.prompt !== undefined) { + nativeArgs = { + prompt: args.prompt, + intent_id: args.intent_id, + intent_name: args.intent_name, + owned_scope: Array.isArray(args.owned_scope) ? args.owned_scope : undefined, + constraints: Array.isArray(args.constraints) ? args.constraints : undefined, + acceptance_criteria: Array.isArray(args.acceptance_criteria) + ? args.acceptance_criteria + : undefined, + } as NativeArgsFor + } + break + default: if (customToolRegistry.has(resolvedName)) { nativeArgs = args as NativeArgsFor From 78ceecf77d5c1d5e1de155a65463199ab4761fcf Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:55:01 +0300 Subject: [PATCH 31/41] chore: commit src/core/assistant-message/presentAssistantMessage.ts --- .../presentAssistantMessage.ts | 362 ++++++++---------- 1 file changed, 164 insertions(+), 198 deletions(-) diff --git a/src/core/assistant-message/presentAssistantMessage.ts b/src/core/assistant-message/presentAssistantMessage.ts index 712218af55c..c185f7f30a2 100644 --- a/src/core/assistant-message/presentAssistantMessage.ts +++ b/src/core/assistant-message/presentAssistantMessage.ts @@ -1,5 +1,7 @@ import { serializeError } from "serialize-error" import { Anthropic } from "@anthropic-ai/sdk" +import * as path from "path" +import * as fs from "fs/promises" import type { ToolName, ClineAsk, ToolProgressStatus } from "@roo-code/types" import { ConsecutiveMistakeError, TelemetryEventName } from "@roo-code/types" @@ -41,24 +43,12 @@ import { formatResponse } from "../prompts/responses" import { sanitizeToolUseId } from "../../utils/tool-id" import { HookEngine } from "../../hooks/HookEngine" import { selectActiveIntentTool } from "../../hooks/SelectActiveIntentTool" +import { createIntentTool } from "../../hooks/CreateIntentTool" +import { recordLessonTool } from "../../hooks/RecordLessonTool" /** * Processes and presents assistant message content to the user interface. - * - * This function is the core message handling system that: - * - Sequentially processes content blocks from the assistant's response. - * - Displays text content to the user. - * - Executes tool use requests with appropriate user approval. - * - Manages the flow of conversation by determining when to proceed to the next content block. - * - Coordinates file system checkpointing for modified files. - * - Controls the conversation state to determine when to continue to the next request. - * - * The function uses a locking mechanism to prevent concurrent execution and handles - * partial content blocks during streaming. It's designed to work with the streaming - * API response pattern, where content arrives incrementally and needs to be processed - * as it becomes available. */ - export async function presentAssistantMessage(cline: Task) { if (cline.abort) { throw new Error(`[Task#presentAssistantMessage] task ${cline.taskId}.${cline.instanceId} aborted`) @@ -73,10 +63,6 @@ export async function presentAssistantMessage(cline: Task) { cline.presentAssistantMessageHasPendingUpdates = false if (cline.currentStreamingContentIndex >= cline.assistantMessageContent.length) { - // This may happen if the last content block was completed before - // streaming could finish. If streaming is finished, and we're out of - // bounds then this means we already presented/executed the last - // content block and are ready to continue to next request. if (cline.didCompleteReadingStream) { cline.userMessageContentReady = true } @@ -87,10 +73,6 @@ export async function presentAssistantMessage(cline: Task) { let block: any try { - // Performance optimization: Use shallow copy instead of deep clone. - // The block is used read-only throughout this function - we never mutate its properties. - // We only need to protect against the reference changing during streaming, not nested mutations. - // This provides 80-90% reduction in cloning overhead (5-100ms saved per block). block = { ...cline.assistantMessageContent[cline.currentStreamingContentIndex] } } catch (error) { console.error(`ERROR cloning block:`, error) @@ -104,13 +86,9 @@ export async function presentAssistantMessage(cline: Task) { switch (block.type) { case "mcp_tool_use": { - // Handle native MCP tool calls (from mcp_serverName_toolName dynamic tools) - // These are converted to the same execution path as use_mcp_tool but preserve - // their original name in API history const mcpBlock = block as McpToolUse if (cline.didRejectTool) { - // For native protocol, we must send a tool_result for every tool_use to avoid API errors const toolCallId = mcpBlock.id const errorMessage = !mcpBlock.partial ? `Skipping MCP tool ${mcpBlock.name} due to user rejecting a previous tool.` @@ -127,11 +105,8 @@ export async function presentAssistantMessage(cline: Task) { break } - // Track if we've already pushed a tool result let hasToolResult = false const toolCallId = mcpBlock.id - - // Store approval feedback to merge into tool result (GitHub #10465) let approvalFeedback: { text: string; images?: string[] } | undefined const pushToolResult = (content: ToolResponse, feedbackImages?: string[]) => { @@ -155,12 +130,9 @@ export async function presentAssistantMessage(cline: Task) { "(tool did not return anything)" } - // Merge approval feedback into tool result (GitHub #10465) if (approvalFeedback) { const feedbackText = formatResponse.toolApprovedWithFeedback(approvalFeedback.text) resultContent = `${feedbackText}\n\n${resultContent}` - - // Add feedback images to the image blocks if (approvalFeedback.images) { const feedbackImageBlocks = formatResponse.imageBlocks(approvalFeedback.images) imageBlocks = [...feedbackImageBlocks, ...imageBlocks] @@ -209,9 +181,6 @@ export async function presentAssistantMessage(cline: Task) { return false } - // Store approval feedback to be merged into tool result (GitHub #10465) - // Don't push it as a separate tool_result here - that would create duplicates. - // The tool will call pushToolResult, which will merge the feedback into the actual result. if (text) { await cline.say("user_feedback", text, images) approvalFeedback = { text, images } @@ -221,8 +190,6 @@ export async function presentAssistantMessage(cline: Task) { } const handleError = async (action: string, error: Error) => { - // Silently ignore AskIgnoredError - this is an internal control flow - // signal, not an actual error. It occurs when a newer ask supersedes an older one. if (error instanceof AskIgnoredError) { return } @@ -235,13 +202,10 @@ export async function presentAssistantMessage(cline: Task) { } if (!mcpBlock.partial) { - cline.recordToolUsage("use_mcp_tool") // Record as use_mcp_tool for analytics + cline.recordToolUsage("use_mcp_tool") TelemetryService.instance.captureToolUsage(cline.taskId, "use_mcp_tool") } - // Resolve sanitized server name back to original server name - // The serverName from parsing is sanitized (e.g., "my_server" from "my server") - // We need the original name to find the actual MCP connection const mcpHub = cline.providerRef.deref()?.getMcpHub() let resolvedServerName = mcpBlock.serverName if (mcpHub) { @@ -251,8 +215,6 @@ export async function presentAssistantMessage(cline: Task) { } } - // Execute the MCP tool using the same handler as use_mcp_tool - // Create a synthetic ToolUse block that the useMcpToolTool can handle const syntheticToolUse: ToolUse<"use_mcp_tool"> = { type: "tool_use", id: mcpBlock.id, @@ -285,10 +247,6 @@ export async function presentAssistantMessage(cline: Task) { let content = block.content if (content) { - // Have to do this for partial and complete since sending - // content in thinking tags to markdown renderer will - // automatically be removed. - // Strip any streamed tags from text output. content = content.replace(/\s?/g, "") content = content.replace(/\s?<\/thinking>/g, "") } @@ -297,13 +255,10 @@ export async function presentAssistantMessage(cline: Task) { break } case "tool_use": { - // Native tool calling is the only supported tool calling mechanism. - // A tool_use block without an id is invalid and cannot be executed. const toolCallId = (block as any).id as string | undefined if (!toolCallId) { const errorMessage = "Invalid tool call: missing tool_use.id. XML tool calls are no longer supported. Remove any XML tool markup (e.g. ...) and use native tool calling instead." - // Record a tool error for visibility/telemetry. Use the reported tool name if present. try { if ( typeof (cline as any).recordToolError === "function" && @@ -321,7 +276,6 @@ export async function presentAssistantMessage(cline: Task) { break } - // Fetch state early so it's available for toolDescription and validation const state = await cline.providerRef.deref()?.getState() const { mode, customModes, experiments: stateExperiments, disabledTools } = state ?? {} @@ -330,8 +284,6 @@ export async function presentAssistantMessage(cline: Task) { case "execute_command": return `[${block.name} for '${block.params.command}']` case "read_file": - // Prefer native typed args when available; fall back to legacy params - // Check if nativeArgs exists (native protocol) if (block.nativeArgs) { return readFileTool.getReadFileToolDescription(block.name, block.nativeArgs) } @@ -339,7 +291,6 @@ export async function presentAssistantMessage(cline: Task) { case "write_to_file": return `[${block.name} for '${block.params.path}']` case "apply_diff": - // Native-only: tool args are structured (no XML payloads). return block.params?.path ? `[${block.name} for '${block.params.path}']` : `[${block.name}]` case "search_files": return `[${block.name} for '${block.params.regex}'${ @@ -390,8 +341,6 @@ export async function presentAssistantMessage(cline: Task) { } if (cline.didRejectTool) { - // Ignore any tool content after user has rejected tool once. - // For native tool calling, we must send a tool_result for every tool_use to avoid API errors const errorMessage = !block.partial ? `Skipping tool ${toolDescription()} due to user rejecting a previous tool.` : `Tool ${toolDescription()} was interrupted and not executed due to user rejecting a previous tool.` @@ -406,16 +355,8 @@ export async function presentAssistantMessage(cline: Task) { break } - // Track if we've already pushed a tool result for this tool call (native tool calling only) let hasToolResult = false - // If this is a native tool call but the parser couldn't construct nativeArgs - // (e.g., malformed/unfinished JSON in a streaming tool call), we must NOT attempt to - // execute the tool. Instead, emit exactly one structured tool_result so the provider - // receives a matching tool_result for the tool_use_id. - // - // This avoids executing an invalid tool_use block and prevents duplicate/fragmented - // error reporting. if (!block.partial) { const customTool = stateExperiments?.customTools ? customToolRegistry.get(block.name) : undefined const isKnownTool = isValidToolName(String(block.name), stateExperiments) @@ -431,8 +372,6 @@ export async function presentAssistantMessage(cline: Task) { // Best-effort only } - // Push tool_result directly without setting didAlreadyUseTool so streaming can - // continue gracefully. cline.pushToolResultToUserContent({ type: "tool_result", tool_use_id: sanitizeToolUseId(toolCallId), @@ -444,11 +383,9 @@ export async function presentAssistantMessage(cline: Task) { } } - // Store approval feedback to merge into tool result (GitHub #10465) let approvalFeedback: { text: string; images?: string[] } | undefined const pushToolResult = (content: ToolResponse) => { - // Native tool calling: only allow ONE tool_result per tool call if (hasToolResult) { console.warn( `[presentAssistantMessage] Skipping duplicate tool_result for tool_use_id: ${toolCallId}`, @@ -469,7 +406,6 @@ export async function presentAssistantMessage(cline: Task) { "(tool did not return anything)" } - // Merge approval feedback into tool result (GitHub #10465) if (approvalFeedback) { const feedbackText = formatResponse.toolApprovedWithFeedback(approvalFeedback.text) resultContent = `${feedbackText}\n\n${resultContent}` @@ -507,7 +443,6 @@ export async function presentAssistantMessage(cline: Task) { ) if (response !== "yesButtonClicked") { - // Handle both messageResponse and noButtonClicked with text. if (text) { await cline.say("user_feedback", text, images) pushToolResult(formatResponse.toolResult(formatResponse.toolDeniedWithFeedback(text), images)) @@ -518,9 +453,6 @@ export async function presentAssistantMessage(cline: Task) { return false } - // Store approval feedback to be merged into tool result (GitHub #10465) - // Don't push it as a separate tool_result here - that would create duplicates. - // The tool will call pushToolResult, which will merge the feedback into the actual result. if (text) { await cline.say("user_feedback", text, images) approvalFeedback = { text, images } @@ -530,17 +462,11 @@ export async function presentAssistantMessage(cline: Task) { } const askFinishSubTaskApproval = async () => { - // Ask the user to approve this task has completed, and he has - // reviewed it, and we can declare task is finished and return - // control to the parent task to continue running the rest of - // the sub-tasks. const toolMessage = JSON.stringify({ tool: "finishTask" }) return await askApproval("tool", toolMessage) } const handleError = async (action: string, error: Error) => { - // Silently ignore AskIgnoredError - this is an internal control flow - // signal, not an actual error. It occurs when a newer ask supersedes an older one. if (error instanceof AskIgnoredError) { return } @@ -555,13 +481,11 @@ export async function presentAssistantMessage(cline: Task) { } if (!block.partial) { - // Check if this is a custom tool - if so, record as "custom_tool" (like MCP tools) const isCustomTool = stateExperiments?.customTools && customToolRegistry.has(block.name) const recordName = isCustomTool ? "custom_tool" : block.name cline.recordToolUsage(recordName) TelemetryService.instance.captureToolUsage(cline.taskId, recordName) - // Track legacy format usage for read_file tool (for migration monitoring) if (block.name === "read_file" && block.usedLegacyFormat) { const modelInfo = cline.api.getModel() TelemetryService.instance.captureEvent(TelemetryEventName.READ_FILE_LEGACY_FORMAT_USED, { @@ -571,14 +495,9 @@ export async function presentAssistantMessage(cline: Task) { } } - // Validate tool use before execution - ONLY for complete (non-partial) blocks. - // Validating partial blocks would cause validation errors to be thrown repeatedly - // during streaming, pushing multiple tool_results for the same tool_use_id and - // potentially causing the stream to appear frozen. + // Validate tool use before execution if (!block.partial) { const modelInfo = cline.api.getModel() - // Resolve aliases in includedTools before validation - // e.g., "edit_file" should resolve to "apply_diff" const rawIncludedTools = modelInfo?.info?.includedTools const { resolveToolAlias } = await import("../prompts/tools/filter-tools-for-mode") const includedTools = rawIncludedTools?.map((tool) => resolveToolAlias(tool)) @@ -606,13 +525,7 @@ export async function presentAssistantMessage(cline: Task) { ) } catch (error) { cline.consecutiveMistakeCount++ - // For validation errors (unknown tool, tool not allowed for mode), we need to: - // 1. Send a tool_result with the error (required for native tool calling) - // 2. NOT set didAlreadyUseTool = true (the tool was never executed, just failed validation) - // This prevents the stream from being interrupted with "Response interrupted by tool use result" - // which would cause the extension to appear to hang const errorContent = formatResponse.toolError(error.message) - // Push tool_result directly without setting didAlreadyUseTool cline.pushToolResultToUserContent({ type: "tool_result", tool_use_id: sanitizeToolUseId(toolCallId), @@ -624,22 +537,17 @@ export async function presentAssistantMessage(cline: Task) { } } - // Check for identical consecutive tool calls. + // Check for identical consecutive tool calls if (!block.partial) { - // Use the detector to check for repetition, passing the ToolUse - // block directly. const repetitionCheck = cline.toolRepetitionDetector.check(block) - // If execution is not allowed, notify user and break. if (!repetitionCheck.allowExecution && repetitionCheck.askUser) { - // Handle repetition similar to mistake_limit_reached pattern. const { response, text, images } = await cline.ask( repetitionCheck.askUser.messageKey as ClineAsk, repetitionCheck.askUser.messageDetail.replace("{toolName}", block.name), ) if (response === "messageResponse") { - // Add user feedback to userContent. cline.userMessageContent.push( { type: "text" as const, @@ -647,12 +555,9 @@ export async function presentAssistantMessage(cline: Task) { }, ...formatResponse.imageBlocks(images), ) - - // Add user feedback to chat. await cline.say("user_feedback", text, images) } - // Track tool repetition in telemetry via PostHog exception tracking and event. TelemetryService.instance.captureConsecutiveMistakeError(cline.taskId) TelemetryService.instance.captureException( new ConsecutiveMistakeError( @@ -666,7 +571,6 @@ export async function presentAssistantMessage(cline: Task) { ), ) - // Return tool result message about the repetition pushToolResult( formatResponse.toolError( `Tool call repetition limit reached for ${block.name}. Please try a different approach.`, @@ -676,14 +580,29 @@ export async function presentAssistantMessage(cline: Task) { } } - // Initialize hook engine for this task - const hookEngine = new HookEngine(cline.cwd) + // Initialize (and persist) hook engine for this task session. + // This preserves Phase 4 state like optimistic-locking file hash cache across tool calls. + const hookEngineKey = "__hookEngine" as const + let hookEngine = (cline as any)[hookEngineKey] as HookEngine | undefined + if (!hookEngine) { + hookEngine = new HookEngine(cline.cwd) + ;(cline as any)[hookEngineKey] = hookEngine + } await hookEngine.initialize() // Pre-Hook: Intercept tool execution + console.log(`[PRESENT ASSISTANT] Calling preHook for tool: ${block.name}`) const preHookResult = await hookEngine.preHook(block.name as ToolName, block, cline) + console.log(`[PRESENT ASSISTANT] preHook result - shouldProceed: ${preHookResult.shouldProceed}`) if (!preHookResult.shouldProceed) { - pushToolResult(formatResponse.toolError(preHookResult.errorMessage || "Tool execution blocked by hook")) + console.log(`[PRESENT ASSISTANT] Blocking tool execution - hook returned shouldProceed: false`) + if (preHookResult.structuredError) { + pushToolResult(JSON.stringify(preHookResult.structuredError, null, 2)) + } else { + pushToolResult( + formatResponse.toolError(preHookResult.errorMessage || "Tool execution blocked by hook"), + ) + } break } @@ -695,26 +614,40 @@ export async function presentAssistantMessage(cline: Task) { pushToolResult, }) break - case "write_to_file": + case "create_intent": + await createIntentTool.handle(cline, block as ToolUse<"create_intent">, { + askApproval, + handleError, + pushToolResult, + }) + break + case "record_lesson": + await recordLessonTool.handle(cline, block as ToolUse<"record_lesson">, { + askApproval, + handleError, + pushToolResult, + }) + break + case "write_to_file": { await checkpointSaveAndMark(cline) - let writeSuccess = false - let writeResult: string | undefined + let wtfSuccess = false + let wtfResult: string | undefined try { await writeToFileTool.handle(cline, block as ToolUse<"write_to_file">, { askApproval, handleError, pushToolResult: (result) => { - writeResult = typeof result === "string" ? result : JSON.stringify(result) + wtfResult = typeof result === "string" ? result : JSON.stringify(result) pushToolResult(result) }, }) - writeSuccess = true + wtfSuccess = true } catch (error) { - writeSuccess = false + wtfSuccess = false } - // Post-Hook: Log trace entry - await hookEngine.postHook(block.name as ToolName, block, cline, writeSuccess, writeResult) + await hookEngine.postHook(block.name as ToolName, block, cline, wtfSuccess, wtfResult) break + } case "update_todo_list": await updateTodoListTool.handle(cline, block as ToolUse<"update_todo_list">, { askApproval, @@ -722,67 +655,131 @@ export async function presentAssistantMessage(cline: Task) { pushToolResult, }) break - case "apply_diff": + case "apply_diff": { await checkpointSaveAndMark(cline) - await applyDiffToolClass.handle(cline, block as ToolUse<"apply_diff">, { - askApproval, - handleError, - pushToolResult, - }) + let adSuccess = false + let adResult: string | undefined + try { + await applyDiffToolClass.handle(cline, block as ToolUse<"apply_diff">, { + askApproval, + handleError, + pushToolResult: (result) => { + adResult = typeof result === "string" ? result : JSON.stringify(result) + pushToolResult(result) + }, + }) + adSuccess = true + } catch (error) { + adSuccess = false + } + await hookEngine.postHook(block.name as ToolName, block, cline, adSuccess, adResult) break + } case "edit": - case "search_and_replace": + case "search_and_replace": { await checkpointSaveAndMark(cline) - await editTool.handle(cline, block as ToolUse<"edit">, { - askApproval, - handleError, - pushToolResult, - }) + let etSuccess = false + let etResult: string | undefined + try { + await editTool.handle(cline, block as ToolUse<"edit">, { + askApproval, + handleError, + pushToolResult: (result) => { + etResult = typeof result === "string" ? result : JSON.stringify(result) + pushToolResult(result) + }, + }) + etSuccess = true + } catch (error) { + etSuccess = false + } + await hookEngine.postHook(block.name as ToolName, block, cline, etSuccess, etResult) break - case "search_replace": + } + case "search_replace": { await checkpointSaveAndMark(cline) - await searchReplaceTool.handle(cline, block as ToolUse<"search_replace">, { - askApproval, - handleError, - pushToolResult, - }) + let srSuccess = false + let srResult: string | undefined + try { + await searchReplaceTool.handle(cline, block as ToolUse<"search_replace">, { + askApproval, + handleError, + pushToolResult: (result) => { + srResult = typeof result === "string" ? result : JSON.stringify(result) + pushToolResult(result) + }, + }) + srSuccess = true + } catch (error) { + srSuccess = false + } + await hookEngine.postHook(block.name as ToolName, block, cline, srSuccess, srResult) break - case "edit_file": + } + case "edit_file": { await checkpointSaveAndMark(cline) - let editSuccess = false - let editResult: string | undefined + let efSuccess = false + let efResult: string | undefined try { await editFileTool.handle(cline, block as ToolUse<"edit_file">, { askApproval, handleError, pushToolResult: (result) => { - editResult = typeof result === "string" ? result : JSON.stringify(result) + efResult = typeof result === "string" ? result : JSON.stringify(result) pushToolResult(result) }, }) - editSuccess = true + efSuccess = true } catch (error) { - editSuccess = false + efSuccess = false } - // Post-Hook: Log trace entry - await hookEngine.postHook(block.name as ToolName, block, cline, editSuccess, editResult) + await hookEngine.postHook(block.name as ToolName, block, cline, efSuccess, efResult) break - case "apply_patch": + } + case "apply_patch": { await checkpointSaveAndMark(cline) - await applyPatchTool.handle(cline, block as ToolUse<"apply_patch">, { - askApproval, - handleError, - pushToolResult, - }) + let apSuccess = false + let apResult: string | undefined + try { + await applyPatchTool.handle(cline, block as ToolUse<"apply_patch">, { + askApproval, + handleError, + pushToolResult: (result) => { + apResult = typeof result === "string" ? result : JSON.stringify(result) + pushToolResult(result) + }, + }) + apSuccess = true + } catch (error) { + apSuccess = false + } + await hookEngine.postHook(block.name as ToolName, block, cline, apSuccess, apResult) break - case "read_file": - // Type assertion is safe here because we're in the "read_file" case + } + case "read_file": { + // Phase 4: Track file hash when file is read (for optimistic locking) + const nativeArgs = (block as any).nativeArgs + const params = block.params as any + const filePath = (nativeArgs?.path || params?.path) as string | undefined + await readFileTool.handle(cline, block as ToolUse<"read_file">, { askApproval, handleError, pushToolResult, }) + + // Track file hash after read completes (for optimistic locking) + if (filePath) { + try { + const absolutePath = path.resolve(cline.cwd, filePath) + const fileContent = await fs.readFile(absolutePath, "utf-8") + hookEngine.trackFileRead(filePath, fileContent) + } catch { + // File might not exist or be unreadable - ignore + } + } break + } case "list_files": await listFilesTool.handle(cline, block as ToolUse<"list_files">, { askApproval, @@ -804,13 +801,25 @@ export async function presentAssistantMessage(cline: Task) { pushToolResult, }) break - case "execute_command": - await executeCommandTool.handle(cline, block as ToolUse<"execute_command">, { - askApproval, - handleError, - pushToolResult, - }) + case "execute_command": { + let ecSuccess = false + let ecResult: string | undefined + try { + await executeCommandTool.handle(cline, block as ToolUse<"execute_command">, { + askApproval, + handleError, + pushToolResult: (result) => { + ecResult = typeof result === "string" ? result : JSON.stringify(result) + pushToolResult(result) + }, + }) + ecSuccess = true + } catch (error) { + ecSuccess = false + } + await hookEngine.postHook(block.name as ToolName, block, cline, ecSuccess, ecResult) break + } case "read_command_output": await readCommandOutputTool.handle(cline, block as ToolUse<"read_command_output">, { askApproval, @@ -893,12 +902,6 @@ export async function presentAssistantMessage(cline: Task) { }) break default: { - // Handle unknown/invalid tool names OR custom tools - // This is critical for native tool calling where every tool_use MUST have a tool_result - - // CRITICAL: Don't process partial blocks for unknown tools - just let them stream in. - // If we try to show errors for partial blocks, we'd show the error on every streaming chunk, - // creating a loop that appears to freeze the extension. Only handle complete blocks. if (block.partial) { break } @@ -935,7 +938,6 @@ export async function presentAssistantMessage(cline: Task) { cline.consecutiveMistakeCount = 0 } catch (executionError: any) { cline.consecutiveMistakeCount++ - // Record custom tool error with static name cline.recordToolError("custom_tool", executionError.message) await handleError(`executing custom tool "${block.name}"`, executionError) } @@ -943,13 +945,10 @@ export async function presentAssistantMessage(cline: Task) { break } - // Not a custom tool - handle as unknown tool error const errorMessage = `Unknown tool "${block.name}". This tool does not exist. Please use one of the available tools.` cline.consecutiveMistakeCount++ cline.recordToolError(block.name as ToolName, errorMessage) await cline.say("error", t("tools:unknownToolError", { toolName: block.name })) - // Push tool_result directly WITHOUT setting didAlreadyUseTool - // This prevents the stream from being interrupted with "Response interrupted by tool use result" cline.pushToolResultToUserContent({ type: "tool_result", tool_use_id: sanitizeToolUseId(toolCallId), @@ -964,56 +963,25 @@ export async function presentAssistantMessage(cline: Task) { } } - // Seeing out of bounds is fine, it means that the next too call is being - // built up and ready to add to assistantMessageContent to present. - // When you see the UI inactive during this, it means that a tool is - // breaking without presenting any UI. For example the write_to_file tool - // was breaking when relpath was undefined, and for invalid relpath it never - // presented UI. - // This needs to be placed here, if not then calling - // cline.presentAssistantMessage below would fail (sometimes) since it's - // locked. cline.presentAssistantMessageLocked = false - // NOTE: When tool is rejected, iterator stream is interrupted and it waits - // for `userMessageContentReady` to be true. Future calls to present will - // skip execution since `didRejectTool` and iterate until `contentIndex` is - // set to message length and it sets userMessageContentReady to true itself - // (instead of preemptively doing it in iterator). if (!block.partial || cline.didRejectTool || cline.didAlreadyUseTool) { - // Block is finished streaming and executing. if (cline.currentStreamingContentIndex === cline.assistantMessageContent.length - 1) { - // It's okay that we increment if !didCompleteReadingStream, it'll - // just return because out of bounds and as streaming continues it - // will call `presentAssitantMessage` if a new block is ready. If - // streaming is finished then we set `userMessageContentReady` to - // true when out of bounds. This gracefully allows the stream to - // continue on and all potential content blocks be presented. - // Last block is complete and it is finished executing - cline.userMessageContentReady = true // Will allow `pWaitFor` to continue. + cline.userMessageContentReady = true } - // Call next block if it exists (if not then read stream will call it - // when it's ready). - // Need to increment regardless, so when read stream calls this function - // again it will be streaming the next block. cline.currentStreamingContentIndex++ if (cline.currentStreamingContentIndex < cline.assistantMessageContent.length) { - // There are already more content blocks to stream, so we'll call - // this function ourselves. presentAssistantMessage(cline) return } else { - // CRITICAL FIX: If we're out of bounds and the stream is complete, set userMessageContentReady - // This handles the case where assistantMessageContent is empty or becomes empty after processing if (cline.didCompleteReadingStream) { cline.userMessageContentReady = true } } } - // Block is partial, but the read stream may have finished. if (cline.presentAssistantMessageHasPendingUpdates) { presentAssistantMessage(cline) } @@ -1021,8 +989,6 @@ export async function presentAssistantMessage(cline: Task) { /** * save checkpoint and mark done in the current streaming task. - * @param task The Task instance to checkpoint save and mark. - * @returns */ async function checkpointSaveAndMark(task: Task) { if (task.currentStreamingDidCheckpoint) { From 4e866f64c64002f1c5853f3e70bc9f7c035c1e92 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:55:22 +0300 Subject: [PATCH 32/41] chore: commit src/core/prompts/tools/native-tools/create_intent.ts --- .../tools/native-tools/create_intent.ts | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 src/core/prompts/tools/native-tools/create_intent.ts diff --git a/src/core/prompts/tools/native-tools/create_intent.ts b/src/core/prompts/tools/native-tools/create_intent.ts new file mode 100644 index 00000000000..bb8b7c657b6 --- /dev/null +++ b/src/core/prompts/tools/native-tools/create_intent.ts @@ -0,0 +1,61 @@ +import type OpenAI from "openai" + +/** + * Tool for creating a new intent based on a prompt. + * Checks for architecture.md and uses it to create the intent. + */ +const createIntent: OpenAI.Chat.ChatCompletionFunctionTool = { + type: "function", + function: { + name: "create_intent", + description: + "Create a new intent in active_intents.yaml based on a prompt. This tool checks for architecture.md first. If architecture.md doesn't exist, it will ask the user if they want to create it. The intent will be created with inferred scope, constraints, and acceptance criteria based on the prompt and architecture.md.", + parameters: { + type: "object", + properties: { + prompt: { + type: "string", + description: + "The prompt describing what the intent should cover. This is used to infer scope, constraints, and acceptance criteria.", + }, + intent_id: { + type: "string", + description: + "Optional: The ID for the new intent (e.g., 'INT-008'). If not provided, the next available ID will be generated automatically.", + }, + intent_name: { + type: "string", + description: + "Optional: The name for the new intent. If not provided, it will be generated from the prompt.", + }, + owned_scope: { + type: "array", + items: { + type: "string", + }, + description: + "Optional: Array of file path patterns (glob patterns) that this intent owns. If not provided, it will be inferred from the prompt.", + }, + constraints: { + type: "array", + items: { + type: "string", + }, + description: + "Optional: Array of constraints for this intent. If not provided, it will be inferred from the prompt.", + }, + acceptance_criteria: { + type: "array", + items: { + type: "string", + }, + description: + "Optional: Array of acceptance criteria for this intent. If not provided, it will be inferred from the prompt.", + }, + }, + required: ["prompt"], + }, + }, +} + +export default createIntent From f7f2ee2070012aaf8197591dcfc7e31bd2a242be Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:55:45 +0300 Subject: [PATCH 33/41] chore: commit src/core/prompts/tools/native-tools/index.ts --- src/core/prompts/tools/native-tools/index.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/core/prompts/tools/native-tools/index.ts b/src/core/prompts/tools/native-tools/index.ts index 82915152b27..dda54abaaa8 100644 --- a/src/core/prompts/tools/native-tools/index.ts +++ b/src/core/prompts/tools/native-tools/index.ts @@ -21,6 +21,8 @@ import switchMode from "./switch_mode" import updateTodoList from "./update_todo_list" import writeToFile from "./write_to_file" import selectActiveIntent from "./select_active_intent" +import createIntent from "./create_intent" +import recordLesson from "./record_lesson" export { getMcpServerTools } from "./mcp_server" export { convertOpenAIToolToAnthropic, convertOpenAIToolsToAnthropic } from "./converters" @@ -49,6 +51,8 @@ export function getNativeTools(options: NativeToolsOptions = {}): OpenAI.Chat.Ch return [ selectActiveIntent, // Must be first - required before code changes + createIntent, // Create new intents based on prompts + recordLesson, // Record lessons learned to AGENT.md (Phase 4) accessMcpResource, apply_diff, applyPatch, From 37e44f8186e5ed6106f16be1c44a530a3e8dd793 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:56:17 +0300 Subject: [PATCH 34/41] chore: commit src/core/prompts/tools/native-tools/record_lesson.ts --- .../tools/native-tools/record_lesson.ts | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 src/core/prompts/tools/native-tools/record_lesson.ts diff --git a/src/core/prompts/tools/native-tools/record_lesson.ts b/src/core/prompts/tools/native-tools/record_lesson.ts new file mode 100644 index 00000000000..0c16094844e --- /dev/null +++ b/src/core/prompts/tools/native-tools/record_lesson.ts @@ -0,0 +1,46 @@ +import type OpenAI from "openai" + +/** + * Tool for recording lessons learned to AGENT.md (Phase 4 requirement). + * This tool allows the agent to append lessons learned when verification steps fail + * or when important insights are discovered during development. + */ +const recordLesson: OpenAI.Chat.ChatCompletionFunctionTool = { + type: "function", + function: { + name: "record_lesson", + description: + "Record a lesson learned to .orchestration/AGENT.md. Use this tool when verification steps (linter/test) fail, when architectural decisions are made, or when important insights are discovered. Lessons are appended with timestamps and context information.", + parameters: { + type: "object", + properties: { + lesson: { + type: "string", + description: + "The lesson learned or insight to record. Should be clear and actionable for future reference.", + }, + context: { + type: "object", + properties: { + tool: { + type: "string", + description: "Optional: The tool that was being used when the lesson was learned.", + }, + error: { + type: "string", + description: "Optional: The error message or issue that led to this lesson.", + }, + file: { + type: "string", + description: "Optional: The file path related to this lesson.", + }, + }, + description: "Optional context information about when/where this lesson was learned.", + }, + }, + required: ["lesson"], + }, + }, +} + +export default recordLesson From 7eaba1b298161bdc95666cb07867cc7500dc03c8 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:56:54 +0300 Subject: [PATCH 35/41] chore: commit src/hooks/CreateIntentTool.ts --- src/hooks/CreateIntentTool.ts | 270 ++++++++++++++++++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 src/hooks/CreateIntentTool.ts diff --git a/src/hooks/CreateIntentTool.ts b/src/hooks/CreateIntentTool.ts new file mode 100644 index 00000000000..e4787d33c93 --- /dev/null +++ b/src/hooks/CreateIntentTool.ts @@ -0,0 +1,270 @@ +import * as fs from "fs/promises" +import * as path from "path" +import * as vscode from "vscode" +import { Task } from "../core/task/Task" +import { formatResponse } from "../core/prompts/responses" +import { BaseTool, ToolCallbacks } from "../core/tools/BaseTool" +import type { ToolUse } from "../shared/tools" +import { OrchestrationDataModel, type ActiveIntent } from "./OrchestrationDataModel" + +interface CreateIntentParams { + prompt: string + intent_id?: string + intent_name?: string + owned_scope?: string[] + constraints?: string[] + acceptance_criteria?: string[] +} + +/** + * Tool for creating a new intent based on a prompt. + * Checks for docs/Architecture.md and uses it to create the intent. + */ +export class CreateIntentTool extends BaseTool<"create_intent"> { + readonly name = "create_intent" as const + + async execute(params: CreateIntentParams, task: Task, callbacks: ToolCallbacks): Promise { + const { prompt, intent_id, intent_name, owned_scope, constraints, acceptance_criteria } = params + const { pushToolResult, handleError, askApproval } = callbacks + + try { + if (!prompt) { + task.consecutiveMistakeCount++ + task.recordToolError("create_intent") + pushToolResult(await task.sayAndCreateMissingParamError("create_intent", "prompt")) + return + } + + // Initialize orchestration data model + const dataModel = new OrchestrationDataModel(task.cwd) + await dataModel.initialize() + + // Check if docs/Architecture.md exists + const archPath = path.join(task.cwd, "docs", "Architecture.md") + let archExists = false + try { + await fs.access(archPath) + archExists = true + } catch { + archExists = false + } + + // If docs/Architecture.md doesn't exist, show clear error + if (!archExists) { + const errorJson = JSON.stringify( + { + error_type: "architecture_missing", + message: + "docs/Architecture.md is required but not found. Please create docs/Architecture.md with your project architecture and come again.", + details: { + required_file: "docs/Architecture.md", + reason: "file_not_found", + required_action: "create_architecture_file", + instructions: [ + "Create docs/Architecture.md file in your project root", + "Document your project structure, directory layout, and intent areas", + "Then try create_intent again", + ], + }, + recoverable: true, + suggested_action: "Create docs/Architecture.md file with project architecture, then try again", + }, + null, + 2, + ) + pushToolResult(errorJson) + return + } + + // Read docs/Architecture.md + let architectureContent = "" + try { + architectureContent = await fs.readFile(archPath, "utf-8") + } catch (error) { + await handleError("reading architecture.md", error as Error) + return + } + + // Read existing intents to generate next ID + const intentsData = await dataModel.readActiveIntents() + const existingIds = intentsData.active_intents.map((i) => i.id) + + // Generate intent ID if not provided + let finalIntentId = intent_id + if (!finalIntentId) { + // Find the highest INT-XXX number and increment + const maxNum = existingIds + .map((id) => { + const match = id.match(/^INT-(\d+)$/) + return match ? parseInt(match[1], 10) : 0 + }) + .reduce((max, num) => Math.max(max, num), 0) + finalIntentId = `INT-${String(maxNum + 1).padStart(3, "0")}` + } + + // Check if intent ID already exists + if (existingIds.includes(finalIntentId)) { + task.consecutiveMistakeCount++ + task.recordToolError("create_intent") + const errorJson = JSON.stringify( + { + error_type: "intent_id_exists", + message: `Intent ID "${finalIntentId}" already exists. Please use a different ID.`, + details: { + requested_intent_id: finalIntentId, + available_intent_ids: existingIds, + }, + recoverable: true, + suggested_action: `Use a different intent ID. Available IDs: ${existingIds.join(", ")}`, + }, + null, + 2, + ) + pushToolResult(errorJson) + return + } + + // Generate intent name if not provided + const finalIntentName = + intent_name || `${finalIntentId} — ${prompt.substring(0, 50)}${prompt.length > 50 ? "..." : ""}` + + // Build the intent based on prompt and docs/Architecture.md + // For now, we'll create a basic intent structure + // The agent can refine it based on docs/Architecture.md content + const newIntent: ActiveIntent = { + id: finalIntentId, + name: finalIntentName, + status: "IN_PROGRESS", + owned_scope: owned_scope || this.inferScopeFromPrompt(prompt, architectureContent), + constraints: constraints || this.inferConstraintsFromPrompt(prompt, architectureContent), + acceptance_criteria: + acceptance_criteria || this.inferAcceptanceCriteriaFromPrompt(prompt, architectureContent), + created_at: new Date().toISOString(), + updated_at: new Date().toISOString(), + } + + // Ask user for approval before creating the intent + const approvalMessage = JSON.stringify({ + tool: "createIntent", + intent_id: newIntent.id, + intent_name: newIntent.name, + owned_scope: newIntent.owned_scope, + constraints: newIntent.constraints, + acceptance_criteria: newIntent.acceptance_criteria, + }) + + const didApprove = await askApproval("tool", approvalMessage) + if (!didApprove) { + pushToolResult("User declined to create the intent.") + return + } + + // Write the intent to active_intents.yaml + await dataModel.updateIntent(newIntent) + + // Reset mistake count on success + task.consecutiveMistakeCount = 0 + + // Return success message + const result = + `Intent created successfully:\n\n` + + `ID: ${newIntent.id}\n` + + `Name: ${newIntent.name}\n` + + `Status: ${newIntent.status}\n` + + `Owned Scope:\n${newIntent.owned_scope.map((s) => ` - ${s}`).join("\n")}\n` + + `\nYou can now call select_active_intent(${newIntent.id}) to activate this intent before making code changes.` + + pushToolResult(result) + } catch (error) { + await handleError("creating intent", error as Error) + } + } + + /** + * Infer scope patterns from prompt and docs/Architecture.md + */ + private inferScopeFromPrompt(prompt: string, architectureContent: string): string[] { + const scope: string[] = [] + + // Try to extract file paths or directories from the prompt + const pathMatches = prompt.match(/(?:src|lib|app|components|api|utils|hooks|core|shared)\/[^\s,]+/g) + if (pathMatches) { + // Convert specific files to directory patterns + pathMatches.forEach((match) => { + if (match.includes(".")) { + // It's a file, convert to directory pattern + const dir = match.substring(0, match.lastIndexOf("/")) + scope.push(`${dir}/**`) + } else { + // It's already a directory + scope.push(`${match}/**`) + } + }) + } + + // If no scope found, use a default based on common patterns + if (scope.length === 0) { + // Try to infer from prompt keywords + if (prompt.toLowerCase().includes("api") || prompt.toLowerCase().includes("endpoint")) { + scope.push("src/api/**") + } else if (prompt.toLowerCase().includes("component") || prompt.toLowerCase().includes("ui")) { + scope.push("src/components/**") + } else if (prompt.toLowerCase().includes("hook") || prompt.toLowerCase().includes("hook system")) { + scope.push("src/hooks/**") + } else { + // Default to src/** if nothing specific + scope.push("src/**") + } + } + + // Remove duplicates + return [...new Set(scope)] + } + + /** + * Infer constraints from prompt and docs/Architecture.md + */ + private inferConstraintsFromPrompt(prompt: string, architectureContent: string): string[] { + const constraints: string[] = [] + + // Add common constraints based on prompt keywords + if (prompt.toLowerCase().includes("test") || prompt.toLowerCase().includes("testing")) { + constraints.push("Must include unit tests") + } + if (prompt.toLowerCase().includes("api") || prompt.toLowerCase().includes("endpoint")) { + constraints.push("Must follow REST API conventions") + } + if (prompt.toLowerCase().includes("hook") || prompt.toLowerCase().includes("hook system")) { + constraints.push("Must integrate with existing hook system") + } + + // If no constraints inferred, add a default + if (constraints.length === 0) { + constraints.push("Must follow project architecture and coding standards") + } + + return constraints + } + + /** + * Infer acceptance criteria from prompt and docs/Architecture.md + */ + private inferAcceptanceCriteriaFromPrompt(prompt: string, architectureContent: string): string[] { + const criteria: string[] = [] + + // Add basic acceptance criteria + criteria.push( + `Implementation matches the requirements: ${prompt.substring(0, 100)}${prompt.length > 100 ? "..." : ""}`, + ) + criteria.push("Code follows project architecture and coding standards") + criteria.push("All tests pass (if applicable)") + + return criteria + } + + override async handlePartial(task: Task, block: ToolUse<"create_intent">): Promise { + // No partial handling needed for intent creation + } +} + +export const createIntentTool = new CreateIntentTool() From 5ce9e584ae9f9633909ce6ea4fbf6dfcb8734b8a Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:57:30 +0300 Subject: [PATCH 36/41] chore: commit src/hooks/HookEngine.ts --- src/hooks/HookEngine.ts | 806 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 777 insertions(+), 29 deletions(-) diff --git a/src/hooks/HookEngine.ts b/src/hooks/HookEngine.ts index e3c2d6bf1bc..38dbe9fe44a 100644 --- a/src/hooks/HookEngine.ts +++ b/src/hooks/HookEngine.ts @@ -7,12 +7,27 @@ import * as path from "path" import * as fs from "fs/promises" import { execSync } from "child_process" +/** + * Standardized error format for autonomous recovery (Phase 2 requirement) + * LLM can parse this JSON and self-correct without crashing + */ +export interface HookError { + error_type: string + message: string + details?: { + [key: string]: any + } + recoverable: boolean + suggested_action?: string +} + /** * Hook execution result */ export interface HookResult { shouldProceed: boolean errorMessage?: string + structuredError?: HookError // Phase 2: Structured error for autonomous recovery injectedContext?: string } @@ -22,6 +37,10 @@ export interface HookResult { */ export class HookEngine { private dataModel: OrchestrationDataModel + private initialized = false + // Phase 4: Track file hashes for optimistic locking + private fileHashCache: Map = new Map() + private readonly HASH_CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes constructor(workspaceRoot: string) { this.dataModel = new OrchestrationDataModel(workspaceRoot) @@ -72,16 +91,233 @@ export class HookEngine { * Initialize orchestration directory */ async initialize(): Promise { + if (this.initialized) return await this.dataModel.initialize() + this.initialized = true + } + + /** + * Extract the primary target file path for a tool call (best-effort). + * This enables consistent scope checks across all file-mutating tools. + */ + private extractTargetFilePath(toolName: ToolName, toolUse: ToolUse): string | undefined { + const nativeArgs = (toolUse as any).nativeArgs + const params = toolUse.params as any + + // Direct path/file_path parameters + const direct = (nativeArgs?.path || nativeArgs?.file_path || params?.path || params?.file_path) as + | string + | undefined + if (direct) return direct + + // apply_patch: infer from patch content + const patchContent = nativeArgs?.patch || params?.patch + if (patchContent && typeof patchContent === "string") { + // Unified diff: --- a/foo or +++ b/foo + const unifiedDiffMatch = patchContent.match(/^(?:---|\+\+\+)\s+(?:a\/|b\/)?(.+?)(?:\s|$)/m) + if (unifiedDiffMatch?.[1]) return unifiedDiffMatch[1].trim() + + // Custom format: "Update File: foo" + const fileMatches = patchContent.match(/(?:Update|Create|Delete)\s+File:\s*(.+)/gm) + if (fileMatches?.length) { + const match = fileMatches[0].match(/(?:Update|Create|Delete)\s+File:\s*(.+)/) + if (match?.[1]) return match[1].trim() + } + } + + return undefined + } + + /** + * Create standardized error for autonomous recovery (Phase 2 requirement) + */ + private createStructuredError( + errorType: string, + message: string, + details?: Record, + recoverable: boolean = true, + suggestedAction?: string, + ): HookError { + return { + error_type: errorType, + message, + details, + recoverable, + suggested_action: suggestedAction, + } + } + + /** + * Format error message with structured JSON for LLM parsing (Phase 2 requirement) + */ + private formatErrorForLLM(error: HookError): string { + const jsonError = JSON.stringify(error, null, 2) + return `${error.message}\n\n\n${jsonError}\n` + } + + /** + * Check if workspace has existing code files to analyze + * Used to determine if agent should reverse engineer from code or create from prompt + */ + private async hasExistingCode(workspaceRoot: string): Promise { + const commonCodeDirs = ["src", "lib", "app", "components", "pages", "scripts", "server", "client"] + const commonCodeExtensions = [".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go", ".rs", ".cpp", ".c"] + + try { + // Check common code directories + for (const dir of commonCodeDirs) { + const dirPath = path.join(workspaceRoot, dir) + try { + const entries = await fs.readdir(dirPath, { withFileTypes: true }) + if (entries.length > 0) { + return true + } + } catch { + // Directory doesn't exist, continue + } + } + + // Check root directory for code files + const rootEntries = await fs.readdir(workspaceRoot, { withFileTypes: true }) + for (const entry of rootEntries) { + if (entry.isFile()) { + const ext = path.extname(entry.name).toLowerCase() + if (commonCodeExtensions.includes(ext)) { + return true + } + } + } + + return false + } catch { + return false + } + } + + /** + * Phase 4: Track file hash when file is read (for optimistic locking) + */ + trackFileRead(filePath: string, content: string): void { + const hash = this.dataModel.computeContentHash(content) + this.fileHashCache.set(filePath, { + hash, + timestamp: Date.now(), + }) + console.log(`[HOOK DEBUG] Tracked file read: ${filePath}, hash: ${hash.substring(0, 8)}...`) + } + + /** + * Phase 4: Validate file hasn't changed since last read (optimistic locking) + */ + private async validateFileNotStale( + filePath: string, + workspaceRoot: string, + ): Promise<{ valid: boolean; message?: string }> { + const cached = this.fileHashCache.get(filePath) + if (!cached) { + // No cached hash - allow write (first write or cache expired) + return { valid: true } + } + + // Check cache TTL + if (Date.now() - cached.timestamp > this.HASH_CACHE_TTL_MS) { + // Cache expired - allow write + this.fileHashCache.delete(filePath) + return { valid: true } + } + + // Read current file hash + try { + const absolutePath = path.resolve(workspaceRoot, filePath) + const currentContent = await fs.readFile(absolutePath, "utf-8") + const currentHash = this.dataModel.computeContentHash(currentContent) + + if (currentHash !== cached.hash) { + // File has changed - stale! + const error = this.createStructuredError( + "stale_file", + `File ${filePath} has been modified since it was last read. Please re-read the file before making changes.`, + { + file_path: filePath, + expected_hash: cached.hash.substring(0, 16), + actual_hash: currentHash.substring(0, 16), + reason: "file_modified_after_read", + }, + true, + "Re-read the file using read_file tool, then retry the write operation", + ) + + return { + valid: false, + message: this.formatErrorForLLM(error), + } + } + + // File is still the same - valid + return { valid: true } + } catch (error) { + // File might not exist (new file) - allow write + if ((error as any).code === "ENOENT") { + return { valid: true } + } + // Other error - fail open (allow write) + console.warn(`[HOOK DEBUG] Error validating file hash for ${filePath}:`, error) + return { valid: true } + } } /** * Pre-Hook: Intercept tool execution before it happens * Enforces intent context injection and scope validation + * + * Per document.md Phase 2: The Gatekeeper - verifies agent has declared a valid intent_id. + * If not, blocks execution and returns error message. + * + * Enhanced: Checks for architecture.md existence to guide agent in establishing intents + * before code changes (Plan-First strategy per document.md). + * + * Phase 4: Also validates optimistic locking (file hasn't changed since read) */ async preHook(toolName: ToolName, toolUse: ToolUse, task: Task): Promise { - // Check if this is select_active_intent - allow it through + // DEBUG: Log all hook calls + console.log( + `[HOOK DEBUG] preHook called - Tool: ${toolName}, ActiveIntentId: ${(task as any).activeIntentId || "undefined"}`, + ) + + // Check if this is select_active_intent - verify it's not in .intentignore if (toolName === "select_active_intent") { + const params = toolUse.params as any + const intentId = params?.intent_id as string | undefined + + if (intentId) { + // Phase 2: Check if intent is in .intentignore + const isIgnored = await this.dataModel.isIntentIgnored(intentId) + if (isIgnored) { + const error = this.createStructuredError( + "intent_protected", + `Intent "${intentId}" is protected and cannot be modified. This intent is listed in .orchestration/.intentignore.`, + { + intent_id: intentId, + reason: "intent_in_ignore_list", + }, + false, // Not recoverable - user must manually remove from ignore list + "Select a different intent or ask user to remove this intent from .intentignore", + ) + + return { + shouldProceed: false, + errorMessage: this.formatErrorForLLM(error), + structuredError: error, + } + } + } + + return { shouldProceed: true } + } + + // Special case: create_intent is always allowed (it's a meta-tool for creating intents) + if (toolName === "create_intent") { + console.log(`[HOOK DEBUG] create_intent is always allowed (meta-tool for intent management)`) return { shouldProceed: true } } @@ -89,7 +325,7 @@ export class HookEngine { const activeIntentId = (task as any).activeIntentId as string | undefined let activeIntent = (task as any).activeIntent as ActiveIntent | undefined - // Destructive tools require intent selection + // Destructive tools require intent selection (document.md Phase 2 requirement) const destructiveTools: ToolName[] = [ "write_to_file", "edit_file", @@ -102,11 +338,100 @@ export class HookEngine { ] if (destructiveTools.includes(toolName)) { + console.log( + `[HOOK DEBUG] Destructive tool detected: ${toolName}, activeIntentId: ${activeIntentId || "undefined"}`, + ) if (!activeIntentId) { + // Check if docs/Architecture.md exists (Plan-First strategy per document.md) + const archPath = path.join(task.cwd, "docs", "Architecture.md") + let archExists = false + try { + await fs.access(archPath) + archExists = true + console.log(`[HOOK DEBUG] docs/Architecture.md exists at: ${archPath}`) + } catch { + archExists = false + console.log(`[HOOK DEBUG] docs/Architecture.md NOT found at: ${archPath}`) + } + + if (!archExists) { + console.log(`[HOOK DEBUG] docs/Architecture.md not found - showing error`) + const error = this.createStructuredError( + "architecture_missing", + `docs/Architecture.md is required but not found. Please create docs/Architecture.md with your project architecture and come again.`, + { + required_file: "docs/Architecture.md", + reason: "file_not_found", + required_action: "create_architecture_file", + instructions: [ + "Create docs/Architecture.md file in your project root", + "Document your project structure, directory layout, and intent areas", + "Then try your operation again", + ], + }, + true, + "Create docs/Architecture.md file with project architecture, then try again", + ) + + return { + shouldProceed: false, + errorMessage: this.formatErrorForLLM(error), + structuredError: error, + } + } + + // docs/Architecture.md exists but no intent selected + const intentsData = await this.dataModel.readActiveIntents() + if (intentsData.active_intents.length === 0) { + console.log( + `[HOOK DEBUG] active_intents.yaml is empty - guide agent to create intents from docs/Architecture.md`, + ) + const error = this.createStructuredError( + "intents_missing", + `No active intent selected. docs/Architecture.md exists but active_intents.yaml is empty.`, + { + architecture_exists: true, + architecture_file: "docs/Architecture.md", + intents_file_empty: true, + required_action: "create_intents_from_architecture", + instructions: [ + "Read docs/Architecture.md to understand the project structure", + "Use create_intent(prompt) to create intents based on docs/Architecture.md content", + "Create intents for each major area (API, services, types, etc.)", + "Then call select_active_intent(intent_id) before making code changes", + ], + }, + true, + "Read docs/Architecture.md, use create_intent() to create intents based on it, then call select_active_intent(intent_id)", + ) + + return { + shouldProceed: false, + errorMessage: this.formatErrorForLLM(error), + structuredError: error, + } + } + + // docs/Architecture.md exists and intents exist, but none selected + console.log( + `[HOOK DEBUG] docs/Architecture.md exists, intents exist, but no intent selected - blocking`, + ) + const error = this.createStructuredError( + "intent_not_selected", + "You must cite a valid active Intent ID. Call select_active_intent(intent_id) before making code changes.", + { + available_intents_file: ".orchestration/active_intents.yaml", + available_intents_count: intentsData.active_intents.length, + available_intent_ids: intentsData.active_intents.map((i) => i.id), + }, + true, + `Call select_active_intent(intent_id) with one of the available intent IDs from active_intents.yaml`, + ) + return { shouldProceed: false, - errorMessage: - "You must cite a valid active Intent ID. Call select_active_intent(intent_id) before making code changes.", + errorMessage: this.formatErrorForLLM(error), + structuredError: error, } } @@ -120,30 +445,179 @@ export class HookEngine { } if (!activeIntent) { + const intentsData = await this.dataModel.readActiveIntents() + const error = this.createStructuredError( + "intent_not_found", + `Intent "${activeIntentId}" not found in active_intents.yaml. Please select a valid intent ID.`, + { + requested_intent_id: activeIntentId, + available_intent_ids: intentsData.active_intents.map((i) => i.id), + available_intents_count: intentsData.active_intents.length, + }, + true, + `Use select_active_intent(intent_id) with one of the available intent IDs: ${intentsData.active_intents.map((i) => i.id).join(", ")}`, + ) + return { shouldProceed: false, - errorMessage: `Intent "${activeIntentId}" not found in active_intents.yaml. Please select a valid intent ID.`, + errorMessage: this.formatErrorForLLM(error), + structuredError: error, } } - // Validate scope for write operations - if (toolName === "write_to_file" || toolName === "edit_file") { - const filePath = (toolUse.params as any).path as string | undefined + // Validate scope for file-mutating tools + const fileMutatingTools: ToolName[] = [ + "write_to_file", + "edit_file", + "apply_diff", + "apply_patch", + "edit", + "search_replace", + "search_and_replace", + ] + + if (fileMutatingTools.includes(toolName)) { + const filePath = this.extractTargetFilePath(toolName, toolUse) + if (filePath) { + // Phase 4: Optimistic locking - check if file has changed since read + const staleCheck = await this.validateFileNotStale(filePath, task.cwd) + if (!staleCheck.valid) { + return { + shouldProceed: false, + errorMessage: staleCheck.message, + structuredError: { + error_type: "stale_file", + message: staleCheck.message || "File has been modified", + recoverable: true, + suggested_action: "Re-read the file and retry", + }, + } + } const scopeValid = await this.validateScope(activeIntentId, filePath, task.cwd) if (!scopeValid.valid) { + // Check if there's any intent that matches this file path + const allIntents = await this.dataModel.readActiveIntents() + let matchingIntent = null + + for (const intent of allIntents.active_intents) { + const checkScope = await this.validateScope(intent.id, filePath, task.cwd) + if (checkScope.valid) { + matchingIntent = intent + break + } + } + + // If no matching intent found, guide agent to create one + if (!matchingIntent) { + const archPath = path.join(task.cwd, "docs", "Architecture.md") + let archExists = false + try { + await fs.access(archPath) + archExists = true + } catch { + archExists = false + } + + if (!archExists) { + const error = this.createStructuredError( + "architecture_missing", + `docs/Architecture.md is required but not found. Please create docs/Architecture.md with your project architecture and come again.`, + { + required_file: "docs/Architecture.md", + file_path: filePath, + reason: "file_not_found", + required_action: "create_architecture_file", + instructions: [ + "Create docs/Architecture.md file in your project root", + "Document your project structure, directory layout, and intent areas", + "Then try your operation again", + ], + }, + true, + "Create docs/Architecture.md file with project architecture, then try again", + ) + + return { + shouldProceed: false, + errorMessage: this.formatErrorForLLM(error), + structuredError: error, + } + } + + // Guide agent to create intent based on file path and docs/Architecture.md + const inferredScope = this.inferScopeFromFilePath(filePath) + const error = this.createStructuredError( + "no_matching_intent", + `No active intent whose owned scope includes ${filePath}. Create a new intent based on docs/Architecture.md.`, + { + file_path: filePath, + architecture_file: "docs/Architecture.md", + inferred_scope: inferredScope, + action: "create_intent", + instructions: [ + `Read docs/Architecture.md to understand the project structure`, + `Call create_intent(prompt: "Intent for ${inferredScope}") to create a new intent`, + `The tool will infer scope, constraints, and acceptance criteria from docs/Architecture.md`, + `Then call select_active_intent(intent_id) with the newly created intent ID`, + ], + }, + true, + `Use create_intent() to create a new intent for ${inferredScope} based on docs/Architecture.md, then select it`, + ) + + return { + shouldProceed: false, + errorMessage: this.formatErrorForLLM(error), + structuredError: error, + } + } + + // There is a matching intent, but it's not the selected one + const error = this.createStructuredError( + "scope_violation", + `Scope Violation: ${activeIntentId} is not authorized to edit ${filePath}. Use intent ${matchingIntent.id} instead.`, + { + intent_id: activeIntentId, + intent_name: activeIntent.name, + file_path: filePath, + intent_scope: activeIntent.owned_scope, + matching_intent_id: matchingIntent.id, + matching_intent_name: matchingIntent.name, + violation_reason: scopeValid.message, + }, + true, + `Call select_active_intent(${matchingIntent.id}) to use the intent that covers ${filePath}`, + ) + return { shouldProceed: false, - errorMessage: `Scope Violation: ${activeIntentId} is not authorized to edit ${filePath}. ${scopeValid.message}`, + errorMessage: this.formatErrorForLLM(error), + structuredError: error, } } // UI-blocking authorization (HITL) const auth = await this.ensureIntentAuthorized(task, activeIntent, toolName, { filePath }) if (!auth.approved) { + const error = this.createStructuredError( + "user_rejected", + auth.message || "Operation rejected by user.", + { + intent_id: activeIntent.id, + intent_name: activeIntent.name, + tool_name: toolName, + file_path: filePath, + rejection_reason: "user_denied_authorization", + }, + false, + "User must approve the operation or select a different approach", + ) + return { shouldProceed: false, - errorMessage: auth.message || "Operation rejected by user.", + errorMessage: this.formatErrorForLLM(error), + structuredError: error, } } } @@ -151,18 +625,47 @@ export class HookEngine { const command = (toolUse.params as any).command as string | undefined const auth = await this.ensureIntentAuthorized(task, activeIntent, toolName, { command }) if (!auth.approved) { + const error = this.createStructuredError( + "user_rejected", + auth.message || "Operation rejected by user.", + { + intent_id: activeIntent.id, + intent_name: activeIntent.name, + tool_name: toolName, + command: command, + rejection_reason: "user_denied_authorization", + }, + false, + "User must approve the operation or select a different approach", + ) + return { shouldProceed: false, - errorMessage: auth.message || "Operation rejected by user.", + errorMessage: this.formatErrorForLLM(error), + structuredError: error, } } } else { // Other destructive tools: still require UI-blocking authorization. const auth = await this.ensureIntentAuthorized(task, activeIntent, toolName) if (!auth.approved) { + const error = this.createStructuredError( + "user_rejected", + auth.message || "Operation rejected by user.", + { + intent_id: activeIntent.id, + intent_name: activeIntent.name, + tool_name: toolName, + rejection_reason: "user_denied_authorization", + }, + false, + "User must approve the operation or select a different approach", + ) + return { shouldProceed: false, - errorMessage: auth.message || "Operation rejected by user.", + errorMessage: this.formatErrorForLLM(error), + structuredError: error, } } } @@ -187,10 +690,35 @@ export class HookEngine { "edit", "search_replace", "search_and_replace", + "execute_command", ] if (destructiveTools.includes(toolName) && activeIntentId && success) { + console.log(`[HOOK DEBUG] postHook - logging trace for tool: ${toolName}, intent: ${activeIntentId}`) await this.logTraceEntry(toolName, toolUse, task, activeIntentId, result) + + // Phase 4: Update file hash cache after successful write + const nativeArgs = (toolUse as any).nativeArgs + const params = toolUse.params as any + const filePath = (nativeArgs?.path || nativeArgs?.file_path || params?.path || params?.file_path) as + | string + | undefined + + if (filePath) { + try { + const absolutePath = path.resolve(task.cwd, filePath) + const newContent = await fs.readFile(absolutePath, "utf-8") + this.trackFileRead(filePath, newContent) + console.log(`[HOOK DEBUG] Updated file hash cache after write: ${filePath}`) + } catch (error) { + // File might not exist or be unreadable - ignore + console.warn(`[HOOK DEBUG] Could not update file hash cache for ${filePath}:`, error) + } + } + } else { + console.log( + `[HOOK DEBUG] postHook - skipping trace: tool=${toolName}, intent=${activeIntentId || "none"}, success=${success}`, + ) } } @@ -209,11 +737,9 @@ export class HookEngine { } const normalizedPath = path.normalize(filePath) - const absolutePath = path.resolve(workspaceRoot, normalizedPath) // Check if file matches any scope pattern for (const scopePattern of intent.owned_scope) { - // Simple glob matching (can be enhanced with minimatch later) if (this.matchesPattern(normalizedPath, scopePattern)) { return { valid: true } } @@ -233,14 +759,48 @@ export class HookEngine { * Simple pattern matching (supports ** and *) */ private matchesPattern(filePath: string, pattern: string): boolean { + // Normalize both to forward slashes for consistent matching + const normalizedFile = filePath.replace(/\\/g, "/") + const normalizedPattern = pattern.replace(/\\/g, "/") + // Convert glob pattern to regex - const regexPattern = pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\//g, "\\/") + const regexPattern = normalizedPattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\//g, "\\/") const regex = new RegExp(`^${regexPattern}$`) - return regex.test(filePath) + return regex.test(normalizedFile) + } + + /** + * Infer scope pattern from file path + */ + private inferScopeFromFilePath(filePath: string): string { + const normalizedPath = path.normalize(filePath).replace(/\\/g, "/") + const parts = normalizedPath.split("/") + + // If it's in src/, infer the scope based on the directory structure + if (parts[0] === "src" && parts.length > 1) { + const dir = parts[1] + return `src/${dir}/**` + } + + // Default: use the parent directory pattern + if (parts.length > 1) { + const parentDir = parts.slice(0, -1).join("/") + return `${parentDir}/**` + } + + // Fallback: just the file's directory + return path.dirname(normalizedPath).replace(/\\/g, "/") + "/**" } /** * Log trace entry to agent_trace.jsonl + * + * FIX: Now correctly extracts file paths from both nativeArgs and params, + * handling different param names across tools: + * - write_to_file uses "path" + * - edit_file, edit, search_replace use "file_path" + * - apply_diff uses "path" + * - apply_patch extracts paths from the patch content */ private async logTraceEntry( toolName: ToolName, @@ -258,33 +818,90 @@ export class HookEngine { // Git not available or not a git repo } - // Extract file path and content from tool params + // FIX: Extract file path from nativeArgs first (typed), then fall back to params + // Different tools use different parameter names for the file path + const nativeArgs = (toolUse as any).nativeArgs const params = toolUse.params as any - const filePath = params.path as string | undefined - if (!filePath) { - return // Can't log without file path + let filePath = // nativeArgs (preferred - typed) + (nativeArgs?.path || + nativeArgs?.file_path || + // params (fallback - stringified) + params?.path || + params?.file_path) as string | undefined + + // If no direct file path (e.g., apply_patch), extract from patch content + let resolvedFilePath = filePath + if (!resolvedFilePath) { + const patchContent = nativeArgs?.patch || params?.patch + if (patchContent && typeof patchContent === "string") { + // Try unified diff format first: "--- a/path/to/file.ts" or "+++ b/path/to/file.ts" + const unifiedDiffMatch = patchContent.match(/^(?:---|\+\+\+)\s+(?:a\/|b\/)?(.+?)(?:\s|$)/m) + if (unifiedDiffMatch && unifiedDiffMatch[1]) { + resolvedFilePath = unifiedDiffMatch[1].trim() + } else { + // Try custom format: "Update File: path/to/file.ts" or "Create File: path/to/file.ts" + const fileMatches = patchContent.match(/(?:Update|Create|Delete)\s+File:\s*(.+)/gm) + if (fileMatches && fileMatches.length > 0) { + // Use the first file path found + const match = fileMatches[0].match(/(?:Update|Create|Delete)\s+File:\s*(.+)/) + if (match && match[1]) { + resolvedFilePath = match[1].trim() + } + } + } + } + } + + if (!resolvedFilePath) { + console.warn( + `[HOOK DEBUG] logTraceEntry - no file path found for tool ${toolName}. ` + + `nativeArgs keys: ${nativeArgs ? Object.keys(nativeArgs).join(", ") : "none"}, ` + + `params keys: ${params ? Object.keys(params).join(", ") : "none"}`, + ) + return } + console.log( + `[HOOK DEBUG] logTraceEntry - tool: ${toolName}, file: ${resolvedFilePath}, intent: ${intentId}`, + ) + // Read file content to compute hash - const absolutePath = path.resolve(task.cwd, filePath) + const absolutePath = path.resolve(task.cwd, resolvedFilePath) let fileContent = "" + let oldContent: string | null = null let startLine = 1 let endLine = 1 + // Phase 3: Get old content for mutation classification + // Try to get from cached hash or read from trace try { + const cached = this.fileHashCache.get(resolvedFilePath) + if (cached) { + // We have a cached hash, but we need the actual content for classification + // For now, we'll read the file and compare + // In a more sophisticated implementation, we could store content snippets + } + fileContent = await fs.readFile(absolutePath, "utf-8") const lines = fileContent.split("\n") endLine = lines.length // If we have line numbers in params, use them if (params.start_line !== undefined && params.end_line !== undefined) { - startLine = params.start_line - endLine = params.end_line + startLine = parseInt(params.start_line, 10) || 1 + endLine = parseInt(params.end_line, 10) || lines.length } - } catch { - // File doesn't exist or can't be read - return + + // Phase 3: Try to get old content from task's diffViewProvider if available + // This is a best-effort approach - in production, you might want a more robust solution + if ((task as any).diffViewProvider?.originalContent !== undefined) { + oldContent = (task as any).diffViewProvider.originalContent + } + } catch (readError) { + console.warn(`[HOOK DEBUG] logTraceEntry - could not read file ${absolutePath}: ${readError}`) + // File might have been deleted or moved - still log the trace entry + // Use empty content for hash } // Extract relevant code block @@ -293,19 +910,27 @@ export class HookEngine { const codeBlock = relevantLines.join("\n") const contentHash = this.dataModel.computeContentHash(codeBlock) + // Phase 3: Classify mutation type + const classification = this.dataModel.classifyMutation(oldContent, fileContent, resolvedFilePath) + console.log( + `[HOOK DEBUG] Mutation classification: ${classification.mutation_class} (${classification.confidence}) - ${classification.reason}`, + ) + // Get model identifier from task const modelId = task.api.getModel().id - // Build trace entry + // Build trace entry with Phase 3 enhancements const traceEntry = { id: `trace-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`, timestamp: new Date().toISOString(), + tool_name: toolName, + mutation_class: classification.mutation_class, // Phase 3: Include mutation classification vcs: { revision_id: gitRevision, }, files: [ { - relative_path: filePath, + relative_path: resolvedFilePath, conversations: [ { url: `task-${task.taskId}`, @@ -333,10 +958,133 @@ export class HookEngine { } await this.dataModel.appendTraceEntry(traceEntry) + console.log( + `[HOOK DEBUG] logTraceEntry - trace entry appended for ${resolvedFilePath} under intent ${intentId}`, + ) + + // Update the spatial map as living documentation (sidecar-only; should not affect usability). + await this.updateIntentMapFromMutation({ + task, + intentId, + filePath: resolvedFilePath, + startLine, + endLine, + mutationClass: classification.mutation_class, + timestamp: traceEntry.timestamp, + }) } catch (error) { console.error("Failed to log trace entry:", error) // Don't throw - logging failures shouldn't break tool execution } } -} + /** + * Keep `.orchestration/intent_map.md` updated so it acts as living documentation. + * Best-effort: failures should never block tool execution. + */ + private async updateIntentMapFromMutation(args: { + task: Task + intentId: string + filePath: string + startLine: number + endLine: number + mutationClass: "AST_REFACTOR" | "INTENT_EVOLUTION" + timestamp: string + }): Promise { + try { + const mapPath = path.join(this.dataModel.getOrchestrationDir(), "intent_map.md") + + let content = "" + try { + content = await fs.readFile(mapPath, "utf-8") + } catch { + content = `# Intent Map + +This file maps high-level business intents to physical files and AST nodes. + +## Intents + +` + } + + // Best-effort intent metadata + let intentName: string | undefined + let intentStatus: string | undefined + const cachedIntent = (args.task as any).activeIntent as ActiveIntent | undefined + if (cachedIntent?.id === args.intentId) { + intentName = cachedIntent.name + intentStatus = cachedIntent.status + } else { + const loaded = await this.dataModel.getIntent(args.intentId) + if (loaded) { + intentName = loaded.name + intentStatus = loaded.status + } + } + + const sectionTitle = intentName ? `${args.intentId}: ${intentName}` : `${args.intentId}` + const changeLine = ` - ${args.timestamp}: \`${args.filePath}\` (lines ${args.startLine}-${args.endLine}) — ${args.mutationClass}` + + const headerRegex = new RegExp(`^##\\s+${this.escapeRegExp(args.intentId)}\\b.*$`, "m") + const match = content.match(headerRegex) + + if (!match || match.index === undefined) { + const statusLine = intentStatus ? `- **Status:** ${intentStatus}\n` : "" + const section = + `\n## ${sectionTitle}\n` + + `- **Last Updated:** ${args.timestamp}\n` + + statusLine + + `- **Recent Changes:**\n` + + `${changeLine}\n` + await fs.writeFile(mapPath, content.trimEnd() + section + "\n", "utf-8") + return + } + + const sectionStart = match.index + const afterHeaderIdx = content.indexOf("\n", sectionStart) + const nextHeaderRel = content.slice(afterHeaderIdx + 1).search(/^##\s+/m) + const sectionEnd = nextHeaderRel === -1 ? content.length : afterHeaderIdx + 1 + nextHeaderRel + + // Ensure Last Updated exists (insert right after header line) + const headerLineEnd = afterHeaderIdx + 1 + const sectionSlice = content.slice(sectionStart, sectionEnd) + if (sectionSlice.includes("- **Last Updated:**")) { + content = + content.slice(0, sectionStart) + + sectionSlice.replace(/^\- \*\*Last Updated:\*\* .*$/m, `- **Last Updated:** ${args.timestamp}`) + + content.slice(sectionEnd) + } else { + content = + content.slice(0, headerLineEnd) + + `- **Last Updated:** ${args.timestamp}\n` + + content.slice(headerLineEnd) + } + + // Recompute section bounds after possible insertion + const updatedAfterHeaderIdx = content.indexOf("\n", sectionStart) + const updatedNextHeaderRel = content.slice(updatedAfterHeaderIdx + 1).search(/^##\s+/m) + const updatedSectionEnd = + updatedNextHeaderRel === -1 ? content.length : updatedAfterHeaderIdx + 1 + updatedNextHeaderRel + + const updatedSection = content.slice(sectionStart, updatedSectionEnd) + if (updatedSection.includes("- **Recent Changes:**")) { + const rcIdx = content.indexOf("- **Recent Changes:**", sectionStart) + const insertAt = content.indexOf("\n", rcIdx) + 1 + content = content.slice(0, insertAt) + changeLine + "\n" + content.slice(insertAt) + } else { + // Append block within the section + const statusLine = intentStatus ? `- **Status:** ${intentStatus}\n` : "" + const addBlock = `\n${statusLine}- **Recent Changes:**\n${changeLine}\n` + content = content.slice(0, updatedSectionEnd) + addBlock + content.slice(updatedSectionEnd) + } + + await fs.writeFile(mapPath, content, "utf-8") + } catch (error) { + console.warn("[HOOK DEBUG] Failed to update intent_map.md:", error) + } + } + + private escapeRegExp(input: string): string { + return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + } +} From b8f44b1c44947ed1535deded261296e713e9310d Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:57:48 +0300 Subject: [PATCH 37/41] chore: commit src/hooks/OrchestrationDataModel.ts --- src/hooks/OrchestrationDataModel.ts | 246 +++++++++++++++++++++++++++- 1 file changed, 241 insertions(+), 5 deletions(-) diff --git a/src/hooks/OrchestrationDataModel.ts b/src/hooks/OrchestrationDataModel.ts index 5b135509149..ed1bc3f506b 100644 --- a/src/hooks/OrchestrationDataModel.ts +++ b/src/hooks/OrchestrationDataModel.ts @@ -30,6 +30,20 @@ export interface AgentTraceRange { content_hash: string } +/** + * Mutation classification types (Phase 3 requirement) + */ +export type MutationClass = "AST_REFACTOR" | "INTENT_EVOLUTION" + +/** + * Mutation classification result + */ +export interface MutationClassification { + mutation_class: MutationClass + confidence: "high" | "medium" | "low" + reason?: string +} + export interface AgentTraceConversation { url: string contributor: { @@ -51,6 +65,8 @@ export interface AgentTraceFile { export interface AgentTraceEntry { id: string timestamp: string + tool_name?: string // Phase 3: Track which tool made the change + mutation_class?: MutationClass // Phase 3: AST_REFACTOR or INTENT_EVOLUTION vcs: { revision_id: string } @@ -125,6 +141,25 @@ This file contains persistent knowledge shared across parallel sessions (Archite ` await fs.writeFile(agentPath, header, "utf-8") } + + // Initialize .intentignore if it doesn't exist (Phase 2 requirement) + const intentIgnorePath = path.join(this.orchestrationDir, ".intentignore") + try { + await fs.access(intentIgnorePath) + } catch { + // File doesn't exist, create it with header + const header = `# Intent Ignore File +# List intent IDs that should be protected from modifications +# One intent ID per line +# Lines starting with # are comments +# +# Example: +# INT-005 # Legacy system - deprecated +# INT-010 # Production critical - manual changes only + +` + await fs.writeFile(intentIgnorePath, header, "utf-8") + } } catch (error) { console.error("Failed to initialize orchestration directory:", error) throw error @@ -201,7 +236,10 @@ This file contains persistent knowledge shared across parallel sessions (Archite try { const content = await fs.readFile(tracePath, "utf-8") - const lines = content.trim().split("\n").filter((line) => line.trim() && !line.startsWith("#")) + const lines = content + .trim() + .split("\n") + .filter((line) => line.trim() && !line.startsWith("#")) const entries: AgentTraceEntry[] = [] @@ -213,9 +251,7 @@ This file contains persistent knowledge shared across parallel sessions (Archite // Check if any file's conversation references this intent const referencesIntent = entry.files.some((file) => file.conversations.some((conv) => - conv.related.some( - (rel) => rel.type === "intent" && rel.value === intentId, - ), + conv.related.some((rel) => rel.type === "intent" && rel.value === intentId), ), ) @@ -250,11 +286,211 @@ This file contains persistent knowledge shared across parallel sessions (Archite return crypto.createHash("sha256").update(content).digest("hex") } + /** + * Classify mutation type: AST_REFACTOR vs INTENT_EVOLUTION (Phase 3 requirement) + * + * Heuristics: + * - AST_REFACTOR: Same semantic meaning, structural changes (renames, formatting, reorganization) + * - INTENT_EVOLUTION: New functionality, feature additions, behavior changes + * + * This is a simplified heuristic - in production, this could use AST diffing or ML models + */ + classifyMutation(oldContent: string | null, newContent: string, filePath: string): MutationClassification { + // If file didn't exist before, it's always INTENT_EVOLUTION + if (!oldContent || oldContent === "") { + return { + mutation_class: "INTENT_EVOLUTION", + confidence: "high", + reason: "New file creation", + } + } + + // Normalize whitespace for comparison + const oldNormalized = oldContent.replace(/\s+/g, " ").trim() + const newNormalized = newContent.replace(/\s+/g, " ").trim() + + // If content is identical (after normalization), it's not a mutation + if (oldNormalized === newNormalized) { + return { + mutation_class: "AST_REFACTOR", + confidence: "high", + reason: "No semantic changes detected", + } + } + + // Calculate similarity ratio + const similarity = this.calculateSimilarity(oldNormalized, newNormalized) + + // Heuristic: If >80% similar, likely a refactor + if (similarity > 0.8) { + // Check if it's mostly structural changes + const oldLines = oldContent.split("\n") + const newLines = newContent.split("\n") + const lineCountDiff = Math.abs(oldLines.length - newLines.length) / Math.max(oldLines.length, 1) + + // If line count changed significantly, might be evolution + if (lineCountDiff > 0.3) { + return { + mutation_class: "INTENT_EVOLUTION", + confidence: "medium", + reason: `Significant line count change (${Math.round(lineCountDiff * 100)}%) despite high similarity`, + } + } + + return { + mutation_class: "AST_REFACTOR", + confidence: similarity > 0.9 ? "high" : "medium", + reason: `High similarity (${Math.round(similarity * 100)}%) suggests refactoring`, + } + } + + // Check for new function/class definitions (strong indicator of evolution) + const newFunctionPattern = /(?:function|class|const|let|var)\s+\w+\s*[=:\(]/g + const oldMatches = (oldContent.match(newFunctionPattern) || []).length + const newMatches = (newContent.match(newFunctionPattern) || []).length + + if (newMatches > oldMatches) { + return { + mutation_class: "INTENT_EVOLUTION", + confidence: "high", + reason: `New code definitions detected (${newMatches - oldMatches} new)`, + } + } + + // Check for significant content addition + const contentGrowth = (newContent.length - oldContent.length) / Math.max(oldContent.length, 1) + if (contentGrowth > 0.5) { + return { + mutation_class: "INTENT_EVOLUTION", + confidence: "medium", + reason: `Significant content growth (${Math.round(contentGrowth * 100)}%)`, + } + } + + // Default: if similarity is low, likely evolution + return { + mutation_class: similarity < 0.5 ? "INTENT_EVOLUTION" : "AST_REFACTOR", + confidence: "low", + reason: `Similarity: ${Math.round(similarity * 100)}%`, + } + } + + /** + * Calculate similarity ratio between two strings using Levenshtein distance + */ + private calculateSimilarity(str1: string, str2: string): number { + const maxLen = Math.max(str1.length, str2.length) + if (maxLen === 0) return 1.0 + + const distance = this.levenshteinDistance(str1, str2) + return 1 - distance / maxLen + } + + /** + * Calculate Levenshtein distance between two strings + */ + private levenshteinDistance(str1: string, str2: string): number { + const m = str1.length + const n = str2.length + const dp: number[][] = [] + + for (let i = 0; i <= m; i++) { + dp[i] = [i] + } + for (let j = 0; j <= n; j++) { + dp[0][j] = j + } + + for (let i = 1; i <= m; i++) { + for (let j = 1; j <= n; j++) { + if (str1[i - 1] === str2[j - 1]) { + dp[i][j] = dp[i - 1][j - 1] + } else { + dp[i][j] = Math.min( + dp[i - 1][j] + 1, // deletion + dp[i][j - 1] + 1, // insertion + dp[i - 1][j - 1] + 1, // substitution + ) + } + } + } + + return dp[m][n] + } + + /** + * Append lesson learned to AGENT.md (Phase 4 requirement) + */ + async appendLesson(lesson: string, context?: { tool?: string; error?: string; file?: string }): Promise { + const agentPath = path.join(this.orchestrationDir, "AGENT.md") + try { + let content = await fs.readFile(agentPath, "utf-8") + + // Ensure Lessons Learned section exists + if (!content.includes("## Lessons Learned")) { + content += "\n\n## Lessons Learned\n\n" + } + + // Append new lesson with timestamp + const timestamp = new Date().toISOString() + const contextInfo = context + ? `\n**Context:** ${context.tool ? `Tool: ${context.tool}` : ""}${context.file ? ` | File: ${context.file}` : ""}${context.error ? ` | Error: ${context.error}` : ""}\n` + : "" + const lessonEntry = `### ${timestamp}\n${contextInfo}${lesson}\n\n---\n\n` + + // Find the Lessons Learned section and append + const lessonsIndex = content.indexOf("## Lessons Learned") + if (lessonsIndex !== -1) { + const afterHeader = content.indexOf("\n", lessonsIndex) + 1 + content = content.slice(0, afterHeader) + lessonEntry + content.slice(afterHeader) + } else { + content += `\n## Lessons Learned\n\n${lessonEntry}` + } + + await fs.writeFile(agentPath, content, "utf-8") + } catch (error) { + console.error("Failed to append lesson to AGENT.md:", error) + // Don't throw - lesson recording shouldn't break execution + } + } + /** * Get orchestration directory path */ getOrchestrationDir(): string { return this.orchestrationDir } -} + /** + * Read .intentignore file and return list of ignored intent IDs (Phase 2 requirement) + */ + async readIntentIgnore(): Promise { + const intentIgnorePath = path.join(this.orchestrationDir, ".intentignore") + try { + const content = await fs.readFile(intentIgnorePath, "utf-8") + const lines = content.split("\n") + const ignoredIntents: string[] = [] + + for (const line of lines) { + // Remove comments and trim + const cleanLine = line.split("#")[0].trim() + if (cleanLine && !cleanLine.startsWith("#")) { + ignoredIntents.push(cleanLine) + } + } + + return ignoredIntents + } catch (error) { + // File doesn't exist or can't be read - return empty array + return [] + } + } + + /** + * Check if an intent ID is in the ignore list + */ + async isIntentIgnored(intentId: string): Promise { + const ignoredIntents = await this.readIntentIgnore() + return ignoredIntents.includes(intentId) + } +} From 5551849f1db33399e47b71a567549cd4789f1465 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:58:14 +0300 Subject: [PATCH 38/41] chore: commit src/hooks/RecordLessonTool.ts --- src/hooks/RecordLessonTool.ts | 46 +++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 src/hooks/RecordLessonTool.ts diff --git a/src/hooks/RecordLessonTool.ts b/src/hooks/RecordLessonTool.ts new file mode 100644 index 00000000000..53ece722b7f --- /dev/null +++ b/src/hooks/RecordLessonTool.ts @@ -0,0 +1,46 @@ +import { BaseTool, ToolCallbacks } from "../core/tools/BaseTool" +import type { ToolUse } from "../shared/tools" +import { Task } from "../core/task/Task" +import { OrchestrationDataModel } from "./OrchestrationDataModel" + +interface RecordLessonParams { + lesson: string + context?: { + tool?: string + error?: string + file?: string + } +} + +/** + * Tool for recording lessons learned to AGENT.md (Phase 4 requirement) + * This tool allows the agent to append lessons learned when verification steps fail + * or when important insights are discovered during development. + */ +export class RecordLessonTool extends BaseTool<"record_lesson"> { + readonly name = "record_lesson" as const + + async execute(params: RecordLessonParams, task: Task, callbacks: ToolCallbacks): Promise { + const { pushToolResult, handleError } = callbacks + + if (!params.lesson || params.lesson.trim() === "") { + task.consecutiveMistakeCount++ + task.recordToolError("record_lesson") + pushToolResult("Error: lesson parameter is required and cannot be empty.") + return + } + + try { + const dataModel = new OrchestrationDataModel(task.cwd) + await dataModel.initialize() + await dataModel.appendLesson(params.lesson.trim(), params.context) + + pushToolResult(`Lesson recorded successfully to .orchestration/AGENT.md`) + task.consecutiveMistakeCount = 0 + } catch (error) { + await handleError("recording lesson", error as Error) + } + } +} + +export const recordLessonTool = new RecordLessonTool() From b7568c88529a7ab9f679b54fa3b4bf64a756c351 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:58:49 +0300 Subject: [PATCH 39/41] chore: commit src/hooks/SelectActiveIntentTool.ts --- src/hooks/SelectActiveIntentTool.ts | 46 +++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/src/hooks/SelectActiveIntentTool.ts b/src/hooks/SelectActiveIntentTool.ts index fedb7364687..879e6394819 100644 --- a/src/hooks/SelectActiveIntentTool.ts +++ b/src/hooks/SelectActiveIntentTool.ts @@ -31,17 +31,54 @@ export class SelectActiveIntentTool extends BaseTool<"select_active_intent"> { const dataModel = new OrchestrationDataModel(task.cwd) await dataModel.initialize() + // Phase 2: Check if intent is in .intentignore (protected) + const isIgnored = await dataModel.isIntentIgnored(intent_id) + if (isIgnored) { + task.consecutiveMistakeCount++ + task.recordToolError("select_active_intent") + const errorJson = JSON.stringify( + { + error_type: "intent_protected", + message: `Intent "${intent_id}" is protected and cannot be modified. This intent is listed in .orchestration/.intentignore.`, + details: { + intent_id: intent_id, + reason: "intent_in_ignore_list", + file: ".orchestration/.intentignore", + }, + recoverable: false, + suggested_action: + "Select a different intent or ask user to remove this intent from .intentignore", + }, + null, + 2, + ) + pushToolResult(errorJson) + return + } + // Load the intent from active_intents.yaml const intent = await dataModel.getIntent(intent_id) if (!intent) { task.consecutiveMistakeCount++ task.recordToolError("select_active_intent") - pushToolResult( - formatResponse.toolError( - `Intent "${intent_id}" not found in active_intents.yaml. Please use a valid intent ID.`, - ), + const intentsData = await dataModel.readActiveIntents() + const errorJson = JSON.stringify( + { + error_type: "intent_not_found", + message: `Intent "${intent_id}" not found in active_intents.yaml. Please use a valid intent ID.`, + details: { + requested_intent_id: intent_id, + available_intent_ids: intentsData.active_intents.map((i) => i.id), + available_intents_count: intentsData.active_intents.length, + }, + recoverable: true, + suggested_action: `Use one of the available intent IDs: ${intentsData.active_intents.map((i) => i.id).join(", ")}`, + }, + null, + 2, ) + pushToolResult(errorJson) return } @@ -126,4 +163,3 @@ ${recentHistorySection} } export const selectActiveIntentTool = new SelectActiveIntentTool() - From 922841e6a903a35d854342b94f4dc39ab8d88dd8 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:59:19 +0300 Subject: [PATCH 40/41] chore: commit src/shared/tools.ts --- src/shared/tools.ts | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/src/shared/tools.ts b/src/shared/tools.ts index 6ae8eecfc32..235e49718b5 100644 --- a/src/shared/tools.ts +++ b/src/shared/tools.ts @@ -80,6 +80,15 @@ export const toolParamNames = [ // read_file legacy format parameter (backward compatibility) "files", "line_ranges", + // select_active_intent parameter + "intent_id", + // create_intent parameters + "intent_name", + "owned_scope", + "constraints", + "acceptance_criteria", + // record_lesson parameters + "lesson", ] as const export type ToolParamName = (typeof toolParamNames)[number] @@ -115,6 +124,23 @@ export type NativeToolArgs = { update_todo_list: { todos: string } use_mcp_tool: { server_name: string; tool_name: string; arguments?: Record } write_to_file: { path: string; content: string } + select_active_intent: { intent_id: string } + create_intent: { + prompt: string + intent_id?: string + intent_name?: string + owned_scope?: string[] + constraints?: string[] + acceptance_criteria?: string[] + } + record_lesson: { + lesson: string + context?: { + tool?: string + error?: string + file?: string + } + } // Add more tools as they are migrated to native protocol } @@ -266,6 +292,7 @@ export type ToolGroupConfig = { export const TOOL_DISPLAY_NAMES: Record = { select_active_intent: "select active intent", + create_intent: "create intent", execute_command: "run commands", read_file: "read files", read_command_output: "read command output", @@ -290,6 +317,7 @@ export const TOOL_DISPLAY_NAMES: Record = { skill: "load skill", generate_image: "generate images", custom_tool: "use custom tools", + record_lesson: "record lesson", } as const // Define available tool groups. @@ -316,6 +344,7 @@ export const TOOL_GROUPS: Record = { // Tools that are always available to all modes. export const ALWAYS_AVAILABLE_TOOLS: ToolName[] = [ "select_active_intent", + "create_intent", "ask_followup_question", "attempt_completion", "switch_mode", From d7b72338bbbee9b7815add2cc7ee337de6725e77 Mon Sep 17 00:00:00 2001 From: sumeyaaaa Date: Sat, 21 Feb 2026 13:59:46 +0300 Subject: [PATCH 41/41] chore: commit src/tsconfig.json --- src/tsconfig.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tsconfig.json b/src/tsconfig.json index 11d189aa2e0..77a425049de 100644 --- a/src/tsconfig.json +++ b/src/tsconfig.json @@ -21,7 +21,7 @@ "useUnknownInCatchVariables": false }, "include": ["."], - "exclude": ["node_modules"], + "exclude": ["node_modules", "api/login.ts"], "watchOptions": { "watchFile": "useFsEvents", "watchDirectory": "useFsEvents",