# Code Guardrails & File Operation Rules # Code Guardrails & File Operation Rules
Relevant source files The following files were used as context for generating this wiki page: - [.devin/rules/code-guardrails.md](.devin/rules/code-guardrails.md) - [.devin/rules/file-operations.md](.devin/rules/file-operations.md) - [.devin/rules/temp-files.md](.devin/rules/temp-files.md)
This page documents the technical constraints and operational protocols governing AI agent behavior within the `primebrick-v3-microservices` repository. These rules ensure system stability, maintain architectural integrity, and prevent repository pollution through strict execution limits and file management policies. ## 1. Code Execution Guardrails The repository enforces a "fail-fast" policy for all automated code modifications. These guardrails prevent the AI agent from entering recursive error-correction loops or introducing large-scale regressions. ### 1.1 Self-Correction & Retry Logic AI agents are permitted a maximum of **2 self-correction attempts** to resolve terminal command failures, linter errors, or test regressions [.devin/rules/code-guardrails.md:6-7](). If the error persists after the second attempt, the agent must immediately halt all operations [.devin/rules/code-guardrails.md:8](). ### 1.2 BLOCKED State & Escalation Upon reaching the retry limit, the system transitions to a **BLOCKED** state [.devin/rules/code-guardrails.md:9](). The agent is required to: 1. Update the Kanban board/Command Center status to `BLOCKED`. 2. Report the full error logs in the communication channel. 3. Wait for manual user intervention before proceeding [.devin/rules/code-guardrails.md:10](). ### 1.3 Scope Locking & Atomicity To maintain architectural consistency, agents operate under "Scope Locking" constraints: * **Signature Protection**: Existing function signatures, API endpoints, and shared state structures cannot be modified unless specifically authorized in a pre-approved Markdown plan [.devin/rules/code-guardrails.md:13](). * **Iterative Application**: Changes must be atomic. Agents must run linters or tests after modifying single modules rather than batching edits across multiple files [.devin/rules/code-guardrails.md:14](). **Sources:** [.devin/rules/code-guardrails.md:1-15]() --- ## 2. File Operation Rules File operations prioritize empirical verification over IDE state. This prevents errors caused by out-of-sync editor buffers or memory-resident file copies. ### 2.1 Empirical Verification Workflow Agents must never assume a file's state based on the editor's context [.devin/rules/file-operations.md:20-22](). Every operation follows a strict verification cycle using system-level tools. **File Verification Process Flow** ```mermaid graph TD "START"["Start File Operation"] --> "VERIFY_EXIST"["Verify Existence via Test-Path/ls"] "VERIFY_EXIST" --> "VERIFY_CONTENT"["Verify Content via read/grep"] "VERIFY_CONTENT" --> "EXECUTE"["Execute File Operation"] "EXECUTE" --> "POST_VERIFY"["Post-Operation Empirical Check"] "POST_VERIFY" --> "END"["Operation Complete"] ``` **Sources:** [.devin/rules/file-operations.md:15-31]() ### 2.2 Tool-Based Verification The following tools are mandated for file state confirmation: * **Existence**: `Test-Path` (PowerShell) or `ls` (Unix) [.devin/rules/file-operations.md:16](). * **Content**: `read` tool [.devin/rules/file-operations.md:17](). * **Search**: `grep` tool for pattern matching [.devin/rules/file-operations.md:18](). * **Discovery**: `find_file_by_name` for location mapping [.devin/rules/file-operations.md:19](). ### 2.3 Path Conventions * **Relative Paths**: Agents must use relative paths from the workspace root (e.g., `primebrick-fe-v3/src/...`) [.devin/rules/file-operations.md:34](). * **Pathing Restrictions**: Absolute paths and leading slashes are prohibited unless explicitly required by a specific tool [.devin/rules/file-operations.md:35-36](). **Sources:** [.devin/rules/file-operations.md:1-42]() --- ## 3. Temporary File Management To maintain a clean repository state, the creation of temporary files (scripts, patches, or intermediate logs) within the project directories is strictly forbidden [.devin/rules/temp-files.md:11-15](). ### 3.1 Designated Temp Locations If temporary files are necessary, they must be stored in external system directories: * **Windows**: `d:\git\primebrick\temp\` [.devin/rules/temp-files.md:18](). * **Linux/Mac**: `/tmp/` or `/var/tmp/` [.devin/rules/temp-files.md:19](). ### 3.2 Cleanup Policy All temporary files must be removed immediately after use using `Remove-Item -Force` or `rm -f` [.devin/rules/temp-files.md:22](). Cleanup must be empirically verified with `Test-Path` before the agent concludes the session [.devin/rules/temp-files.md:24,35](). ### 3.3 In-Memory Preference Agents are instructed to prefer in-memory operations over disk writes whenever possible, utilizing string manipulation or subagents for complex tasks [.devin/rules/temp-files.md:26-30](). **Temp File Life Cycle** ```mermaid sequenceDiagram participant "Agent" as Agent Logic participant "Temp" as d:\git\primebrick\temp\ participant "Repo" as primebrick-us-v3/ "Agent"->>"Temp": Create temporary script/patch Note over "Agent", "Repo": Prohibited: Writing temp to Repo/ "Agent"->>"Agent": Execute logic using Temp file "Agent"->>"Temp": Remove-Item -Force "Agent"->>"Temp": Test-Path (Verify deletion) ``` **Sources:** [.devin/rules/temp-files.md:1-37]() --- ## 4. Summary of Constraints | Category | Rule | Enforcement Mechanism | | :--- | :--- | :--- | | **Execution** | Max 2 Retries | Hard stop and transition to `BLOCKED` state [.devin/rules/code-guardrails.md:7-9]() | | **Modification** | Scope Locking | Prohibition of unauthorized signature changes [.devin/rules/code-guardrails.md:13]() | | **Verification** | Empirical Tools | Mandatory use of `ls`, `grep`, and `read` over IDE context [.devin/rules/file-operations.md:15-20]() | | **Pollution** | Temp Isolation | No `.js`, `.py`, or `.patch` files in project repos [.devin/rules/temp-files.md:11-15]() | | **IDE Interaction** | No Auto-Open | Plans and internal scripts must not be opened in the editor [.devin/rules/file-operations.md:11-13]() | **Sources:** [.devin/rules/code-guardrails.md:1-15](), [.devin/rules/file-operations.md:1-42](), [.devin/rules/temp-files.md:1-37]() ---