agentme 0.15.0 → 0.17.0

package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md

@@ -82,7 +82,7 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 - Outbound adapters live under `adapters/connectors/` with one subfolder per external resource, named descriptively (e.g., `postgres/`, `stripe-api/`, `redis-cache/`).
 - `shared/` must contain only infrastructure-agnostic utilities — not business rules or domain logic.
 - Packages are flat by default; sub-packages are only introduced when a feature package itself exceeds ~400 lines or has clearly separable sub-concerns.
-- Application MAY import from Adapters when it simplifies the design (pragmatic coupling per edr-021 rule 05).
+- Application MAY import from Adapters when it simplifies the design (pragmatic coupling per edr-022 rule 05).
 - Consumer examples for reusable libraries belong in a sibling `examples/` folder and MUST import the public module path rather than reaching into internal source paths. Because Go libraries are not typically consumed from a local packaged artifact, local example validation may use a temporary module replacement for resolution, but the import path MUST remain the public module path.
 
 #### go.mod

package/.xdrs/agentme/edrs/application/015-cli-tool-standards.md

@@ -53,11 +53,10 @@ This keeps the user-facing command predictable while preserving a clean library
 #### Configuration
 
 - Prefer flags and positional arguments for simple inputs.
-- When configuration becomes long, nested, or repetitive, support a config file instead of pushing all values into flags.
+- When configuration becomes long, nested, or repetitive, use a YAML config file instead of pushing all values into flags. See [agentme-edr-027](../devops/027-environment-variable-configuration.md) for when `.env` values should be referenced from within that file.
 - By default, config-file discovery and loading must happen in the CLI layer, not in the application layer.
-- When a config file is supported, the CLI should try to load a JSON config file from `[cwd]/.[cli-name]rc` by default.
-- The CLI should also support an explicit config path flag such as `--config`.
-- For JavaScript tools, `cosmiconfig` is an acceptable implementation. Equivalent discovery libraries are acceptable in other ecosystems.
+- When a config file is supported, the CLI must try to load a YAML file from `[cwd]/[tool-name].yml` by default.
+- The CLI must also support an explicit config path flag such as `--config`.
 - The application layer must not depend on the presence of the config file; it should receive parsed configuration values from the CLI layer.
 - The application layer may load or parse config files only when that behavior is an explicit requirement of the application contract for non-CLI consumers as well.
 
@@ -106,4 +105,4 @@ This keeps the user-facing command predictable while preserving a clean library
 - [agentme-edr-009](../principles/009-error-handling.md) - Process error signaling and error handling expectations
 - [agentme-edr-010](010-golang-project-tooling.md) - Go CLI structure and verbose logging baseline
 - [agentme-edr-014](014-python-project-tooling.md) - Python packaging and CLI entry-point guidance
-- [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) - Example JSON configuration discovery library for JavaScript CLIs
+- [agentme-edr-027](../devops/027-environment-variable-configuration.md) - Environment variable configuration files; defines how `.env` values are referenced from YAML config files

package/.xdrs/agentme/edrs/application/018-ai-llm-development-standards.md

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-policy-018-ai-llm-development-standards
-description: Defines the standard framework, provider configuration, observability approach, and LLM mocking patterns for simple LLM calls in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls using LangChain, manages prompt context, or handles conversation history. For agentic patterns see agentme-edr-019, for workflow patterns see agentme-edr-020.
+description: Defines the standard framework, provider configuration, observability approach, and LLM mocking patterns for simple LLM calls in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls using LangChain, manages prompt context, or handles conversation history. For agentic patterns see agentme-edr-019, for workflow patterns see agentme-edr-021.
 apply-to: Python projects that make direct LLM calls, manage prompt context, or handle conversation threads
 valid-from: 2026-06-05
 ---
@@ -29,7 +29,7 @@ Three distinct tiers of LLM-based computation are recognized in this policy. Eve
 
 These tiers nest: in general, a Workflow may contain Agent nodes; an Agent uses LLM calls internally. The tier of a component is determined by its outermost controlling structure.
 
-See [agentme-edr-019](019-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-020](020-ai-workflow-development-standards.md) for Workflow implementation standards.
+See [agentme-edr-019](019-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-021](021-ai-workflow-development-standards.md) for Workflow implementation standards.
 
 ### Details
 
@@ -71,6 +71,7 @@ llm = ChatOpenAI(
 Enable LangChain auto-tracing at every application entry point by calling `mlflow.langchain.autolog()` during startup, before any LLM call is made.
 
 - This captures inputs, outputs, token counts, and latency for every LangChain chain or runnable automatically.
+- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../devops/008-common-targets.md) rule `09-ai-project-dev-targets`.
 
 #### 04-unit-test-mocking
 
