agentme 0.27.0 → 0.28.1

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

@@ -8,14 +8,8 @@ Propose changes via pull request. All changes must be verified for clarity and n
 
 Foundational standards, principles, and guidelines.
 
-- [agentme-edr-002](principles/002-coding-best-practices.md) - **Coding best practices** - Keep files small, tests nearby, and docs synchronized
-- [agentme-edr-023](principles/023-coding-abstraction-practices.md) - **Coding abstraction practices** - Define when abstractions are justified and when they must be inlined
-- [agentme-edr-004](principles/004-unit-test-requirements.md) - **Unit test requirements** - Define minimum unit-test coverage and naming expectations
-- [agentme-edr-007](principles/007-project-quality-standards.md) - **Project quality standards** - Require build, lint, and test verification before completion
-- [agentme-edr-009](principles/009-error-handling.md) - **Error handling** - Standardize explicit errors, logging, and propagation rules
 - [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy** - Promote recurring delivery lessons into reusable XDRs
 - [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure** - Organize modules consistently across supported languages
-- [agentme-edr-022](principles/022-secrets-management.md) - **Secrets management** - Handle secrets securely using native keychains and cloud secret managers
 
 ## Articles
 
@@ -27,6 +21,12 @@ Synthetic views combining agentme XDRs and skills around a specific topic.
 
 Language and framework-specific tooling and project structure.
 
+- [agentme-edr-002](application/002-coding-best-practices.md) - **Coding best practices** - Keep files small, tests nearby, and docs synchronized
+- [agentme-edr-004](application/004-unit-test-requirements.md) - **Unit test requirements** - Define minimum unit-test coverage and naming expectations
+- [agentme-edr-009](application/009-error-handling.md) - **Error handling** - Standardize explicit errors, logging, and propagation rules
+- [agentme-edr-022](application/022-secrets-management.md) - **Secrets management** - Handle secrets securely using native keychains and cloud secret managers
+- [agentme-edr-023](application/023-coding-abstraction-practices.md) - **Coding abstraction practices** - Define when abstractions are justified and when they must be inlined
+
 ### Language and framework tooling
 
 - [agentme-edr-003](application/003-javascript-project-tooling.md) - **JavaScript project tooling and structure** - Scaffold JavaScript libraries with the standard toolchain *(includes skill: [001-create-javascript-project](application/skills/001-create-javascript-project/SKILL.md))*
@@ -40,42 +40,48 @@ Language and framework-specific tooling and project structure.
 
 Standards for building LLM, Agent, and Workflow components.
 
-- [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** - 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-029](application/029-ai-workflow-naming-conventions.md) - **AI workflow naming conventions** - Node suffix/prefix roles, state type and attribute naming, judge output schema, workflow class names, and cross-element coherence rules
-- [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-040](application/040-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-041](application/041-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-042](application/042-ai-agents-quality-standards.md) - **AI agents implementation quality standards** - Tool definition patterns, error handling, observability, and unit testing for agents
+- [agentme-edr-043](application/043-ai-workflow-development-standards.md) - **AI workflow development standards** - Standard toolchain (LangGraph), evaluation, and testing patterns for workflow projects
+- [agentme-edr-044](application/044-ai-workflow-naming-conventions.md) - **AI workflow naming conventions** - Node suffix/prefix roles, state type and attribute naming, judge output schema, workflow class names, and cross-element coherence rules
+- [agentme-edr-045](application/045-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)
 
 ### AI evaluation and testing
 
 Standards for eval datasets, scripts, reports, and test type taxonomy.
 
-- [agentme-edr-030](application/030-ai-test-types-taxonomy.md) - **AI test types taxonomy** - Names AI test types (`functional`, `safety`, `smoke`, `repeatability`, `adversarial`, `fairness`, and 6 others) with group, objective, mocking constraint, and relevance, and defines the shared golden dataset entry envelope
-- [agentme-edr-028](application/028-ai-eval-core-standards.md) - **AI eval core standards** - Eval folder structure and Makefile interface; LLM-as-judge binary scoring contract applicable to all AI tiers and test types
-- [agentme-edr-031](application/031-ai-eval-script.md) - **AI eval script** - eval.py requirements: entry-first loop, --type filtering, mock_fixtures wiring, human entries, threshold enforcement, and MLflow experiment conventions
-- [agentme-edr-032](application/032-ai-eval-report-format.md) - **AI eval report format** - report-<type>.md template, Wilson score confidence interval, convergence analysis, and human-type checklist artifact
-- [agentme-edr-033](application/033-ai-eval-repeatability.md) - **AI eval repeatability** - Repeatability test type: REPEAT_COUNT loop exception, semantic-similarity and LLM-as-judge scoring, repeatability_accuracy metric, report shape, and run cadence
-- [agentme-edr-024](application/024-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
+- [agentme-edr-051](application/051-ai-eval-core-standards.md) - **AI eval core standards** - Eval folder structure and Makefile interface; LLM-as-judge binary scoring contract applicable to all AI tiers and test types
+- [agentme-edr-052](application/052-ai-test-types-taxonomy.md) - **AI test types taxonomy** - Names AI test types (`functional`, `safety`, `smoke`, `repeatability`, `adversarial`, `fairness`, `bias`, and 5 others) with group, objective, mocking constraint, and relevance, and defines the shared golden dataset entry envelope
+- [agentme-edr-053](application/053-ai-eval-script.md) - **AI eval script** - eval.py requirements: entry-first loop, --type filtering, mock_fixtures wiring, human entries, threshold enforcement, and MLflow experiment conventions
+- [agentme-edr-054](application/054-ai-eval-report-format.md) - **AI eval report format** - report-<type>.md template, Wilson score confidence interval, convergence analysis, and human-type checklist artifact
+- [agentme-edr-055](application/055-ai-eval-repeatability.md) - **AI eval repeatability** - Repeatability test type: REPEAT_COUNT loop exception, semantic-similarity and LLM-as-judge scoring, repeatability_accuracy metric, report shape, and run cadence
+
+## Data
+
+Data layer implementation and data management decisions.
+
+- [agentme-edr-050](data/050-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
 
-## Devops
+## Platform
 
-Repository structure, build conventions, and CI/CD pipelines.
+Infrastructure implementation, delivery pipeline, and developer environment decisions.
 
-- [agentme-edr-005](devops/005-monorepo-structure.md) - **Monorepo structure** - Standardize monorepo layout, tooling, and package boundaries *(includes skill: [002-monorepo-setup](devops/skills/002-monorepo-setup/SKILL.md))*
-- [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
+- [agentme-edr-005](platform/005-monorepo-structure.md) - **Monorepo structure** - Standardize monorepo layout, tooling, and package boundaries *(includes skill: [002-monorepo-setup](platform/skills/002-monorepo-setup/SKILL.md))*
+- [agentme-edr-006](platform/006-github-pipelines.md) - **GitHub CI/CD pipelines** - Define required CI stages and workflow structure
+- [agentme-edr-008](platform/008-common-targets.md) - **Common development script names** - Reuse standard build, lint, and test target names
+- [agentme-edr-017](platform/017-tool-execution-and-scripting.md) - **Tool execution and scripting** - Run tools consistently across shells, Makefiles, and CI
+- [agentme-edr-027](platform/027-environment-variable-configuration.md) - **Environment variable configuration files** - Manage non-secret configuration with `.env` files, `.gitignore` rules, stage variants, and Makefile loading
 
 ## Governance
 
 Contribution and collaboration standards shared across projects.
 
+- [agentme-edr-007](governance/007-project-quality-standards.md) - **Project quality standards** - Require build, lint, and test verification before completion
 - [agentme-edr-013](governance/013-contributing-guide-requirements.md) - **Contributing guide requirements** - Define the minimum structure for CONTRIBUTING guides
 
-## Observability
+## Operations
 
-Health, metrics, logging, and monitoring standards.
+Production behavior and operational response decisions.
 
-- [agentme-edr-011](observability/011-service-health-check-endpoint.md) - **Service health check endpoint** - Expose a standard runtime health-check endpoint for services
+- [agentme-edr-011](operations/011-service-health-check-endpoint.md) - **Service health check endpoint** - Expose a standard runtime health-check endpoint for services

package/.xdrs/agentme/edrs/{devops → platform}/005-monorepo-structure.md

@@ -24,6 +24,8 @@ Module folder responsibilities, artifact locations, and test-folder conventions
 
 #### 01-top-level-directory-layout
 
+Every monorepo MUST follow this top-level directory layout:
+
 ```
 /
 ├── .cache/               # Optional shared cache for repo-level tooling

package/.xdrs/agentme/edrs/{devops → platform}/008-common-targets.md

@@ -73,10 +73,10 @@ 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. **MUST** only invoke targets that run **offline** — no external credentials, running servers, paid APIs, or environment-specific configuration outside the repository. |
+| `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). Debugging or development-only features **SHOULD NOT** be enabled. |
+| `run` | Run the software in production mode (e.g., start a compiled binary, launch a production server). Debugging or development-only features SHOULD NOT be enabled. |
 | `update-lockfile` | Update the dependency lockfile to reflect the latest resolved versions of all dependencies. |
 
 ##### Build group
@@ -93,17 +93,17 @@ 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`. **MUST** only invoke subtargets that run **offline** (no external credentials or services). |
+| `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 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` | 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. |
-| `eval` | *(Optional)* Run **all evaluations** for the module. Used alongside `test` to measure the accuracy and performance of statistical systems such as ML models, AI agents, or noisy systems. Typically runs against a live or near-live system (similar to an integration test) and produces a performance analysis report (e.g., F1 score, Accuracy, Precision, Recall). **MUST NOT** be included in `test` or `all` — evals are opt-in because they require live dependencies and MAY be slow or costly to run. Individual evaluations **MUST** follow the prefix convention: `eval-<qualifier>` (e.g., `eval-simple`, `eval-complex`). |
+| `eval` | *(Optional)* Run **all evaluations** for the module. Used alongside `test` to measure the accuracy and performance of statistical systems such as ML models, AI agents, or noisy systems. Typically runs against a live or near-live system (similar to an integration test) and produces a performance analysis report (e.g., F1 score, Accuracy, Precision, Recall). MUST NOT be included in `test` or `all` — evals are opt-in because they require live dependencies and MAY be slow or costly to run. Individual evaluations MUST follow the prefix convention: `eval-<qualifier>` (e.g., `eval-simple`, `eval-complex`). |
 
 ##### Release group
 
@@ -119,18 +119,18 @@ Targets are organized into five lifecycle groups. Projects MUST use these names
 
 #### 04-standard-environment-variables
 
-Two environment variables have defined semantics and **MUST** be used consistently.
+Two environment variables have defined semantics and MUST be used consistently.
 
 | Variable | Purpose |
 |----------|---------|
-| `STAGE` | Identifies the runtime environment. Format: `[prefix][-variant]`. Common prefixes: `dev`, `tst`, `acc`, `prd`. Examples: `dev`, `dev-pr123`, `tst`, `prd-blue`. **MAY** be required by any target that is environment-aware (build, lint, deploy, etc.). |
+| `STAGE` | Identifies the runtime environment. Format: `[prefix][-variant]`. Common prefixes: `dev`, `tst`, `acc`, `prd`. Examples: `dev`, `dev-pr123`, `tst`, `prd-blue`. MAY be required by any target that is environment-aware (build, lint, deploy, etc.). |
 | `VERSION` | Sets the explicit version used during packaging and deployment. Used when there is no automatic version-tagging utility, or to override it. |
 
 ---
 
 #### 05-extending-targets-with-prefixes
 
-Projects **MAY** add custom targets beyond the standard set. Custom targets **MUST** be named by prefixing a standard target name with a descriptive qualifier, keeping the naming intuitive and consistent with the group it belongs to.
+Projects MAY add custom targets beyond the standard set. Custom targets MUST be named by prefixing a standard target name with a descriptive qualifier, keeping the naming intuitive and consistent with the group it belongs to.
 
 **Examples:**
 
@@ -152,7 +152,7 @@ The prefix convention ensures developers can infer the purpose of any target wit
 
 #### 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 --`.
+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 --`.
 
 ```makefile
 # root Makefile — delegates to all modules
@@ -165,7 +165,7 @@ test:
 	$(MAKE) -C module-b test
 ```
 
-A developer can run `make test` at the repo root to test everything, or `cd module-a && make test` to test a single module. Both **MUST** work.
+A developer can run `make test` at the repo root to test everything, or `cd module-a && make test` to test a single module. Both MUST work.
 
 **Reference:** See [agentme-edr-005](005-monorepo-structure.md) for the full monorepo layout convention.
 
@@ -220,15 +220,15 @@ make all
 
 #### 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.
+`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`.
+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`.
 
 ---
 
 #### 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.
+AI-based projects (LLM, Agent, and Workflow tiers as defined in [agentme-edr-040](../application/040-ai-llm-development-standards.md)) MUST expose a `dev-mlflow` target that starts a local MLflow tracking server for development inspection.
 
 **Example implementation:**
 

package/.xdrs/agentme/edrs/{devops → platform}/027-environment-variable-configuration.md

@@ -19,7 +19,7 @@ How should projects manage environment variable configuration and CLI invocation
 
 **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 — MUST NOT be loaded inside application code.**
 
-Secrets (API keys, passwords, tokens) MUST NOT be placed in `.env` files. Those are handled by [agentme-edr-022](../principles/022-secrets-management.md).
+Secrets (API keys, passwords, tokens) MUST NOT be placed in `.env` files. Those are handled by [agentme-edr-022](../application/022-secrets-management.md).
 
 ### Details
 
@@ -152,7 +152,7 @@ The `.env` file must be loaded in the Makefile before launching the process (see
 
 ## References
 
-- [agentme-edr-022](../principles/022-secrets-management.md) - Secrets must use OS keychains or cloud secret managers, not `.env` files
+- [agentme-edr-022](../application/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/principles/016-cross-language-module-structure.md

@@ -25,7 +25,7 @@ Language-specific EDRs MAY add ecosystem details, but they MUST NOT redefine the
 
 A module is the smallest independently buildable, testable, or publishable unit. It MUST live in its own folder and that folder MUST contain:
 
-- a `Makefile` following [agentme-edr-008](../devops/008-common-targets.md)
+- a `Makefile` following [agentme-edr-008](../platform/008-common-targets.md)
 - a `README.md` for the module itself
 - all configuration files needed to build, lint, test, package, or publish that module
 - its generated `dist/` directory when the module produces distributable artifacts
@@ -127,9 +127,9 @@ Benchmark tests MUST live in one of these locations:
 
 #### 08-module-makefiles-must-expose-shared-targets
 
-Every module `Makefile` MUST expose the common target names from [agentme-edr-008](../devops/008-common-targets.md). At minimum, modules MUST provide `build`, `lint`, and `test`, and SHOULD also provide `all`, `clean`, and `lint-fix` when meaningful.
+Every module `Makefile` MUST expose the common target names from [agentme-edr-008](../platform/008-common-targets.md). At minimum, modules MUST provide `build`, `lint`, and `test`, and SHOULD also provide `all`, `clean`, and `lint-fix` when meaningful.
 
 ## References
 
-- [agentme-edr-005](../devops/005-monorepo-structure.md) - Monorepo aggregation and delegation rules
-- [agentme-edr-008](../devops/008-common-targets.md) - Shared Makefile target names
+- [agentme-edr-005](../platform/005-monorepo-structure.md) - Monorepo aggregation and delegation rules
+- [agentme-edr-008](../platform/008-common-targets.md) - Shared Makefile target names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "",
   "dependencies": {
     "filedist": "^0.39.0"
@@ -18,6 +18,6 @@
     "url": "https://github.com/flaviostutz/agentme.git"
   },
   "devDependencies": {
-    "xdrs-core": "^0.38.0"
+    "xdrs-core": "^0.39.0"
   }
 }