agentme 0.15.0 → 0.16.0

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

@@ -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
 

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

@@ -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)
@@ -188,6 +189,7 @@ Agent execution MUST be observable through logging and tracing:
 - 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:**
 

package/.xdrs/agentme/edrs/application/020-ai-workflow-development-standards.md

@@ -33,6 +33,7 @@ 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
 

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

@@ -48,6 +48,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

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.16.0",
   "description": "",
   "dependencies": {
-    "filedist": "^0.34.2"
+    "filedist": "^0.35.0"
   },
   "bin": "bin/filedist.js",
   "files": [