@@ -173,8 +174,8 @@ prompt = PromptTemplate.from_file(
 ## References
 
 - [agentme-edr-019](019-ai-agents-development-standards.md) — Agent implementation standards (deepagents, tool-invocation loops)
-- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, MLflow run-level tracking)
+- [agentme-edr-021](021-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, MLflow run-level tracking)
 - [agentme-edr-004](../principles/004-unit-test-requirements.md) — Unit test requirements including external API mocking guidance
 - [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
 - [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
-- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking
+- [agentme-edr-028](028-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking

package/.xdrs/agentme/edrs/application/019-ai-agents-development-standards.md

@@ -1,7 +1,7 @@
 ---
 name: agentme-edr-policy-019-ai-agents-development-standards
-description: Defines the standard framework and patterns for building AI agents with tool-invocation loops using the deepagents framework. Use when building agents where the LLM autonomously decides which tools to call and when to stop. For simple LLM calls see agentme-edr-018, for workflow orchestration see agentme-edr-020.
-apply-to: AI agent projects that use tool-invocation loops where the LLM decides which tools to call and when to stop
+description: Defines the structural patterns and design decisions for building AI agents with tool-invocation loops using the deepagents framework: framework selection, sandbox setup, state naming, agent naming, composition patterns, and system prompt structure. Use when designing or scaffolding a new agent. For tool definitions, error handling, observability, and testing see agentme-edr-020. For simple LLM calls see agentme-edr-018, for workflow orchestration see agentme-edr-021.
+apply-to: AI agent projects — consult when designing agent structure, choosing sandbox approach, defining naming conventions, and composing multi-agent systems
 valid-from: 2026-06-05
 ---
 
@@ -9,9 +9,9 @@ valid-from: 2026-06-05
 
 ## Context and Problem Statement
 
-AI applications often need to give LLMs the ability to autonomously choose and invoke tools to accomplish tasks. Without standardized patterns for agent implementation, projects end up with incompatible approaches to tool definition, state management, and runtime environments.
+AI applications often need to give LLMs the ability to autonomously choose and invoke tools to accomplish tasks. Without standardized structural patterns for agent design, projects end up with incompatible approaches to framework selection, sandbox setup, state management, naming, composition, and system prompts.
 
-Which framework should be used for building agents with tool-invocation loops, and what are the essential patterns for agent state, tools, and execution environments?
+Which framework should be used for building agents, how should agents be sandboxed, named, composed, and how should their system prompts be structured?
 
 ## Decision Outcome
 
@@ -50,6 +50,7 @@ Use deepagents sandbox whenever ANY of the following is true:
 
 **Integration requirements:**
 
+- The sandbox MUST always be initialized with `virtual_mode=True` to prevent the agent from reading or writing files outside the mounted workspace. Omitting this flag allows the agent unrestricted host filesystem access, which is a security violation.
 - Initialize the sandbox at the start of the agent run and shut it down in the same `try/finally` block.
 - Pass the sandbox handle into the agent's state so all tool calls share the same sandbox instance.
 - If the host-side code needs to pass files into the sandbox (e.g. generated config or input data), create a temporary directory with `tempfile.mkdtemp()`, write the files there, and mount it into the sandbox. Clean it up in the `finally` block.
@@ -69,7 +70,7 @@ def run_file_analysis_agent(input_files: List[Path]) -> AnalysisResult:
             shutil.copy(f, tmp_dir)
         
         # Initialize sandbox with mounted directory
-        sandbox = Sandbox(mount_paths={tmp_dir: "/workspace"})
+        sandbox = Sandbox(mount_paths={tmp_dir: "/workspace"}, virtual_mode=True)
         
         # Run agent with sandbox
         agent = FileAnalysisAgent(sandbox=sandbox)
@@ -86,84 +87,9 @@ def run_file_analysis_agent(input_files: List[Path]) -> AnalysisResult:
 **State type naming:**
 
 - Agent state types MUST end with `_agent_state` suffix (e.g., `file_analyzer_agent_state`)
-- Follow [agentme-edr-020](020-ai-workflow-development-standards.md) rule `11-state-type-conventions` when agents are used as workflow nodes
+- Follow [agentme-edr-021](021-ai-workflow-development-standards.md) rule `11-state-type-conventions` when agents are used as workflow nodes
 
-#### 04-tool-definition-patterns
-
-Tools provided to agents MUST follow these patterns:
-
-**Tool signature:**
-
-```python
-from typing import Any, Dict
-
-def tool_name(arg1: str, arg2: int) -> Dict[str, Any]:
-    """
-    Brief description of what the tool does.
-    
-    Args:
-        arg1: Description of arg1
-        arg2: Description of arg2
-    
-    Returns:
-        Dictionary with tool execution results
-    """
-    # Tool implementation
-    return {"status": "success", "result": ...}
-```
-
-**Tool requirements:**
-
-- Tool names MUST be descriptive action verbs (e.g., `search_files`, `execute_command`, `read_document`)
-- Tool docstrings MUST clearly describe the tool's purpose, arguments, and return value (the LLM reads these)
-- Tools MUST return structured data (dictionaries or dataclasses), not bare strings or untyped values
-- Tools MUST handle errors gracefully and return error information in the result structure, not raise exceptions
-- Tools that interact with external systems MUST be placed in `adapters/connectors/` per [agentme-edr-026](026-pragmatic-hexagonal-architecture.md)
-
-**Error handling in tools:**
-
-```python
-def search_files(pattern: str, directory: str = ".") -> Dict[str, Any]:
-    """Search for files matching a glob pattern."""
-    try:
-        matches = list(Path(directory).glob(pattern))
-        return {
-            "status": "success",
-            "matches": [str(m) for m in matches],
-            "count": len(matches)
-        }
-    except Exception as e:
-        return {
-            "status": "error",
-            "error_message": str(e),
-            "error_type": type(e).__name__
-        }
-```
-
-#### 05-agent-error-handling-and-recovery
-
-Agents MUST implement robust error handling:
-
-**Maximum iteration limits:**
-
-- Every agent MUST have a maximum iteration limit to prevent infinite loops
-- The default maximum SHOULD be configurable and logged when reached
-- When the maximum is reached, the agent MUST return a structured failure result, not raise an exception
-
-**Tool failure handling:**
-
-- When a tool returns an error, the agent MUST be able to observe the error and decide on recovery actions
-- Tools MUST NOT raise exceptions for expected failures (network errors, file not found, etc.)
-- Agents MAY implement retry logic with exponential backoff for transient failures
-
-**Terminal states:**
-
-Agents MUST recognize and handle three terminal states:
-- **Success**: Goal achieved, task complete
-- **Failure**: Goal cannot be achieved, give up gracefully
-- **Timeout**: Maximum iterations reached, return partial results if possible
-
-#### 06-agent-naming-conventions
+#### 04-agent-naming-conventions
 
 Agent class names MUST follow the pattern `<Purpose>Agent` where `<Purpose>` describes what the agent does:
 
@@ -178,92 +104,14 @@ Agent class names MUST follow the pattern `<Purpose>Agent` where `<Purpose>` des
 - `MyAgent` (not descriptive)
 - `Agent1` (numbered, not semantic)
 
-When agents are used as nodes in workflows, the node name MUST use the `_agent` suffix per [agentme-edr-020](020-ai-workflow-development-standards.md) rule `09-node-naming-conventions`.
-
-#### 07-agent-observability
-
-Agent execution MUST be observable through logging and tracing:
-
-- Log each iteration of the perceive → plan → act → observe cycle with iteration number and tool selection.
-- Use structured logging (JSON) with fields: `iteration`, `tool_selected`, `tool_result_status`, `decision`.
-- For LLM calls within agents, follow [agentme-edr-018](018-ai-llm-development-standards.md) rule `03-llm-observability`.
-- When agents run as workflow nodes, MLflow tracking from the parent workflow automatically captures agent-level traces.
+When agents are used as nodes in workflows, the node name MUST use the `_agent` suffix per [agentme-edr-021](021-ai-workflow-development-standards.md) rule `09-node-naming-conventions`.
 
-**Example structured log entry:**
-
-```json
-{
-  "timestamp": "2026-06-05T10:30:45Z",
-  "agent": "FileAnalyzerAgent",
-  "iteration": 3,
-  "tool_selected": "search_files",
-  "tool_args": {"pattern": "*.py"},
-  "tool_result_status": "success",
-  "decision": "continue"
-}
-```
-
-#### 08-agent-unit-testing
-
-Agent LLM calls are external API calls and MUST be mocked in unit tests per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`.
-
-Because agents drive a tool-invocation loop — where the LLM decides which tools to call — the fake model must return **tool-call messages** followed by a final answer. Use **`GenericFakeChatModel`** for this:
-
-```python
-from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
-from langchain_core.messages import AIMessage
-
-def test_file_analyzer_agent_calls_search_then_stops():
-    # Iteration 1: LLM requests a tool call
-    tool_call_msg = AIMessage(
-        content="",
-        tool_calls=[{
-            "name": "search_files",
-            "args": {"pattern": "*.py", "directory": "/workspace"},
-            "id": "call_1"
-        }]
-    )
-    # Iteration 2: LLM produces a final answer after observing the tool result
-    final_msg = AIMessage(content="Found 3 Python files matching the pattern.")
-
-    fake_model = GenericFakeChatModel(messages=iter([tool_call_msg, final_msg]))
-
-    agent = FileAnalyzerAgent(model=fake_model)
-    result = agent.run(directory="/workspace")
-
-    assert result.status == "success"
-    assert "3 Python files" in result.summary
-```
-
-Agents MUST be designed so that the LLM instance is injectable (constructor parameter) to allow test doubles. See [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking` for the injectable LLM pattern.
-
-**`mock_deep_agent`**
-
-Place `mock_deep_agent` in a shared test utilities module (e.g., `tests/helpers.py`) so all test files that need it can import it from one location and mock deep_agent instances when needed.
-
-**Example usage:**
-
-```python
-from tests.helpers import mock_deep_agent
-
-def test_workflow_calls_subagent(mocker):
-    mock_deep_agent(
-        mocker,
-        "mypackage.nodes.analysis_node.create_workflow_agent",
-        output={"status": "success", "findings": ["issue A"]}
-    )
-
-    result = run_analysis_workflow(input_data)
-
-    assert result.findings == ["issue A"]
-```
-
-#### 09-agent-composition
+#### 05-agent-composition
 
 When multiple agents are needed:
 
 - **Single agent with multiple tools:** Use when tools share a common goal and context (e.g., a code analysis agent with `read_file`, `search_code`, and `analyze_pattern` tools).
-- **Multiple agents as workflow nodes:** Use when agents have distinct responsibilities and outputs that feed into each other. Orchestrate them using LangGraph per [agentme-edr-020](020-ai-workflow-development-standards.md).
+- **Multiple agents as workflow nodes:** Use when agents have distinct responsibilities and outputs that feed into each other. Orchestrate them using LangGraph per [agentme-edr-021](021-ai-workflow-development-standards.md).
 - Do NOT create nested agent loops (agent calling agent autonomously). Use workflows for multi-agent orchestration.
 
 **Decision criteria:**
@@ -274,11 +122,74 @@ When multiple agents are needed:
 | Multiple workflow-orchestrated agents | Each agent has a distinct goal; outputs flow between agents; deterministic sequencing needed |
 | Nested agents (FORBIDDEN) | Never — always use workflow orchestration instead |
 
+#### 06-agent-system-prompt-structure
+
+Every agent system prompt MUST follow this XML-section template. Sections must appear in this order. Required sections must always be present; optional sections may be omitted when they genuinely do not apply; never reorder them.
+
+```xml
+<OBJECTIVE>
+[A one or two-sentence summary of the agent's main deliverable.
+e.g.: Split the incoming file list into logical batches for parallel processing.]
+</OBJECTIVE>
+
+<ROLE>
+[Defines who the agent is, its area of expertise, and its core persona.
+If running inside a workflow, define exactly which node in WORKFLOW_CONTEXT this agent corresponds to.
+e.g.: You are the batch_planning_agent (see WORKFLOW_CONTEXT). You are an expert at partitioning large file sets into balanced, directory-aware batches.]
+</ROLE>
+
+<INPUT>
+[All inputs for this agent invocation. For standalone agents: list only the agent-specific inputs. For workflow agents: list workflow-level inputs shared across all agents first, then agent-specific inputs such as judge outcomes, counters, or intermediate results from upstream nodes.]
+</INPUT>
+
+<!-- Optional: include when the agent follows a non-trivial sequence of steps -->
+<STEPS>
+[Numbered list or chronological steps detailing how the agent should process an incoming request.
+e.g.:
+1. Analyse the file list and group files by directory.
+2. Assign files to batches respecting the size constraints.
+3. Emit the JSON output described in OUTPUT_FORMAT.]
+</STEPS>
+
+<!-- Optional: include when tool use needs explicit guidance -->
+<TOOL_GUIDANCE>
+[Explicit instructions on when and how to use external tools, preventing the agent from guessing or using the wrong sequence.
+e.g.: Do not call any tools. All reasoning is done in-context using the INPUT fields only.]
+</TOOL_GUIDANCE>
+
+<!-- Optional: include when hard constraints need to be stated explicitly -->
+<GUARDRAILS>
+[Hard, non-negotiable constraints the agent must never violate.
+e.g.: NEVER create batches with fewer than 5 or more than 20 files. NEVER split files from the same directory across different batches unless unavoidable.]
+</GUARDRAILS>
+
+<OUTPUT_FORMAT>
+[A templated example or JSON schema specifying exactly how the final response should look.
+e.g.: Respond with a JSON object matching this schema: ...]
+</OUTPUT_FORMAT>
+
+<!-- Workflow-only: omit this section for standalone (non-workflow) agents -->
+<WORKFLOW_CONTEXT>
+[A detailed prose or diagram description of the overall workflow graph so the agent understands its role within the larger flow. Reference the specific node name that maps to this agent. Include enough detail about upstream and downstream nodes so the agent can reason about its context.]
+</WORKFLOW_CONTEXT>
+```
+
+**Rules:**
+
+| Section | Required? | Notes |
+|---|---|---|
+| `<OBJECTIVE>` | Required | One or two sentences summarising the agent's main deliverable. |
+| `<ROLE>` | Required | Agent persona and expertise. When inside a workflow, MUST reference its node name from `<WORKFLOW_CONTEXT>`. |
+| `<INPUT>` | Required | List ALL inputs. For workflow agents: workflow-level inputs first, then agent-specific inputs. |
+| `<STEPS>` | Optional | Include when the agent follows a non-trivial numbered sequence of steps. |
+| `<TOOL_GUIDANCE>` | Optional | Include when tool use order or conditions need explicit direction. |
+| `<GUARDRAILS>` | Optional | Hard constraints that must never be violated. |
+| `<OUTPUT_FORMAT>` | Required | MUST include a concrete schema or templated example; do not leave it vague. |
+| `<WORKFLOW_CONTEXT>` | Conditional | MUST be omitted for standalone agents. MUST be present when the agent runs as a node inside a LangGraph workflow. |
+
 ## References
 
 - [agentme-edr-018](018-ai-llm-development-standards.md) — LLM development standards (LangChain configuration, mocking patterns)
-- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow development standards (using agents as workflow nodes)
-- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Hexagonal architecture (tool placement in adapters/connectors)
+- [agentme-edr-021](021-ai-workflow-development-standards.md) — Workflow development standards (using agents as workflow nodes)
+- [agentme-edr-020](020-ai-agents-quality-standards.md) — Agent implementation quality standards (tool definitions, error handling, observability, unit testing)
 - [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
-- [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
-- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking

package/.xdrs/agentme/edrs/application/020-ai-agents-quality-standards.md

@@ -0,0 +1,182 @@
+---
+name: agentme-edr-policy-020-ai-agents-quality-standards
+description: Defines implementation quality standards for AI agents: tool definition patterns, error handling and recovery, observability, and unit testing. Apply alongside agentme-edr-019 when implementing or reviewing agent code. For agent architecture and structural decisions (framework, sandbox, naming, composition, system prompts) see agentme-edr-019.
+apply-to: AI agent implementation code — apply when writing tools, error handlers, logging, and unit tests for agents
+valid-from: 2026-06-09
+---
+
+# agentme-edr-policy-020: AI agents quality standards
+
+## Context and Problem Statement
+
+Beyond selecting the right framework and structural patterns, agent implementations require consistent standards for how tools are defined, how errors are handled, how execution is observed, and how agents are tested. Without these standards, agents become hard to debug, unreliable, and untestable.
+
+How should agent tools be defined, what error handling must agents implement, how should agent execution be observed, and how should agents be unit tested?
+
+## Decision Outcome
+
+**Agent implementations MUST follow the tool definition, error handling, observability, and unit testing standards defined here, alongside the structural decisions in [agentme-edr-019](019-ai-agents-development-standards.md).**
+
+### Details
+
+#### 01-tool-definition-patterns
+
+Tools provided to agents MUST follow these patterns:
+
+**Tool signature:**
+
+```python
+from typing import Any, Dict
+
+def tool_name(arg1: str, arg2: int) -> Dict[str, Any]:
+    """
+    Brief description of what the tool does.
+    
+    Args:
+        arg1: Description of arg1
+        arg2: Description of arg2
+    
+    Returns:
+        Dictionary with tool execution results
+    """
+    # Tool implementation
+    return {"status": "success", "result": ...}
+```
+
+**Tool requirements:**
+
+- Tool names MUST be descriptive action verbs (e.g., `search_files`, `execute_command`, `read_document`)
+- Tool docstrings MUST clearly describe the tool's purpose, arguments, and return value (the LLM reads these)
+- Tools MUST return structured data (dictionaries or dataclasses), not bare strings or untyped values
+- Tools MUST handle errors gracefully and return error information in the result structure, not raise exceptions
+- Tools that interact with external systems MUST be placed in `adapters/connectors/` per [agentme-edr-026](026-pragmatic-hexagonal-architecture.md)
+
+**Error handling in tools:**
+
+```python
+def search_files(pattern: str, directory: str = ".") -> Dict[str, Any]:
+    """Search for files matching a glob pattern."""
+    try:
+        matches = list(Path(directory).glob(pattern))
+        return {
+            "status": "success",
+            "matches": [str(m) for m in matches],
+            "count": len(matches)
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error_message": str(e),
+            "error_type": type(e).__name__
+        }
+```
+
+#### 02-agent-error-handling-and-recovery
+
+Agents MUST implement robust error handling:
+
+**Maximum iteration limits:**
+
+- Every agent MUST have a maximum iteration limit to prevent infinite loops
+- The default maximum SHOULD be configurable and logged when reached
+- When the maximum is reached, the agent MUST return a structured failure result, not raise an exception
+
+**Tool failure handling:**
+
+- When a tool returns an error, the agent MUST be able to observe the error and decide on recovery actions
+- Tools MUST NOT raise exceptions for expected failures (network errors, file not found, etc.)
+- Agents MAY implement retry logic with exponential backoff for transient failures
+
+**Terminal states:**
+
+Agents MUST recognize and handle three terminal states:
+- **Success**: Goal achieved, task complete
+- **Failure**: Goal cannot be achieved, give up gracefully
+- **Timeout**: Maximum iterations reached, return partial results if possible
+
+#### 03-agent-observability
+
+Agent execution MUST be observable through logging and tracing:
+
+- Log each iteration of the perceive → plan → act → observe cycle with iteration number and tool selection.
+- Use structured logging (JSON) with fields: `iteration`, `tool_selected`, `tool_result_status`, `decision`.
+- For LLM calls within agents, follow [agentme-edr-018](018-ai-llm-development-standards.md) rule `03-llm-observability`.
+- When agents run as workflow nodes, MLflow tracking from the parent workflow automatically captures agent-level traces.
+- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../devops/008-common-targets.md) rule `09-ai-project-dev-targets`.
+
+**Example structured log entry:**
+
+```json
+{
+  "timestamp": "2026-06-05T10:30:45Z",
+  "agent": "FileAnalyzerAgent",
+  "iteration": 3,
+  "tool_selected": "search_files",
+  "tool_args": {"pattern": "*.py"},
+  "tool_result_status": "success",
+  "decision": "continue"
+}
+```
+
+#### 04-agent-unit-testing
+
+Agent LLM calls are external API calls and MUST be mocked in unit tests per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`.
+
+Because agents drive a tool-invocation loop — where the LLM decides which tools to call — the fake model must return **tool-call messages** followed by a final answer. Use **`GenericFakeChatModel`** for this:
+
+```python
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage
+
+def test_file_analyzer_agent_calls_search_then_stops():
+    # Iteration 1: LLM requests a tool call
+    tool_call_msg = AIMessage(
+        content="",
+        tool_calls=[{
+            "name": "search_files",
+            "args": {"pattern": "*.py", "directory": "/workspace"},
+            "id": "call_1"
+        }]
+    )
+    # Iteration 2: LLM produces a final answer after observing the tool result
+    final_msg = AIMessage(content="Found 3 Python files matching the pattern.")
+
+    fake_model = GenericFakeChatModel(messages=iter([tool_call_msg, final_msg]))
+
+    agent = FileAnalyzerAgent(model=fake_model)
+    result = agent.run(directory="/workspace")
+
+    assert result.status == "success"
+    assert "3 Python files" in result.summary
+```
+
+Agents MUST be designed so that the LLM instance is injectable (constructor parameter) to allow test doubles. See [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking` for the injectable LLM pattern.
+
+**`mock_deep_agent`**
+
+Place `mock_deep_agent` in a shared test utilities module (e.g., `tests/helpers.py`) so all test files that need it can import it from one location and mock deep_agent instances when needed.
+
+**Example usage:**
+
+```python
+from tests.helpers import mock_deep_agent
+
+def test_workflow_calls_subagent(mocker):
+    mock_deep_agent(
+        mocker,
+        "mypackage.nodes.analysis_node.create_workflow_agent",
+        output={"status": "success", "findings": ["issue A"]}
+    )
+
+    result = run_analysis_workflow(input_data)
+
+    assert result.findings == ["issue A"]
+```
+
+## References
+
+- [agentme-edr-019](019-ai-agents-development-standards.md) — Agent development standards (framework, sandbox, naming, composition, system prompts)
+- [agentme-edr-018](018-ai-llm-development-standards.md) — LLM development standards (LangChain configuration, mocking patterns)
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Hexagonal architecture (tool placement in adapters/connectors)
+- [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
+- [agentme-edr-028](028-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking

package/.xdrs/agentme/edrs/application/{020-ai-workflow-development-standards.md → 021-ai-workflow-development-standards.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-020-ai-workflow-development-standards
+name: agentme-edr-policy-021-ai-workflow-development-standards
 description: Defines the standard toolchain, framework, observability, and workflow patterns for building LangGraph workflows in Python. Use when scaffolding, reviewing, or extending AI workflow projects that orchestrate LLM calls, agents, and algorithmic nodes. For simple LLM calls see agentme-edr-018, for agentic patterns see agentme-edr-019.
 apply-to: AI workflow projects using LangGraph StateGraph built with Python
 valid-from: 2026-06-05
 ---
 
-# agentme-edr-policy-020: AI workflow development standards
+# agentme-edr-policy-021: AI workflow development standards
 
 ## Context and Problem Statement
 
@@ -33,10 +33,11 @@ Use **MLflow** for all workflow observability and evaluation:
 - **LLM-level auto-tracing:** Enable LangChain auto-tracing per [agentme-edr-018](018-ai-llm-development-standards.md) rule `03-llm-observability` by calling `mlflow.langchain.autolog()` during application startup. This captures inputs, outputs, token counts, and latency for every LangChain call within workflow nodes.
 - Log run parameters (model name, temperature, prompt version) and output metrics (accuracy, latency, token counts) using `mlflow.log_param` / `mlflow.log_metric`.
 - Run a local MLflow tracking server with `mlflow ui` to inspect runs during development. Do not require a remote MLflow server for local development.
+- The project Makefile MUST expose a `dev-mlflow` target to start the local MLflow tracking server, per [agentme-edr-008](../devops/008-common-targets.md) rule `09-ai-project-dev-targets`.
 
 #### 04-dataset-driven-accuracy-measurement
 
-Eval dataset and implementation requirements are defined in [agentme-edr-021](021-ai-eval-standards.md). Testing requirements (when evals are required, release gates) are defined in [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09-ai-project-testing-requirements`.
+Eval dataset and implementation requirements are defined in [agentme-edr-028](028-ai-eval-standards.md). Testing requirements (when evals are required, release gates) are defined in [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09-ai-project-testing-requirements`.
 
 #### 05-flow-documentation
 
@@ -100,7 +101,7 @@ lib/src/<package_name>/
 
 #### 08-workflow-evals
 
-Eval folder structure and script requirements are defined in [agentme-edr-021](021-ai-eval-standards.md).
+Eval folder structure and script requirements are defined in [agentme-edr-028](028-ai-eval-standards.md).
 
 #### 09-node-naming-conventions
 
@@ -257,5 +258,5 @@ result = graph.invoke(input_state, config={"thread_id": "session-123"})
 - [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Adapter/application layer separation that defines the project layout
 - [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
 - [agentme-edr-024](024-ml-dataset-structure.md) — ML dataset structure for eval datasets
-- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking
+- [agentme-edr-028](028-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking
 - [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)

package/.xdrs/agentme/edrs/application/025-ai-agent-xdrs-knowledge-layer.md

@@ -17,7 +17,7 @@ How should an AI agent project integrate XDRS as its runtime source of truth for
 
 **Embed XDRS documents in `lib/data/.xdrs/`, instruct the agent to consult them via `AGENTS.md`, equip the agent with sandboxed file tools, and use the deepagents framework when a local sandbox is required.**
 
-This policy MUST only be applied when the project explicitly chooses XDRS as its knowledge governance layer. It is not required by [agentme-edr-019](019-ai-agents-development-standards.md) or [agentme-edr-020](020-ai-workflow-development-standards.md) in general.
+This policy MUST only be applied when the project explicitly chooses XDRS as its knowledge governance layer. It is not required by [agentme-edr-019](019-ai-agents-development-standards.md) or [agentme-edr-021](021-ai-workflow-development-standards.md) in general.
 
 ### Details
 
@@ -59,7 +59,7 @@ Read /AGENTS.md and follow all instructions in it before proceeding.
 
 #### 02-agent-file-tools
 
-Every agent that uses the XDRS knowledge layer MUST use the file tools provided by the deepagents framework. Do not implement hand-rolled alternatives — see [agentme-edr-policy-018-ai-agent-development-standards.[09-local-sandbox]](018-ai-agent-development-standards.md) for the full sandbox and tool requirements.
+Every agent that uses the XDRS knowledge layer MUST use the file tools provided by the deepagents framework. Do not implement hand-rolled alternatives — see [agentme-edr-019 rule 02-local-sandbox](019-ai-agents-development-standards.md) for the full sandbox and tool requirements.
 
 These tools operate over two sandboxed roots (configured in rule `03-local-sandbox`):
 
@@ -72,7 +72,7 @@ These tools operate over two sandboxed roots (configured in rule `03-local-sandb
 
 #### 03-local-sandbox
 
-Follow [agentme-edr-policy-018-ai-agent-development-standards.[09-local-sandbox]](018-ai-agent-development-standards.md) for the general deepagents sandbox setup. When XDRS is in use, add the following mounts to the sandbox configuration:
+Follow [agentme-edr-019 rule 02-local-sandbox](019-ai-agents-development-standards.md) for the general deepagents sandbox setup. When XDRS is in use, add the following mounts to the sandbox configuration:
 
 | Source | Content | Deepagents sandbox path |
 |---|---|---|
@@ -92,8 +92,13 @@ agents_md = Path(temp_root) / "AGENTS.md"
 agents_md.write_text(_AGENTS_MD)  # content from xdrs-core AGENTS.md template; see rule 01-xdrs-knowledge-layer
 
 # Add these mounts alongside the base mounts from agentme-edr-019 rule 02-local-sandbox:
-xdrs_mounts = [
-    {"src": f"{data_root}/.xdrs", "dst": "/.xdrs",    "readonly": True},
-    {"src": str(agents_md),       "dst": "/AGENTS.md", "readonly": True},
-]
+# (mount_paths uses {src: dst} dict format per agentme-edr-019)
+sandbox = Sandbox(
+    mount_paths={
+        tmp_dir: "/workspace",
+        f"{data_root}/.xdrs": "/.xdrs",
+        str(agents_md): "/AGENTS.md",
+    },
+    virtual_mode=True,
+)
 ```

package/.xdrs/agentme/edrs/application/{021-ai-eval-standards.md → 028-ai-eval-standards.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-021-ai-eval-standards
+name: agentme-edr-policy-028-ai-eval-standards
 description: Defines how to structure, write, and run eval tests for AI projects — folder layout, script requirements, and MLflow tracking. Use when implementing evals for LLM, Agent, or Workflow projects. For when evals are required see agentme-edr-007 rule 09-ai-project-testing-requirements.
 apply-to: Python AI projects (LLM, Agent, or Workflow tier) that implement eval testing
 valid-from: 2026-06-05
 ---
 
-# agentme-edr-policy-021: AI eval standards
+# agentme-edr-policy-028: AI eval standards
 
 ## Context and Problem Statement
 
@@ -86,5 +86,6 @@ with mlflow.start_run():
 - [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards: when evals are required per AI tier (rule `09-ai-project-testing-requirements`) and statistical model eval targets (rule `07-statistical-models-must-have-eval-targets`)
 - [agentme-edr-018](018-ai-llm-development-standards.md) — LLM development standards: LangChain framework and observability
 - [agentme-edr-019](019-ai-agents-development-standards.md) — Agent development standards
-- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow development standards
+- [agentme-edr-021](021-ai-workflow-development-standards.md) — Workflow development standards
+
 - [agentme-edr-024](024-ml-dataset-structure.md) — ML dataset structure for eval datasets

package/.xdrs/agentme/edrs/devops/008-common-targets.md

@@ -73,7 +73,7 @@ Targets are organized into five lifecycle groups. Projects must use these names
 | Target | Purpose |
 |--------|---------|
 | `setup` | Run `mise install` and any small project bootstrap needed before normal targets work. This is the first command after checkout. |
-| `all` | Alias that runs `build`, `lint`, and `test` in sequence. Must be the default target (i.e., running `make` or the runner with no arguments invokes `all`). Used by developers as a fast pre-push check to verify the software meets minimum quality standards in one command. |
+| `all` | Alias that runs `build`, `lint`, and `test` in sequence. Must be the default target (i.e., running `make` or the runner with no arguments invokes `all`). Used by developers as a fast pre-push check to verify the software meets minimum quality standards in one command. Must only invoke targets that run **offline** — no external credentials, running servers, paid APIs, or environment-specific configuration outside the repository. |
 | `clean` | Remove all temporary or generated files created during build, lint, or test (e.g., `node_modules`, virtual environments, compiled binaries, generated files). Used both locally and in CI for a clean slate. |
 | `dev` | Run the software locally for development (e.g., start a Node.js API server, open a Jupyter notebook, launch a React dev server). May have debugging tools, verbose logging, or hot reloading features enabled. |
 | `run` | Run the software in production mode (e.g., start a compiled binary, launch a production server). No debugging or development-only features should be enabled. |
@@ -93,13 +93,13 @@ Targets are organized into five lifecycle groups. Projects must use these names
 
 | Target | Purpose |
 |--------|---------|
-| `lint` | Run **all static quality checks** outside of tests. This MUST include: code formatting validation, code style enforcement, code smell detection, static analysis, dependency audits for known CVEs, security vulnerability scans (e.g., SAST), and project/configuration structure checks. All checks must be non-destructive (read-only); fixes are handled by `lint-fix`. |
+| `lint` | Run **all static quality checks** outside of tests. This MUST include: code formatting validation, code style enforcement, code smell detection, static analysis, dependency audits for known CVEs, security vulnerability scans (e.g., SAST), and project/configuration structure checks. All checks must be non-destructive (read-only); fixes are handled by `lint-fix`. Must only invoke subtargets that run **offline** (no external credentials or services). |
 | `lint-fix` | Automatically fix linting and formatting issues where possible. || `lint-format` | *(Optional)* Check code formatting only (e.g., Prettier, gofmt, Black). |
 ##### Test group
 
 | Target | Purpose |
 |--------|---------|
-| `test` | Run **all tests** required for the project. This MUST include unit tests (with coverage enforcement — the build MUST fail if coverage thresholds are not met) and integration/end-to-end tests. Normally delegates to `test-unit` and `test-integration` in sequence. |
+| `test` | Run **all offline tests** required for the project. This MUST include unit tests (with coverage enforcement — the build MUST fail if coverage thresholds are not met) and any integration or end-to-end tests that run **offline** (no external servers, credentials, or paid APIs). Normally delegates to `test-unit` and, when offline, `test-integration` in sequence. Suffixed targets that require external dependencies must not be invoked automatically — see rule 08. |
 | `test-unit` | Run unit tests only, including coverage report generation and coverage threshold enforcement. |
 | `test-integration` | *(Optional)* Run integration and end-to-end tests only. Projects without integration tests may omit this target. |
 | `test-smoke` | *(Optional)* Run a fast, minimal subset of tests to verify the software is basically functional. Useful as a post-deploy health check. |
@@ -150,6 +150,28 @@ The prefix convention ensures developers can infer the purpose of any target wit
 
 ---
 
+#### 09-ai-project-dev-targets
+
+AI-based projects (LLM, Agent, and Workflow tiers as defined in [agentme-edr-018](../application/018-ai-llm-development-standards.md)) MUST expose a `dev-mlflow` target that starts a local MLflow tracking server for development inspection.
+
+**Example implementation:**
+
+```makefile
+dev-mlflow:
+	mise exec -- mlflow ui --host 0.0.0.0 --port 5000
+	open http://localhost:5000/
+```
+
+---
+
+#### 08-default-targets-must-only-include-offline-subtargets
+
+`make all`, `make test`, and `make lint` must include every subtarget that runs **offline** — meaning it requires no external credentials, no running servers, no paid APIs, and no environment-specific configuration outside the repository.
+
+Subtargets that require external dependencies (e.g., `test-integration` against a live database, `test-e2e` against a staging environment, `lint-api` against a remote schema registry) **must** exist as named targets so developers can invoke them explicitly, but **must not** be invoked from `all`, `test`, or `lint`.
+
+---
+
 #### 06-monorepo-usage
 
 In a monorepo, each module has its own `Makefile` with its own `build`, `lint`, `test`, and `deploy` targets scoped to that module. Parent-level Makefiles (at the application or repo root) delegate to child Makefiles in sequence. The parent Makefile should call `$(MAKE) -C <child> <target>` directly, while each child `Makefile` runs its actual tool commands through `mise exec --`.
@@ -194,6 +216,9 @@ make lint-fix
 # run the software in dev mode (may have hot reload, debug tools enabled, verbose logging etc)
 make dev
 
+# [AI projects only] start a local MLflow tracking server for development inspection
+make dev-mlflow
+
 # run the software in production mode
 make run
 

package/.xdrs/agentme/edrs/devops/027-environment-variable-configuration.md

@@ -0,0 +1,158 @@
+---
+name: agentme-edr-policy-027-environment-variable-configuration-files
+description: Defines when to use YAML config files versus .env files for configuration, how to combine them, and how .env is loaded for spawned processes. Use when setting up project configuration for any application, CLI, or library.
+apply-to: All projects that use environment variables for configuration
+valid-from: 2026-06-09
+---
+
+# agentme-edr-policy-027: Environment variable configuration files
+
+## Context and Problem Statement
+
+Projects need a consistent way to define non-secret configuration — service URLs, feature flags, port numbers, runtime modes — that varies across environments. Ad-hoc approaches (hardcoded defaults, scattered exports, application-level dotenv loaders, and flat env-var-only configs) lead to inconsistent behavior and unclear ownership of configuration.
+
+CLI tools additionally need to handle multi-attribute invocation configuration without forcing users to provide every value as a flag. At the same time, some of those values may be environment-specific and must not be committed to the repository.
+
+How should projects manage environment variable configuration and CLI invocation configuration across local development, deployment stages, and Makefiles?
+
+## Decision Outcome
+
+**Use YAML config files for CLI invocation configuration with multiple attributes; use `.env` files to supply environment variables to spawned processes and to hold uncommitted values referenced by config files. Load `.env` exclusively at process launch time — never inside application code.**
+
+Secrets (API keys, passwords, tokens) must never be placed in `.env` files. Those are handled by [agentme-edr-022](../principles/022-secrets-management.md).
+
+### Details
+
+#### 01-when-to-use-dotenv
+
+Use a `.env` file when either of the following is true:
+
+1. **Spawned process needs env vars** — the project launches a process (a deployable service, background worker, or shell script) that reads configuration from OS environment variables such as port numbers or API endpoint URLs.
+2. **Value must not be committed** — a configuration value used in a YAML config file (see rule 07) is environment-specific or sensitive enough to exclude from version control. In that case, store the value in `.env` and reference it from the YAML file using env var substitution (see rule 08).
+
+Do not use `.env` as a general-purpose configuration store when a YAML config file is the right tool (see rule 07).
+
+Example `.env` for a service with process-level env vars:
+```
+SERVER_URL=http://localhost:8080
+LOG_LEVEL=debug
+FEATURE_FLAG_NEW_UI=false
+```
+
+---
+
+#### 02-dotenv-not-committed
+
+`.env` must be listed in `.gitignore` and must never be committed to the repository. It is intended for local use in standalone projects and libraries that do not have a formal deployment pipeline.
+
+---
+
+#### 03-dotenv-example-committed
+
+A `.env.example` file must be committed alongside `.env`. It contains all the same variable names with placeholder or illustrative values — no real URLs, credentials, or server names. This file documents what configuration is expected without exposing real values.
+
+Example `.env.example`:
+```
+SERVER_URL=http://localhost:8080
+LOG_LEVEL=debug
+FEATURE_FLAG_NEW_UI=false
+```
+
+---
+
+#### 04-stage-specific-dotenv-committed
+
+Stage-specific overrides must use the naming convention `.env.[stage]` (e.g., `.env.production`, `.env.staging`, `.env.test`). These files may be committed to the repository because they carry deployment-stage configuration rather than local developer configuration. They are used during deployment pipelines where the stage is known and explicit.
+
+The generic `.env` must still not be committed. The distinction is: `.env` is for local, ad-hoc, standalone use; `.env.[stage]` is for deployment pipelines with a defined environment identity.
+
+---
+
+#### 05-load-in-makefile-before-processes
+
+When `.env` defines variables consumed by shell scripts or spawned processes, the Makefile must load and export them before invoking those processes. Use the following pattern at the top of the relevant Makefile or in a shared include:
+
+```makefile
+ifneq (,$(wildcard .env))
+  include .env
+  export
+endif
+```
+
+This ensures all variables in `.env` are available as environment variables to every child process spawned by `make`. The `ifneq` guard prevents errors when `.env` does not exist (e.g., in CI or fresh checkouts).
+
+---
+
+#### 06-no-application-level-dotenv-loading
+
+Applications must not load `.env` files directly inside their own code using dotenv libraries or equivalent mechanisms. Configuration must enter the process exclusively as OS-level environment variables, set before the process is launched (by the Makefile, a shell script, CI, or a container runtime).
+
+Prohibited patterns:
+
+```python
+# Python — disallowed
+from dotenv import load_dotenv
+load_dotenv()
+```
+
+```typescript
+// TypeScript — disallowed
+import dotenv from "dotenv";
+dotenv.config();
+```
+
+```go
+// Go — disallowed
+godotenv.Load()
+```
+
+Permitted pattern: set env vars in the Makefile (see rule 05), then launch the application normally. Inside application code, read configuration only from `os.environ`, `process.env`, or the standard OS environment API for the language.
+
+This rule prevents two parallel loading paths — OS env and file-based env — from coexisting invisibly in the same process.
+
+---
+
+#### 07-cli-adapters-use-yaml-config
+
+CLI adapters with multiple configuration attributes must use a YAML config file rather than env vars or flags for those attributes. This applies whenever configuration is nested, repetitive, or too verbose for flags alone.
+
+The CLI layer is responsible for loading and parsing the YAML file and passing the resolved values to the application layer. The application layer must not read the config file directly.
+
+Default config file discovery should follow the pattern defined in [agentme-edr-015](../application/015-cli-tool-standards.md): load `[cwd]/[tool-name].yml` by default, or an explicit path provided via `--config`.
+
+Example `myconfig.yml`:
+```yaml
+openapi_endpoint: https://example.com/openapi
+log_level: debug
+max_retries: 3
+```
+
+---
+
+#### 08-env-var-substitution-in-config-files
+
+When a YAML config file contains a value that must not be committed (such as a real endpoint URL, a username, or any other environment-specific value), that value must be expressed as an environment variable reference using `${VAR_NAME}` syntax, and the actual value must be defined in `.env`.
+
+This keeps the YAML file committable while keeping the environment-specific value out of the repository.
+
+Example:
+
+`.env` (not committed):
+```
+OPENAPI_ENDPOINT=https://real-server.example.com/openapi
+```
+
+`myconfig.yml` (committed):
+```yaml
+openapi_endpoint: ${OPENAPI_ENDPOINT}
+log_level: debug
+```
+
+The `.env` file must be loaded in the Makefile before launching the process (see rule 05) so the variable is available when the CLI or process reads the config file.
+
+## References
+
+- [agentme-edr-022](../principles/022-secrets-management.md) - Secrets must use OS keychains or cloud secret managers, not `.env` files
+- [agentme-edr-017](017-tool-execution-and-scripting.md) - Makefiles are the authoritative command entry point; rule 05 above integrates with that standard
+- [agentme-edr-008](008-common-targets.md) - Standard Makefile target names
+- [agentme-edr-015](../application/015-cli-tool-standards.md) - CLI config file discovery and CLI-to-application separation

package/.xdrs/agentme/edrs/index.md

@@ -32,9 +32,10 @@ Language and framework-specific tooling and project structure.
 - [agentme-edr-014](application/014-python-project-tooling.md) - **Python project tooling and structure** - Scaffold Python packages and CLIs with the standard layout *(includes skill: [005-create-python-project](application/skills/005-create-python-project/SKILL.md))*
 - [agentme-edr-015](application/015-cli-tool-standards.md) - **CLI tool standards** - Define command UX and behavior for CLI tools
 - [agentme-edr-018](application/018-ai-llm-development-standards.md) - **AI LLM development standards** - Standard framework (LangChain) and patterns for simple LLM calls with explicit configuration (no environment variables)
-- [agentme-edr-019](application/019-ai-agents-development-standards.md) - **AI agents development standards** - Standard framework (deepagents) and patterns for agentic tool-invocation loops
-- [agentme-edr-020](application/020-ai-workflow-development-standards.md) - **AI workflow development standards** - Standard toolchain (LangGraph), evaluation, and testing patterns for workflow projects
-- [agentme-edr-021](application/021-ai-eval-standards.md) - **AI eval standards** - Folder structure, script requirements, and MLflow tracking for eval tests across LLM, Agent, and Workflow tiers
+- [agentme-edr-019](application/019-ai-agents-development-standards.md) - **AI agents development standards** - Structural patterns for agents: framework selection, sandbox setup, naming conventions, composition, and system prompt structure
+- [agentme-edr-020](application/020-ai-agents-quality-standards.md) - **AI agents implementation quality standards** - Tool definition patterns, error handling, observability, and unit testing for agents
+- [agentme-edr-021](application/021-ai-workflow-development-standards.md) - **AI workflow development standards** - Standard toolchain (LangGraph), evaluation, and testing patterns for workflow projects
+- [agentme-edr-028](application/028-ai-eval-standards.md) - **AI eval standards** - Folder structure, script requirements, and MLflow tracking for eval tests across LLM, Agent, and Workflow tiers
 - [agentme-edr-024](application/024-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
 - [agentme-edr-025](application/025-ai-agent-xdrs-knowledge-layer.md) - **AI agent XDRS knowledge layer** - How to integrate XDRS as the runtime source of truth for policies and skills in AI agents (apply only when the project explicitly uses XDRS)
 - [agentme-edr-026](application/026-pragmatic-hexagonal-architecture.md) - **Pragmatic hexagonal architecture** - Organize application layers as External/Adapters/Application with practical coupling rules
@@ -48,6 +49,7 @@ Repository structure, build conventions, and CI/CD pipelines.
 - [agentme-edr-006](devops/006-github-pipelines.md) - **GitHub CI/CD pipelines** - Define required CI stages and workflow structure
 - [agentme-edr-008](devops/008-common-targets.md) - **Common development script names** - Reuse standard build, lint, and test target names
 - [agentme-edr-017](devops/017-tool-execution-and-scripting.md) - **Tool execution and scripting** - Run tools consistently across shells, Makefiles, and CI
+- [agentme-edr-027](devops/027-environment-variable-configuration.md) - **Environment variable configuration files** - Manage non-secret configuration with `.env` files, `.gitignore` rules, stage variants, and Makefile loading
 
 ## Governance
 

package/.xdrs/agentme/edrs/principles/007-project-quality-standards.md

@@ -145,6 +145,7 @@ Projects that are libraries or shared utilities must include an `examples/` dire
 **Root Makefile:**
 
 ```makefile
+# test-examples runs the examples offline (no external services) → include in test
 test: test-unit test-examples
 
 test-unit:
@@ -154,6 +155,8 @@ test-examples:
 	$(MAKE) -C examples
 ```
 
+If examples require live services or credentials, remove `test-examples` from the `test` dependency list and keep it as a standalone named target only. See [agentme-edr-008](../devops/008-common-targets.md) rule 08 for the full offline/online decision table.
+
 **Examples Makefile:**
 
 ```makefile
@@ -241,7 +244,7 @@ AI projects are classified into three tiers — LLM, Agent, and Workflow — def
 |---|---|---|---|
 | **LLM** ([agentme-edr-018](../application/018-ai-llm-development-standards.md)) | Not required | Not required; SHOULD be used when critical prompts are in use to measure accuracy and detect model drift | Not required |
 | **Agent** ([agentme-edr-019](../application/019-ai-agents-development-standards.md)) | Not required | Not required; MAY be used | Not required |
-| **Workflow** ([agentme-edr-020](../application/020-ai-workflow-development-standards.md)) | **Required** — see below | **Required** before every release; failed evals block release | Advised |
+| **Workflow** ([agentme-edr-021](../application/021-ai-workflow-development-standards.md)) | **Required** — see below | **Required** before every release; failed evals block release | Advised |
 
 **Workflow unit test requirements:**
 
@@ -257,4 +260,4 @@ AI projects are classified into three tiers — LLM, Agent, and Workflow — def
 - Evals MUST be executed before every release.
 - Accuracy below project-defined thresholds MUST block the release. Thresholds MUST be documented in the eval Makefile or README.
 - Evals MUST run against real LLM providers (not mocks) to capture model drift.
-- For eval folder structure and script requirements, see [agentme-edr-021](../application/021-ai-eval-standards.md).
+- For eval folder structure and script requirements, see [agentme-edr-028](../application/028-ai-eval-standards.md).

package/.xdrs/agentme/edrs/principles/022-secrets-management.md

@@ -96,6 +96,26 @@ $ make run
 # Application starts successfully
 ```
 
+#### 05a-makefile-uses-security-utility
+
+Makefile targets (e.g., `setup-secrets`) must use the macOS native `security` CLI to store and retrieve secrets from the keychain. This restricts Makefile-based secret management to macOS developer machines, which is acceptable since all contributors are expected to use macOS.
+
+Do **not** use `keyring` or other cross-platform libraries in Makefiles — `security` is simpler to invoke from shell and requires no additional dependencies.
+
+Storing a secret:
+```makefile
+security add-generic-password -a "$(USER)" -s "mymodule/api-key" -w "$(SECRET_VALUE)" -U
+```
+
+Retrieving a secret (e.g., to pass to a command):
+```makefile
+SECRET_VALUE := $(shell security find-generic-password -a "$(USER)" -s "mymodule/api-key" -w 2>/dev/null)
+```
+
+The `-U` flag updates the entry if it already exists. Use the format `<group>/<secret-id>` as the service name (`-s`) to mirror the module name and cloud secret manager ID convention defined in rule 02 and 05.
+
+In library code (Python, JS/TS, Go), continue using the cross-platform libraries defined in rule 02 (`keyring`, `cross-keychain`, `go-keyring`). The `security` utility is only for Makefile scripts.
+
 ---
 
 #### 06-never-log-or-leak-secrets

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "agentme",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "",
   "dependencies": {
-    "filedist": "^0.34.2"
+    "filedist": "^0.35.0"
   },
   "bin": "bin/filedist.js",
   "files": [