agentme 0.24.1 → 0.25.0

package/.filedist-package.yml

@@ -1,5 +1,5 @@
 sets:
-  - package: xdrs-core@0.30.0
+  - package: xdrs-core@0.37.2
   # - package: git:https://github.com/flaviostutz/xdrs-core.git@main
     selector:
       files:

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

@@ -23,21 +23,21 @@ This keeps the user-facing command predictable while preserving a clean library
 
 #### CLI command surface
 
-- CLI tools should default to the format `[tool] [command] [options] [arguments]`.
+- CLI tools SHOULD default to the format `[tool] [command] [options] [arguments]`.
 - Example: `filedist extract --packages=test mydir`
-- A single-action tool may omit `[command]` only when adding a subcommand would be artificial and there is no meaningful action split.
-- Every CLI tool must expose:
+- A single-action tool MAY omit `[command]` only when adding a subcommand would be artificial and there is no meaningful action split.
+- Every CLI tool MUST expose:
   - `--help` on the root command
   - `--version` on the root command
   - `--verbose` on the root command and on subcommands when flags are parsed per command
-- Root `--help` output must list all available commands, key options, and usage examples. Command-specific help must describe that command's arguments and options.
+- Root `--help` output MUST list all available commands, key options, and usage examples. Command-specific help MUST describe that command's arguments and options.
 
 #### CLI to application separation
 
 - Structure the software as `cli -> app` — the CLI adapter delegates to the application layer, following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md).
-- The CLI layer must only parse arguments, load config, call the application layer, and format output.
-- Domain logic must live in the application layer and be usable without CLI globals such as `argv`, `stdout`, or process exit handlers.
-- Every feature available through the CLI must also be available through the application API.
+- The CLI layer MUST only parse arguments, load config, call the application layer, and format output.
+- Domain logic MUST live in the application layer and be usable without CLI globals such as `argv`, `stdout`, or process exit handlers.
+- Every feature available through the CLI MUST also be available through the application API.
 - Organize the application layer by action so the mapping stays direct and obvious.
   - `extract` command -> `app/extract(...)`
   - `validate` command -> `app/validate(...)`
@@ -45,49 +45,49 @@ This keeps the user-facing command predictable while preserving a clean library
 
 #### Application API shape
 
-- Each CLI action should map to a dedicated exported application function with typed inputs and outputs appropriate for the language.
-- Application APIs should accept in-memory options objects or typed parameters, not require config files or environment variables unless application-level config-file support is an explicit requirement.
+- Each CLI action SHOULD map to a dedicated exported application function with typed inputs and outputs appropriate for the language.
+- Application APIs SHOULD accept in-memory options objects or typed parameters, not require config files or environment variables unless application-level config-file support is an explicit requirement.
 - The CLI layer is responsible for translating flags, positional arguments, and config-file contents into application inputs.
-- The application layer should return explicit results and errors so the CLI can decide what to print and which exit code to use.
+- The application layer SHOULD return explicit results and errors so the CLI can decide what to print and which exit code to use.
 
 #### Configuration
 
 - Prefer flags and positional arguments for simple inputs.
 - 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 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.
+- 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 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.
 
 #### Output and progress
 
-- Standard output must show a start message when work begins and a result message when work completes successfully.
+- Standard output MUST show a start message when work begins and a result message when work completes successfully.
 - When processing is long-running or multi-stage, print concise intermediate progress messages.
-- `--verbose` must reveal more internal detail about what the tool is doing without changing the meaning of the command result.
-- Default output should stay concise and readable for humans.
-- Errors should be written to standard error with an actionable message. Stack traces or raw internal errors should stay hidden by default and may be shown in verbose mode.
+- `--verbose` MUST reveal more internal detail about what the tool is doing without changing the meaning of the command result.
+- Default output SHOULD stay concise and readable for humans.
+- Errors SHOULD be written to standard error with an actionable message. Stack traces or raw internal errors SHOULD stay hidden by default and MAY be shown in verbose mode.
 
 #### Exit behavior
 
 - Exit with `0` only when the requested action completed successfully.
 - Exit with `1` when the requested action could not be completed.
-- The application layer should surface failure as return values, result objects, or language-idiomatic errors; the CLI is responsible for converting that outcome into user-facing messages and process exit codes.
+- The application layer SHOULD surface failure as return values, result objects, or language-idiomatic errors; the CLI is responsible for converting that outcome into user-facing messages and process exit codes.
 
 #### Documentation
 
-- `README.md` must include at least 4 CLI usage examples.
-- `README.md` must include at least 2 application API examples for the same operation also available through the CLI.
-- If the tool supports config files, at least 1 README example should show config-file usage.
-- Examples must use the public command and public application API, not internal modules or private files.
+- `README.md` MUST include at least 4 CLI usage examples.
+- `README.md` MUST include at least 2 application API examples for the same operation also available through the CLI.
+- If the tool supports config files, at least 1 README example SHOULD show config-file usage.
+- Examples MUST use the public command and public application API, not internal modules or private files.
 
 #### Distribution and versioning
 
-- The implementation language is project-dependent, but the packaging and entry-point strategy must match how users are expected to run the tool.
+- The implementation language is project-dependent, but the packaging and entry-point strategy MUST match how users are expected to run the tool.
 - Choose language tooling that stays compatible with ecosystem launchers such as `npx`, `pnpm dlx`, `uvx`, or equivalent distribution commands for that ecosystem.
-- `--version` must print the same version declared in the published package or release artifact metadata.
+- `--version` MUST print the same version declared in the published package or release artifact metadata.
 - Do not hard-code a second version string that can drift from the published package version.
-- Language-specific project structure and packaging rules still apply and should be combined with this XDR, especially [agentme-edr-003](003-javascript-project-tooling.md), [agentme-edr-010](010-golang-project-tooling.md), and [agentme-edr-014](014-python-project-tooling.md).
+- Language-specific project structure and packaging rules still apply and SHOULD be combined with this XDR, especially [agentme-edr-003](003-javascript-project-tooling.md), [agentme-edr-010](010-golang-project-tooling.md), and [agentme-edr-014](014-python-project-tooling.md).
 
 ## Considered Options
 

package/.xdrs/agentme/edrs/application/024-ml-dataset-structure.md

@@ -9,7 +9,7 @@ valid-from: 2026-05-27
 
 ## Context and Problem Statement
 
-ML projects accumulate datasets of different shapes: file-paired annotations, tabular CSVs, and structured JSONL records. Without a shared layout convention, tooling and agents cannot reliably discover schema files, consume data programmatically, or understand what a dataset contains.
+ML projects accumulate datasets of different shapes: file-paired annotations, tabular CSVs, and complex per-record structures. Without a shared layout convention, tooling and agents cannot reliably discover schema files, consume data programmatically, or understand what a dataset contains.
 
 How should ML datasets be organized on disk so they are self-describing, easy to consume, and consistent across dataset types?
 
@@ -58,6 +58,8 @@ Placing the annotation file next to its source file (same name + `.json`) keeps
 
 Subdirectories inside `data/` are allowed when the number of files warrants grouping, but the `.json` sibling convention MUST be preserved at each level.
 
+Each `.json` annotation file MUST include a top-level `$schema` property whose value is the correct relative path to the dataset's root `dataset.schema.json`, accounting for subdirectory depth (e.g. `"$schema": "../dataset.schema.json"` at one level, `"../../dataset.schema.json"` at two levels). This is the standard editor-tooling convention for associating a JSON instance with its schema, and is validated by rule `06`.
+
 #### 03-tabular-datasets-must-use-csv-files-at-root
 
 Datasets composed of column-oriented tabular data MUST place CSV files at the root of the dataset folder. All tabular files MUST conform to the schema defined in `dataset.schema.json`, which MUST describe columns as named attributes with their types.
@@ -70,27 +72,40 @@ Datasets composed of column-oriented tabular data MUST place CSV files at the ro
     README.md
 ```
 
-Multiple CSV files are allowed when they represent different slices or splits of the same schema (e.g. train/test splits, subsets by source). All files in the same dataset MUST share the same column schema.
+Multiple CSV files are allowed when they represent different slices or splits of the same schema (e.g. train/test splits, subsets by source). All files in the same dataset MUST share the same column schema. Each row MUST also be validated by `make lint` per rule `06` — CSV has no `$schema` field (not applicable to that format), so only the row content is checked, not a schema pointer.
 
-#### 04-complex-structured-datasets-must-use-jsonl
+#### 04-complex-structured-datasets-must-use-per-entry-json-files
 
-Datasets with complex or heterogeneous per-record structures (e.g. LLM workflow evaluation sets, Q&A pairs, input → expected_output pairs) MUST use JSONL files (one JSON object per line) placed at the root of the dataset folder. Each line MUST conform to the schema defined in `dataset.schema.json`.
+Datasets with complex or heterogeneous per-record structures (e.g. LLM workflow evaluation sets, Q&A pairs, input → expected_output pairs) MUST use one JSON file per entry, placed inside the `data/` subfolder. Each file MUST conform to the schema defined in `dataset.schema.json`.
 
 ```
 /[name-of-dataset]/
-    simple-cases-test.jsonl
-    edge-cases-test.jsonl
-    dataset.schema.json    (schema defining the structure of each line in the JSONL files)
+    data/
+        case-001.json
+        case-002.json
+    dataset.schema.json    (schema defining the structure of each entry file)
     README.md
 ```
 
-Multiple JSONL files are allowed when they represent different splits or categories (e.g. easy vs. edge cases). All files in the same dataset MUST conform to the same line schema.
+Each entry file MUST include a top-level `$schema` property whose value is the correct relative path to the dataset's root `dataset.schema.json`, accounting for subdirectory depth (e.g. `"$schema": "../dataset.schema.json"` at one level, `"../../dataset.schema.json"` at two levels), validated by rule `06`.
+
+Subdirectories inside `data/` are allowed for grouping entries by collection source, time period, actor, or similar dimensions when the number of files warrants it. ALL files in one dataset MUST conform to the SAME `dataset.schema.json` — if a project needs a different schema for a different set of entries, that MUST be a separate dataset (its own folder, README, and `dataset.schema.json`), not multiple schemas inside one dataset.
 
 #### 05-referenced-files-must-live-in-data-folder
 
-When any dataset type (tabular, JSONL, or annotation-pair) contains references to external files as part of the data (e.g. a JSONL record that includes a file path), those referenced files MUST be stored inside the `data/` subfolder of the dataset. Paths inside data records MUST be relative to the dataset root.
+When any dataset type (tabular, per-entry JSON, or annotation-pair) contains references to external files as part of the data (e.g. an entry record that includes a file path), those referenced files MUST be stored inside the `data/` subfolder of the dataset. Paths inside data records MUST be relative to the dataset root.
+
+#### 06-datasets-must-be-lint-validated-against-schema
+
+Every dataset MUST expose a `make lint` target (in the Makefile of the project/component that owns the dataset) that validates its data against `dataset.schema.json` using the Python [`jsonschema`](https://pypi.org/project/jsonschema/) library:
+
+- Per-entry JSON files (rule `04`) and annotation-pair `.json` siblings (rule `02`) MUST each be validated against `dataset.schema.json`, and their `$schema` property MUST be present and resolve to the dataset's actual schema file.
+- CSV rows (rule `03`) MUST each be converted to a JSON object (column header → value) and validated against the same `dataset.schema.json`.
+- `make lint` MUST list every violation found across all files/rows before exiting with a non-zero status (not fail-fast on the first violation).
+- `jsonschema` MUST be declared as a normal project dependency per [agentme-edr-014](014-python-project-tooling.md); no special-casing.
 
 ## References
 
 - [JSON Schema specification](https://json-schema.org/)
-- [JSONL format](https://jsonlines.org/)
+- [jsonschema (Python library)](https://pypi.org/project/jsonschema/)
+- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and dependency conventions

package/.xdrs/agentme/edrs/application/026-pragmatic-hexagonal-architecture.md

@@ -56,6 +56,14 @@ Every application is conceptually divided into three layers:
 - Group related logic into subfolders (aggregation roots)
 - Environment variables must be read only in the bootstrap/entry-point layer of inbound adapters, converted into typed configuration objects, and passed explicitly to all other components
 
+- Data flow examples
+
+```text
+HTTP request  →  adapters/http/     →  app/create-user     →  adapters/connectors/postgres/
+CLI command   →  adapters/cli/      →  app/create-dir      →  adapters/connectors/local-fs/
+Kafka message →  adapters/kafka/    →  app/process-event   →  adapters/connectors/stripe-api/
+```
+
 #### 04-mandatory-folder-structure
 
 ```text
@@ -98,15 +106,56 @@ mysystem/
 - Trivial scripts and single-purpose tools (fewer than ~300 lines with a single I/O boundary) MAY skip this layering
 - All other projects MUST use this structure from the start
 
-#### 08-examples-of-data-flow
+#### 09-unit-testing-and-mocking-strategy
 
-```text
-HTTP request  →  adapters/http/     →  app/create-user     →  adapters/connectors/postgres/
-CLI command   →  adapters/cli/      →  app/create-dir      →  adapters/connectors/local-fs/
-Kafka message →  adapters/kafka/    →  app/process-event   →  adapters/connectors/stripe-api/
+Unit tests for the `app/` layer MUST mock outbound adapter/connector interfaces at the `app/` → `adapters/connectors/` boundary. Inject connectors as constructor parameters or function arguments so tests can substitute them without touching real databases, HTTP APIs, or external services.
+
+The connector implementations themselves SHOULD have their own unit tests that mock the underlying SDK or HTTP client.
+
+```python
+# Good — inject connector; unit test mocks it
+class OrderService:
+    def __init__(self, db: OrderRepository):
+        self.db = db
+
+def test_create_order_persists_record():
+    fake_db = FakeOrderRepository()
+    service = OrderService(db=fake_db)
+    order = service.create({"item": "widget", "qty": 2})
+    assert fake_db.find(order.id) is not None
 ```
 
+Inbound adapters (`cli/`, `http/`, `grpc/`) are entry points and do not need to be mocked — test the `app/` layer directly by injecting fakes for its outbound connectors. See rule `10` for the naming and placement convention for shared mock files.
+
+#### 10-mock-file-strategy
+
+When a mock implementation needs to be **reused across multiple tests or imported by an eval script** (e.g. `eval.py` using `mock_fixtures` from [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `02`), define it in a dedicated `_mock` file rather than inline.
+
+**When to use a `_mock` file vs inline:**
+- Single-test use → define the mock inline inside the test file (per rule `09` example; no file needed)
+- Reusable across multiple tests OR used from `eval.py` → define in a separate `_mock` file
+
+**Scope:** applies to any source file in `adapters/connectors/`, `app/`, or `shared/`. MUST NOT be used for inbound adapters (`cli/`, `http/`, `grpc/`) — those are entry points and are never mocked (rule `09`).
+
+**Naming:** insert `_mock` immediately before the file extension:
+
+| Source file | Mock file |
+|---|---|
+| `client.py` | `client_mock.py` |
+| `order_service.ts` | `order_service_mock.ts` |
+| `user_store.go` | `user_store_mock_test.go` |
+
+**Placement:** follows the project's test file placement convention per [agentme-edr-004](../principles/004-unit-test-requirements.md) rule `04`:
+- Co-located test convention (TypeScript, Go) → mock file in the same directory as the source file
+- Separate test folder convention (Python) → mock file mirrors the source path under the test folder (e.g. `lib/src/<pkg>/adapters/connectors/user-db/client.py` → `lib/tests/<pkg>/adapters/connectors/user-db/client_mock.py`)
+
+**Mock contract:**
+- MUST accept a `fixtures` parameter (constructor argument or factory function argument); the value is whatever `mock_fixtures[key]` contains from the dataset entry — its internal structure is opaque and interpreted by the mock implementation
+- MUST NOT fall back to real external calls under any circumstance — if a call cannot be satisfied from the provided fixtures, MUST raise an explicit error (never silently return `null`, `undefined`, or an empty value)
+
 ## References
 
 - [agentme-edr-016](../principles/016-cross-language-module-structure.md) — Defines the module-root structure (Makefile, dist/, .cache/) that wraps this internal layout
 - [agentme-edr-002](../principles/002-coding-best-practices.md) — File size limits and code organization practices that complement this architecture
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) — Rule `04`: test file placement convention per language (governs `_mock` file placement in rule `10`)
+- [agentme-edr-030](030-ai-test-types-taxonomy.md) — Rule `02`: `mock_fixtures` golden dataset envelope that drives `_mock` usage in eval scripts

package/.xdrs/agentme/edrs/application/028-ai-eval-standards.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Defines how to structure, write, and run eval tests for AI projects — folder layout, golden dataset, --type test-type filtering, mock_fixtures wiring, entry-first eval loop, per-type Makefile targets and reports, 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. For the test type taxonomy and mock_fixtures envelope see agentme-edr-030. For mock file naming see agentme-edr-026 rule 10.
 apply-to: Python AI projects (LLM, Agent, or Workflow tier) that implement eval testing
 valid-from: 2026-06-05
 ---
@@ -29,10 +29,10 @@ Evals are grouped first by the component being evaluated, then by the specific e
 evals/
   <component>/           # the component being evaluated (e.g., workflow-x, agent-y, model-z)
     eval-<name>/
-      dataset/           # EDR-024 compliant dataset (README.md, dataset.schema.json, data/)
+      golden_dataset/    # EDR-024 + EDR-030 compliant golden dataset (README.md, dataset.schema.json, data/)
       eval.py            # evaluation script
-      report.md          # generated report (overwritten on each run — see rule 03)
-      Makefile           # eval and run targets
+      report-<type>.md   # generated report, one per evaluated test type (overwritten on each run — see rule 03)
+      Makefile           # lint, eval, run, and eval-<type> targets
     eval-<name2>/
       ...
   <component2>/
@@ -41,73 +41,126 @@ evals/
 
 `<component>` MUST match the name of the component under evaluation and use lowercase hyphen-separated words (e.g., `workflow-document-review`, `agent-support`, `model-classifier`).
 
-`<name>` identifies the specific evaluation scenario using lowercase hyphen-separated words (e.g., `eval-basic`, `eval-complex`, `eval-edge-cases`, `eval-bias-test`).
+`<name>` identifies the specific evaluation scenario using lowercase hyphen-separated words (e.g., `eval-basic`, `eval-complex`, `eval-edge-cases`). A scenario's `golden_dataset` MAY mix multiple test types across its entries: label each entry with its applicable `test_types` ([agentme-edr-030](030-ai-test-types-taxonomy.md) rule `04`) and use the `eval-<type>` targets below to run one type at a time.
 
-The `dataset/` subfolder MUST be a valid [agentme-edr-024](024-ml-dataset-structure.md) dataset — it MUST include `README.md` and `dataset.schema.json` at its root. For input/output pairs, use JSONL files per `agentme-edr-024.04-complex-structured-datasets-must-use-jsonl`.
+The `golden_dataset/` subfolder MUST be a valid [agentme-edr-024](024-ml-dataset-structure.md) dataset (`README.md`, `dataset.schema.json`, one JSON file per entry under `data/` per rule `04-complex-structured-datasets-must-use-per-entry-json-files`, lint-validated per rule `06`) whose entries follow the golden dataset envelope defined in [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `02`.
 
-Each `evals/<component>/eval-<name>/Makefile` MUST define:
+Each `evals/<component>/eval-<name>/Makefile` MUST declare a `TEST_TYPES` variable listing the `test_types` values present in its golden dataset, and define:
 
 | Target | Behaviour |
 |---|---|
-| `eval` | Runs the eval with threshold enforcement; exits non-zero on failure (CI-safe) |
-| `run` | Runs the eval without threshold enforcement (exploration / debugging) |
+| `lint` | Validates every `golden_dataset/data/*.json` file against `golden_dataset/dataset.schema.json` per [agentme-edr-024](024-ml-dataset-structure.md) rule `06` |
+| `eval` | Depends on `lint`; runs `eval.py --type=all` with threshold enforcement; exits non-zero on failure (CI-safe) |
+| `run` | Depends on `lint`; runs `eval.py --type=all` without threshold enforcement (exploration / debugging) |
+| `eval-<type>` | Depends on `lint`; runs `eval.py --type=<type>` for one declared test type, following [agentme-edr-008](../devops/008-common-targets.md) rule `03`'s `eval-<qualifier>` convention |
 
-The module root Makefile MUST expose a `make eval` target that delegates to `eval` in every `evals/<component>/eval-<name>/Makefile`:
+```makefile
+TEST_TYPES := smoke functional safety
+
+lint:
+	mise exec -- uv run --project . python lint_dataset.py golden_dataset/
+
+eval: lint
+	mise exec -- uv run --project . python eval.py --type=all
+
+run: lint
+	mise exec -- uv run --project . python eval.py --type=all --no-threshold
+
+eval-%: lint
+	mise exec -- uv run --project . python eval.py --type=$*
+```
+
+The module root Makefile MUST expose `make eval` and `make lint` targets that delegate to `eval` and `lint` respectively in every `evals/<component>/eval-<name>/Makefile`:
 
 ```makefile
 eval:
 	$(MAKE) -C evals/workflow-document-review/eval-basic eval
 	$(MAKE) -C evals/workflow-document-review/eval-complex eval
+
+lint:
+	$(MAKE) -C evals/workflow-document-review/eval-basic lint
+	$(MAKE) -C evals/workflow-document-review/eval-complex lint
 ```
 
 #### 02-eval-script-requirements
 
 Each `eval.py` script MUST:
 
-- Load the dataset from `dataset/` in the same eval folder, following [agentme-edr-024](024-ml-dataset-structure.md). For input/output pairs, use the JSONL format per `agentme-edr-024.04-complex-structured-datasets-must-use-jsonl`.
-- Run every input through the live component against **real LLM providers** (not mocked responses), to capture model drift.
-- Log per-sample and aggregate metrics to an MLflow experiment that runs **locally** — a remote MLflow server MUST NOT be required.
-- Compare outputs to expected values using project-defined quality thresholds. Thresholds MUST be declared explicitly (e.g., in a Makefile variable or README).
-- Write `report.md` in the same folder per rule `03-eval-report-file`.
-- Exit with a non-zero status when any metric falls below its defined threshold, consistent with [agentme-edr-007](../principles/007-project-quality-standards.md) rule `07-statistical-models-must-have-eval-targets`.
+- Load the golden dataset from `golden_dataset/` in the same eval folder, following [agentme-edr-024](024-ml-dataset-structure.md) and the entry envelope in [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `02` (one JSON file per entry, `test_types` array, `input`, `expected_output`, optional `mock_fixtures`).
+- Accept a required `--type=<test_type>|all` CLI argument and filter entries whose `test_types` array contains the requested value; `--type=all` includes every entry.
+- Iterate **entry-first**: for each entry in the filtered set, invoke the real component exactly once; then score that single `actual_output` for every `test_types` value the entry carries that falls within the current `--type` scope — never invoke the component more than once per entry per run.
+- When an entry contains `mock_fixtures` ([agentme-edr-030](030-ai-test-types-taxonomy.md) rule `02`), configure each named mock adapter with its fixture data BEFORE invoking the component for that entry. Each entry MUST use fresh mock instances so fixture state does not bleed across entries. `mock_fixtures` applies to all test types including `human`. `mock_fixtures` MUST NOT configure LLM adapters — the LLM call MUST always be real (see [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `03`). How mock adapters are discovered and instantiated is left to the project; see [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) rule `10` for the `_mock` file naming and placement convention.
+- Run every component invocation against **real LLM providers** (not mocked responses), to capture model drift.
+- For `human` entries: invoke the component to capture `actual_output`, export each entry's `input`, `expected_output.human_test` instructions, and `actual_output` into a manual-review checklist (`report-human.md`). MUST NOT invoke an automated scorer and MUST NOT enforce a pass/fail threshold for it. Other `test_types` on the same entry (e.g. `functional`) are still scored automatically.
+- After all entries are processed, compute aggregate metrics per test type, log them to a local MLflow experiment (see rule `04`), write one `report-<type>.md` per evaluated test type (rule `03`), and exit with a non-zero status when any metric falls below its defined threshold per [agentme-edr-007](../principles/007-project-quality-standards.md) rule `07-statistical-models-must-have-eval-targets`. The `human` type has no threshold and does not trigger a non-zero exit.
+- Compare outputs to expected values using project-defined quality thresholds per test type. Thresholds MUST be declared explicitly (e.g., in a Makefile variable or README) — this Policy does not mandate which test types a project must threshold or what value to use (see [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `06`).
 
 **Example:**
 
 ```python
+import argparse
+from collections import defaultdict
 import mlflow
 from my_package.app.workflows.document_review_workflow.graph import graph
 
-EVAL_MIN_ACCURACY = 0.85
+EVAL_MIN_ACCURACY = {"functional": 0.85, "smoke": 0.85}
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--type", required=True)
+args = parser.parse_args()
 
-with mlflow.start_run() as run:
-    results = []
-    for sample in load_dataset("dataset/"):
-        output = graph.invoke({"document": sample["input"]})
-        results.append(output["label"] == sample["expected_label"])
+entries = load_golden_dataset("golden_dataset/", test_type=args.type)  # "all" loads every entry
+resolved_types = resolve_types(args.type, entries)
 
-    accuracy = sum(results) / len(results)
-    mlflow.log_metric("accuracy", accuracy)
+mlflow.set_experiment("document-review/eval-basic")
 
-    write_eval_report(run, results, thresholds={"accuracy": EVAL_MIN_ACCURACY})
+with mlflow.start_run():
+    mlflow.set_tag("test_types", ",".join(sorted(resolved_types)))
 
-    if accuracy < EVAL_MIN_ACCURACY:
-        raise SystemExit(f"Eval failed: accuracy {accuracy:.2f} < {EVAL_MIN_ACCURACY}")
+    results = defaultdict(list)
+
+    # Entry-first loop: invoke each entry exactly once
+    for entry in entries:
+        # Configure mock adapters from mock_fixtures before invocation
+        # (implementation left to the project — see agentme-edr-026 rule 10)
+        if entry.get("mock_fixtures"):
+            configure_mocks(entry["mock_fixtures"])  # project-defined helper
+
+        actual_output = invoke_component(entry, graph)
+
+        for test_type in [t for t in entry["test_types"] if t in resolved_types]:
+            if test_type == "human":
+                export_human_review(entry, actual_output)
+                continue
+            results[test_type].append(score(test_type, actual_output, entry["expected_output"]))
+
+    # Aggregate, report, and enforce thresholds per test type
+    for test_type in resolved_types:
+        if test_type == "human":
+            continue
+
+        accuracy = sum(results[test_type]) / len(results[test_type])
+        mlflow.log_metric(f"{test_type}_accuracy", accuracy)
+        write_eval_report(test_type, results[test_type], thresholds={"accuracy": EVAL_MIN_ACCURACY[test_type]})
+
+        if accuracy < EVAL_MIN_ACCURACY[test_type]:
+            raise SystemExit(f"Eval failed: {test_type} accuracy {accuracy:.2f} < {EVAL_MIN_ACCURACY[test_type]}")
 ```
 
 #### 03-eval-report-file
 
-Each eval script MUST produce `report.md` in the same `evals/<component>/eval-<name>/` folder and overwrite it on every run.
+Each eval script MUST produce one `report-<type>.md` per evaluated test type in the same `evals/<component>/eval-<name>/` folder and overwrite each on every run — only the types included in the current `--type` invocation are (re)written; report files for other types are left untouched. The `human` type does not produce a metrics report (see below).
 
 **Generation constraint:** The report MUST be produced programmatically, reading raw metric values directly from MLflow. No LLM or generative model may write, summarize, or paraphrase any section of the report, to prevent hallucinated metric values.
 
 The report MUST follow this template:
 
 ```markdown
-# Eval Report: <name>
+# Eval Report: <name> — <type>
 
 **Date:** <ISO date>
-**Dataset:** dataset/
-**Script:** eval.py
+**Dataset:** golden_dataset/
+**Script:** eval.py --type=<type>
 **Thresholds:** accuracy ≥ <value>, F1 ≥ <value>
 
 ## Overall Results
@@ -142,14 +195,14 @@ $$\frac{\hat{p} + \frac{z^2}{2n} \pm z\sqrt{\frac{\hat{p}(1-\hat{p})}{n} + \frac
 
 Where $\hat{p}$ is observed accuracy and $n$ is sample count. Accuracy and F1 are required; precision and recall are recommended.
 
-**Filled-in example** (`evals/workflow-document-review/eval-basic/report.md` for a document review workflow):
+**Filled-in example** (`evals/workflow-document-review/eval-basic/report-functional.md` for a document review workflow):
 
 ```markdown
-# Eval Report: eval-basic
+# Eval Report: eval-basic — functional
 
 **Date:** 2026-06-12
-**Dataset:** dataset/
-**Script:** eval.py
+**Dataset:** golden_dataset/
+**Script:** eval.py --type=functional
 **Thresholds:** accuracy ≥ 0.85, F1 ≥ 0.80
 
 ## Overall Results
@@ -169,7 +222,7 @@ Where $\hat{p}$ is observed accuracy and $n$ is sample count. Accuracy and F1 ar
 ## Per-item Results
 
 | ID  | Input Summary                       | Expected | Actual   | Correct |
-|-----|-------------------------------------|----------|----------|---------|
+|-----|--------------------------------------|----------|----------|---------|
 | 001 | Contract renewal, 3 pages, standard | approve  | approve  | ✓       |
 | 002 | NDA with unusual liability clause   | escalate | escalate | ✓       |
 | 003 | Vendor invoice, missing PO number   | reject   | reject   | ✓       |
@@ -179,20 +232,26 @@ Where $\hat{p}$ is observed accuracy and $n$ is sample count. Accuracy and F1 ar
 ## Notes
 
 - Sample 005 misclassified: redlined IP clause not flagged as escalation trigger. Possible model drift.
-- MLflow run: experiment `workflow-document-review/eval-basic` — view with `mlflow ui`
+- MLflow run: experiment `workflow-document-review/eval-basic`, tag `test_types=functional` — view with `mlflow ui`
 ```
 
+**`human` type artifact:** instead of `report-human.md` with metrics, `--type=human` produces a checklist artifact (still named `report-human.md`) listing, per entry, its `input`, `expected_output.human_test` instructions, and the captured `actual_output` — with no Overall Results table, threshold, or PASS/FAIL section, since this type is never auto-scored.
+
 #### 04-eval-mlflow-unique-port
 
 Each `evals/<component>/eval-<name>/Makefile` MUST start its MLflow tracking server on a **unique port** to prevent conflicts when multiple eval Makefiles are run concurrently or in parallel (e.g., in CI or across multiple terminal sessions).
 
-Ports MUST be statically assigned per eval scenario and MUST NOT reuse the default `5000` port (reserved for `dev-mlflow` per [agentme-edr-008](../devops/008-common-targets.md) rule `09-ai-project-dev-targets`). Assign ports starting at `5100` and incrementing by 1 for each additional eval scenario across the entire project.
+Ports MUST be statically assigned per eval scenario (not per test type) and MUST NOT reuse the default `5000` port (reserved for `dev-mlflow` per [agentme-edr-008](../devops/008-common-targets.md) rule `09-ai-project-dev-targets`). Assign ports starting at `5100` and incrementing by 1 for each additional eval scenario across the entire project.
+
+The MLflow **experiment** is scoped to the eval scenario: `<component>/<eval-name>` (e.g. `document-review/eval-basic`). Each `mlflow.start_run()` call MUST set a `test_types` tag listing the test types evaluated in that invocation (comma-separated, e.g. `"functional,smoke"` for `--type=all`, `"smoke"` for `--type=smoke`). A remote MLflow server MUST NOT be required — all tracking is local.
 
 ## References
 
 - [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-030](030-ai-test-types-taxonomy.md) — AI test types taxonomy: `test_types` enum, golden dataset entry envelope (including `mock_fixtures`), and mocking constraints per type
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Rule `10`: `_mock` file naming and placement convention for mock adapters used in `mock_fixtures`
 - [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-021](021-ai-workflow-development-standards.md) — Workflow development standards
-
-- [agentme-edr-024](024-ml-dataset-structure.md) — ML dataset structure for eval datasets
+- [agentme-edr-024](024-ml-dataset-structure.md) — ML dataset structure, per-entry JSON format, and schema-lint validation for golden datasets
+- [agentme-edr-008](../devops/008-common-targets.md) — `eval-<qualifier>` Makefile convention (rule `03`) and Mise tool-execution flow (rule `02`)

package/.xdrs/agentme/edrs/application/030-ai-test-types-taxonomy.md

@@ -0,0 +1,96 @@
+---
+name: agentme-edr-policy-030-ai-test-types-taxonomy
+description: Names AI-application test types (safety, responsible-AI, quality-eval, prompt, code-level) with their group, objective, mocking constraint, and relevance, and defines the shared "golden dataset" entry envelope that agentme-edr-028's eval tooling filters by test_types. Use when deciding which AI test types to implement or when authoring a golden dataset entry.
+apply-to: AI projects (LLM, Agent, or Workflow tier) implementing AI-specific test types beyond generic code-level unit/integration tests
+valid-from: 2026-07-05
+---
+
+# agentme-edr-policy-030: AI test types taxonomy
+
+## Context and Problem Statement
+
+AI components need test types beyond generic unit/integration tests (safety, fairness, groundedness, functional accuracy, etc.). Which test types should be named, and how should their datasets and eval tooling work?
+
+## Decision Outcome
+
+**Adopt a named taxonomy of AI test types plus a shared "golden dataset" entry envelope that agentme-edr-028's eval tooling filters by `test_types`.**
+
+Each test type is named with its group, objective, mocking constraint, applicability, and relevance; every golden dataset entry is labeled with the test types it applies to.
+
+### Details
+
+#### 01-golden-dataset-concept
+
+A **golden dataset** comprises all eval case entries used to test an AI component (LLM, Agent, or Workflow tier); each entry is labeled with the `test_types` (rule `04`) it applies to. It is the dataset consumed by [agentme-edr-028](028-ai-eval-standards.md) evals and stored as one JSON file per entry per [agentme-edr-024](024-ml-dataset-structure.md) rule `04`, at `evals/<component>/eval-<name>/golden_dataset/`.
+
+#### 02-golden-dataset-entry-envelope
+
+Every golden dataset entry (a JSON file in `golden_dataset/data/`) MUST have this shape, in addition to any project-specific fields:
+
+```json
+{
+  "$schema": "../dataset.schema.json",
+  "test_types": ["functional"],
+  "input": "...",
+  "expected_output": "...",
+  "mock_fixtures": {
+    "system_y": [{"123": {"name": "Flavio"}}, {"456": {"name": "Andrew"}}]
+  }
+}
+```
+
+- `test_types` — array, values MUST come from rule `04`'s enum, MUST contain at least one value. An entry MAY carry more than one value additively (e.g. `["functional", "smoke", "human"]`) — no test type excludes another.
+- `input` — for Prompt-tier components, a raw prompt string or the prompt template's input parameters object; for Agent/Workflow-tier components, the input attributes object passed to the component.
+- `expected_output` — the fields used to score the entry under each of its automated `test_types`: output attributes for an LLM-as-judge rubric, a target for vector-similarity scoring, or exact attribute values for strict comparison. When `human` is one of the entry's `test_types`, `expected_output` MUST additionally include a `human_test` string field with manual-verification instructions (e.g. `"check for ethical issues, verify record change in system X"`) — this supplements, and never replaces, the entry's automated scoring fields.
+- `mock_fixtures` — optional object; keys identify the adapter or external system to mock (SHOULD match the connector folder name under `adapters/connectors/<name>` for readability, though not enforced), values are any valid JSON interpreted by the mock implementation. When present, eval.py MUST configure each named mock adapter with its fixture data BEFORE invoking the component for that entry; each entry MUST use fresh mock instances to prevent state from bleeding across entries. `mock_fixtures` applies to all `test_types` including `human` — the component is still invoked for human entries to capture `actual_output`. `mock_fixtures` MUST NOT include keys for LLM adapters: all golden dataset test types are rated `mocks disallowed for LLM calls` (rule `03`), so the LLM call MUST always be real; LLM provider mocking belongs exclusively to unit tests via [agentme-edr-018](018-ai-llm-development-standards.md) rule `04`. See [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) rule `10` for the `_mock` file naming and placement convention.
+- The dataset's `dataset.schema.json` MUST require `test_types`, `input`, and `expected_output`, and SHOULD declare `mock_fixtures` as optional (`"type": "object", "additionalProperties": {}`), per [agentme-edr-024](024-ml-dataset-structure.md) rule `04`.
+
+#### 03-mocks-allowed-values
+
+The taxonomy in rule `05` rates each test type using one of three values:
+
+| Value | Meaning |
+|---|---|
+| `mocks allowed` | Fully offline; fakes may replace every dependency (e.g. `FakeListChatModel` per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04`). |
+| `mocks disallowed` | No mocking of any dependency — real external systems required. |
+| `mocks disallowed for LLM calls` | Tools and other external/dependency calls MAY be mocked; only the LLM call itself MUST be real for the test to be meaningful. |
+
+#### 04-test-types-enum
+
+A golden dataset entry's `test_types` array MUST only use these values: `safety`, `adversarial`, `fairness`, `bias`, `robustness`, `explainability`, `groundedness`, `functional`, `prompt`, `smoke`, `human`. These correspond to the dataset-driven rows of rule `05`. **Unit test** and **Integration test** (the two Code-level rows) are NOT part of this enum — they have no golden dataset entries and remain governed entirely by [agentme-edr-004](../principles/004-unit-test-requirements.md) and [agentme-edr-007](../principles/007-project-quality-standards.md) rule `08`.
+
+#### 05-test-type-taxonomy
+
+| Test Type Name | Group | Test Objective | Mocks Allowed | When to Apply | Relevance – Business | Relevance – Development Team | Priority (1-5) |
+|---|---|---|---|---|---|---|---|
+| Safety/content eval | Safety & adversarial | Detect harmful, biased, or policy-violating output | mocks disallowed for LLM calls | Any user-facing release | Avoids reputational harm; acceptable-use compliance | Automated content gate before merge/release | 5 |
+| Adversarial/red-team test | Safety & adversarial | Probe for prompt injection, jailbreaks, unsafe tool use | mocks disallowed for LLM calls | System exposes tool-invocation or agent loops | Reduces security-incident/breach liability | Finds exploitable tool-loop paths before attackers do | 5 |
+| Fairness test | Responsible AI | Verify equitable outcomes across user groups | mocks disallowed for LLM calls | Output affects decisions about individuals/groups | Regulatory requirement; protects equitable access | Surfaces uneven outcomes before release | 4 |
+| Bias test | Responsible AI | Detect skewed or stereotyped associations | mocks disallowed for LLM calls | User-facing content generation | Lowers legal/reputational exposure | Catches bias introduced by data/prompts/fine-tuning | 3 |
+| Robustness test | Responsible AI | Verify stable behavior under noisy/out-of-distribution input | mocks disallowed for LLM calls | Inputs come from untrusted/variable sources | Protects reliability/SLAs | Confirms graceful degradation, guides input validation | 3 |
+| Explainability test | Responsible AI | Verify output is justifiable with a faithful rationale | mocks disallowed for LLM calls | Output must be justified to users/auditors/regulators | Required for auditability; builds user trust | Gives rationale trace for debugging wrong answers | 2 |
+| Groundedness (RAG) eval | Quality eval | Verify the answer is supported by retrieved context | mocks disallowed for LLM calls | System uses retrieval-augmented generation | Avoids confidently-wrong answers reaching customers | Pinpoints retrieval/prompt bugs | 4 |
+| Human evaluation | Quality eval | Manually verify aspects automated scoring can't (ethics, side effects, external state) | mocks disallowed for LLM calls | Before major releases; periodic spot-check | Defensible, human-reviewed sign-off | Catches what automated metrics miss | 3 |
+| Functional eval (golden-dataset accuracy / LLM-as-judge) | Quality eval | Measure output correctness against the golden dataset | mocks disallowed for LLM calls | Required before every Workflow release ([agentme-edr-007](../principles/007-project-quality-standards.md) rule `09`); advised elsewhere | Auditable evidence of business correctness before release | Detects regressions from model/provider/prompt changes | 5 |
+| Smoke test | Quality eval | Fast pass/fail check on a small, critical subset before running fuller suites | mocks disallowed for LLM calls | Every commit/PR, before functional/responsible-AI evals run | Cheap early warning before slower evals run | Fast, cheap feedback loop | 4 |
+| Prompt regression test | Prompt/LLM | Detect behavior change when a prompt or model version changes | mocks disallowed for LLM calls | Whenever a prompt template or model version changes | Prevents shipping a worse experience via a "small" tweak | Fast check on every prompt edit | 3 |
+| Integration test | Code-level | Verify real interaction with external systems | mocks disallowed | Component depends on external systems | Reduces production outages from integration mismatches | Catches wiring bugs unit tests can't see | 2 |
+| Unit test (offline, mocked) | Code-level | Verify deterministic logic in isolation, offline | mocks allowed | Required for Workflow tier every commit ([agentme-edr-007](../principles/007-project-quality-standards.md) rule `09`) | Lowest-cost point to catch defects | Fastest, fully offline feedback on every commit | 5 |
+
+#### 06-priority-and-relevance-are-descriptive-only
+
+Priority, Relevance, and When to Apply in rule `05` are guidance for prioritization conversations — they do NOT mandate which test types a project must implement, nor their thresholds. [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09` remains the only tier-level testing requirement in force (Workflow unit tests + functional evals). Once a project chooses to implement and threshold a test type, [agentme-edr-028](028-ai-eval-standards.md) rule `02`'s failing-threshold behavior applies uniformly, regardless of this table's priority rating — a project may enforce fairness at 70% and functional at 90%, or skip fairness entirely; that choice is a project/business decision, not one this Policy makes.
+
+#### 07-smoke-is-distinct-from-test-smoke
+
+The `smoke` test type (surfaced as the `eval-smoke` Makefile target, a fast subset of the golden-dataset functional eval) is a different concept from [agentme-edr-008](../devops/008-common-targets.md)'s existing `test-smoke` target (a fast subset of code-level tests). Both may exist in the same project; do not conflate them.
+
+## References
+
+- [agentme-edr-024](024-ml-dataset-structure.md) — Golden dataset file layout, per-entry JSON format, `$schema` pointer, and schema-lint validation
+- [agentme-edr-028](028-ai-eval-standards.md) — Eval folder structure, `--type` filtering, per-type Makefile targets, and per-type reports that consume this taxonomy
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Rule `10`: `_mock` file naming and placement convention for mock adapters referenced by `mock_fixtures`
+- [agentme-edr-007](../principles/007-project-quality-standards.md) — Rule `09` tier-level testing requirements (the only mandated AI testing baseline)
+- [agentme-edr-008](../devops/008-common-targets.md) — Rule `03` `eval-<qualifier>` Makefile convention; rule `03`'s `test-smoke` (distinguished in rule `07`)
+- [agentme-edr-018](018-ai-llm-development-standards.md) — LLM tier definition and mocking utilities referenced by the `mocks allowed` value
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) — Unit test requirements underlying the Code-level rows

package/.xdrs/agentme/edrs/devops/005-monorepo-structure.md

@@ -57,8 +57,6 @@ Module folder responsibilities, artifact locations, and test-folder conventions
 - **MUST** contain a `README.md` with: purpose, architecture overview, how to build, and how to run.
 - **MAY** contain `examples/`, `tests_integration/`, and `tests_benchmark/` when those artifacts apply to multiple modules inside the application.
 
-*Why:* Isolating applications prevents implicit coupling and makes the `shared/` boundary explicit and intentional.
-
 #### 03-module-folders
 
 - A module is a subfolder inside an application that is independently compilable and produces a build artifact.
@@ -87,8 +85,6 @@ Module Makefiles **SHOULD** also provide `lint-fix` and `install` when the under
 The root `Makefile` **MUST** also define a `setup` target that guides a new contributor to prepare their machine.
 The root `setup` target **MUST** run `mise install` and any small repository bootstrap required before routine targets work.
 
-*Why:* Makefiles provide a universal, stack-agnostic entry point regardless of programming language.
-
 #### 06-mise-for-tooling-management
 
 - [Mise](https://mise.jdx.dev/) **MUST** be used to pin all tool versions (compilers, runtimes, CLI tools).
@@ -100,8 +96,6 @@ The root `setup` target **MUST** run `mise install` and any small repository boo
 - If a required tool is missing, the first remediation step **MUST** be to update `.mise.toml` or run `mise install`, not to install ad-hoc global tools with language-specific installers such as `go install`, `npm install -g`, `pip install --user`, or `cargo install`.
 - Root and module `Makefile` targets **MUST** work when invoked as plain `make <target>` after `make setup`.
 
-*Why:* Eliminates "works on my machine" build failures by ensuring identical tool versions across all environments.
-
 #### 07-root-readme
 
 The root `README.md` **MUST** include: overview, machine setup, quickstart, and a repository map.
@@ -116,8 +110,6 @@ All releases **MUST** be tagged using the format `<module-name>/<semver>` (e.g.,
 
 `<module-name>` is preferably the path-like identifier of the module being released. A custom name is allowed but the folder name is strongly preferred.
 
-*Why:* Namespacing tags by module prevents collisions and makes it easy to filter release history when multiple modules release independently.
-
 ---
 
 #### 11-summary-of-requirements

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

@@ -15,7 +15,7 @@ What standard set of Makefile target names and execution rules should projects a
 
 ## Decision Outcome
 
-**Every project must expose its development actions through a root `Makefile` using a defined set of standardized target names. Target implementation and tool-execution rules follow [agentme-edr-017](017-tool-execution-and-scripting.md), which requires `mise exec --` before routine tool commands.**
+**Every project MUST expose its development actions through a root `Makefile` using a defined set of standardized target names. Target implementation and tool-execution rules follow [agentme-edr-017](017-tool-execution-and-scripting.md), which requires `mise exec --` before routine tool commands.**
 
 Standardizing both the target names and the execution chain removes per-project guesswork, makes CI pipelines reusable, and keeps tooling behavior visible in one place.
 
@@ -23,18 +23,18 @@ Standardizing both the target names and the execution chain removes per-project
 
 #### 01-every-project-must-have-root-makefile
 
-The project root must contain a single authoritative `Makefile` that exposes the standard target names defined in rule 3. Developers and CI pipelines must invoke routine actions through this `Makefile`, never by calling underlying tools directly in documentation, CI, or daily workflow commands.
+The project root **MUST** contain a single authoritative `Makefile` that exposes the standard target names defined in rule 3. Developers and CI pipelines **MUST** invoke routine actions through this `Makefile`, **NEVER** by calling underlying tools directly in documentation, CI, or daily workflow commands.
 
 `make <target>` is the shared contract across projects and languages.
 
-- The root `Makefile` must be the entry point for both developers and pipelines.
-- The root `Makefile` must expose at minimum the common targets defined in this XDR.
-- Reverse-compatibility wrappers are allowed when an ecosystem expects them, but they must stay trivial.
+- The root `Makefile` **MUST** be the entry point for both developers and pipelines.
+- The root `Makefile` **MUST** expose at minimum the common targets defined in this XDR.
+- Reverse-compatibility wrappers are allowed when an ecosystem expects them, but they **MUST** stay trivial.
 	- Allowed: `package.json` script `"test": "make test"`
 	- Not allowed: `make test` -> `npm run test` -> tool command
-- Project logic must not live in npm scripts, Mise tasks, shell wrappers, or other secondary runners when the same logic belongs in the `Makefile`.
+- Project logic **MUST NOT** live in npm scripts, Mise tasks, shell wrappers, or other secondary runners when the same logic belongs in the `Makefile`.
 
-*Why:* The project entry point must stay language-agnostic and obvious. A developer should be able to inspect the `Makefile` and immediately see which real tool commands will run.
+*Why:* The project entry point **MUST** stay language-agnostic and obvious. A developer **SHOULD** be able to inspect the `Makefile` and immediately see which real tool commands will run.
 
 #### 02-makefile-recipes-must-use-mise
 
@@ -47,10 +47,10 @@ make <target>
 			-> explicit tool command
 ```
 
-- The `setup` target must run `mise install` and any small project-specific bootstrap needed before normal targets work.
-- Routine targets such as `build`, `lint`, `test`, `run`, and `publish` must be invoked as `make <target>` by both contributors and CI.
-- Each Makefile recipe must call the real underlying command through `mise exec --`, following [agentme-edr-017](017-tool-execution-and-scripting.md).
-- Makefile recipes must not add extra script layers such as `npm run`, `pnpm run`, `yarn run`, `mise run`, `mise tasks`, or shell aliases when those layers only forward to another command.
+- The `setup` target **MUST** run `mise install` and any small project-specific bootstrap needed before normal targets work.
+- Routine targets such as `build`, `lint`, `test`, `run`, and `publish` **MUST** be invoked as `make <target>` by both contributors and CI.
+- Each Makefile recipe **MUST** call the real underlying command through `mise exec --`, following [agentme-edr-017](017-tool-execution-and-scripting.md).
+- Makefile recipes **MUST NOT** add extra script layers such as `npm run`, `pnpm run`, `yarn run`, `mise run`, `mise tasks`, or shell aliases when those layers only forward to another command.
 - Calling the actual tool is allowed even when that tool itself launches another program as part of its normal interface.
 	- Allowed: `mise exec -- pnpm exec eslint ./src`
 	- Allowed: `mise exec -- go test -cover ./...`
@@ -66,17 +66,17 @@ make <target>
 
 #### 03-standard-target-groups-and-names
 
-Targets are organized into five lifecycle groups. Projects must use these names unchanged. Extensions are allowed (see rule 5) but the core names must not be repurposed.
+Targets are organized into five lifecycle groups. Projects **MUST** use these names unchanged. Extensions are allowed (see rule 5) but the core names **MUST NOT** be repurposed.
 
 ##### Developer group
 
 | 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). No debugging or development-only features should 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-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:**
 
@@ -166,15 +166,15 @@ dev-mlflow:
 
 #### 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`.
 
 ---
 
 #### 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
@@ -187,7 +187,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.
 

package/.xdrs/agentme/edrs/governance/013-contributing-guide-requirements.md

@@ -15,9 +15,9 @@ What contributor workflow guidance must every project publish so contributors kn
 
 ## Decision Outcome
 
-**Every project must publish a root CONTRIBUTING.md with a small, explicit contribution workflow.**
+**Every project MUST publish a root CONTRIBUTING.md with a small, explicit contribution workflow.**
 
-Projects must keep a `CONTRIBUTING.md` file at the repository root. The file must explain where bugs, feature discussions, and code changes belong so contributors follow a predictable workflow before opening pull requests.
+Projects MUST keep a `CONTRIBUTING.md` file at the repository root. The file MUST explain where bugs, feature discussions, and code changes belong so contributors follow a predictable workflow before opening pull requests.
 
 ### Details
 

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

@@ -37,6 +37,7 @@ Language and framework-specific tooling and project structure.
 - [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-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-030](application/030-ai-test-types-taxonomy.md) - **AI test types taxonomy** - Names AI test types (safety, responsible-AI, quality-eval, prompt, code-level) with group, objective, mocking constraint, and relevance, and defines the shared golden dataset entry envelope
 - [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

package/.xdrs/agentme/edrs/observability/011-service-health-check-endpoint.md

@@ -17,7 +17,7 @@ How should services expose their health status and validate operational readines
 
 **Standardized `/health` endpoint with dependency validation**
 
-All services must expose a `GET /health` endpoint that validates external dependencies using read-only operations and returns structured status with appropriate HTTP codes.
+All services **MUST** expose a `GET /health` endpoint that validates external dependencies using read-only operations and returns structured status with appropriate HTTP codes.
 
 ### Details
 
@@ -45,12 +45,12 @@ All services must expose a `GET /health` endpoint that validates external depend
 
 - `health` (required): overall state — `OK`, `WARNING`, or `ERROR`
 - `latencyMs` (required): total milliseconds to run all checks
-- `message` (required): human-readable summary; must never expose credentials, internal IPs, or stack traces
+- `message` (required): human-readable summary; **MUST NEVER** expose credentials, internal IPs, or stack traces
 
 **Dependency validation rules:**
 
 - Check all external dependencies (databases, downstream APIs, queues, caches) using read-only operations (e.g., `SELECT 1`, lightweight GET, connection ping)
-- Never execute write operations or create side effects
+- **MUST NOT** execute write operations or create side effects
 - `OK`: all dependencies healthy within expected thresholds
 - `WARNING`: non-critical dependency degraded, or elevated but acceptable response times
 - `ERROR`: critical dependency unavailable or service unable to process requests
@@ -70,6 +70,28 @@ All services must expose a `GET /health` endpoint that validates external depend
 - Monitoring: periodic polling with alerts on `210` and `503` responses
 - CI/CD: poll `/health` to confirm deployment success
 
+**Unit testing and mocking strategy:** Each dependency checker MUST be injectable so unit tests can simulate `OK`, `WARNING`, and `ERROR` states independently without a real database or API. Integration tests MUST NOT mock dependency checkers — they MUST run against real dependencies to verify the wiring.
+
+```typescript
+// Good — injectable checkers; unit test controls each state
+function buildHealthHandler(checkers: DependencyChecker[]) {
+  return async () => {
+    const results = await Promise.all(checkers.map(c => c.check()));
+    const status = results.some(r => r.status === "ERROR") ? "ERROR"
+      : results.some(r => r.status === "WARNING") ? "WARNING" : "OK";
+    return { health: status };
+  };
+}
+
+it("returns ERROR when the database checker fails", async () => {
+  const handler = buildHealthHandler([
+    { check: async () => ({ name: "db", status: "ERROR" }) },
+  ]);
+  const response = await handler();
+  expect(response.health).toBe("ERROR");
+});
+```
+
 ## Considered Options
 
 * (REJECTED) **No health checks** — detect failures through request errors

package/.xdrs/agentme/edrs/principles/002-coding-best-practices.md

@@ -21,12 +21,10 @@ What coding practices should be followed across all languages and projects to ke
 
 #### 01-keep-files-short
 
-A file must not exceed **400 lines**. When a file grows beyond this limit, split related functions or types into separate, focused modules.
+A file MUST NOT exceed **400 lines**. When a file grows beyond this limit, split related functions or types into separate, focused modules.
 
 One exception are test files, which normally are bigger than the tested resources.
 
-*Why:* Large files make navigation slow, increase merge conflicts, and obscure the single-responsibility principle.
-
 **Example (TypeScript):**
 
 ```
@@ -50,8 +48,6 @@ src/
 
 When a function's main logic contains well-defined sections and **any individual section exceeds ~20 lines**, extract each section into its own named function. The outer function becomes an orchestrator that calls the extracted helpers in sequence.
 
-*Why:* Named sub-functions serve as inline documentation, are independently testable, and reduce cognitive load.
-
 **Example (Python):**
 
 ```python
@@ -85,9 +81,7 @@ def _persist_order(order, total): ...
 
 #### 03-put-entry-point-function-first
 
-Place the **entry-point function** (the outermost caller) at the **top** of the file. All helper or sub-functions it calls internally must appear **below** it.
-
-*Why:* Readers can follow the overall logic top-down without jumping around the file. The most important function is immediately visible when the file is opened.
+Place the **entry-point function** (the outermost caller) at the **top** of the file. All helper or sub-functions it calls internally MUST appear **below** it.
 
 **Example (Python):**
 
@@ -106,22 +100,18 @@ def _persist_order(order, total): ...
 
 #### 04-keep-readme-tests-and-examples-in-sync
 
-Every change to a public interface, behavior, or configuration option must be reflected in:
+Every change to a public interface, behavior, or configuration option MUST be reflected in:
 
 - `README.md` — update usage examples, option tables, and feature descriptions.
 - Unit/integration tests — update or add tests that cover the changed behavior.
 - `examples/` resources — update runnable examples so they continue to work.
 
-*Why:* Stale documentation and broken examples erode trust and waste time for consumers of the code.
-
 ---
 
 #### 05-declare-types-in-file-where-used
 
 If a type (struct, interface, class, typedef, etc.) is used in only **one** file, declare it in that same file. Move a type to a shared module only when it is referenced in two or more files.
 
-*Why:* Co-locating a type with its sole consumer removes the need to navigate to a separate types file and makes the type's purpose immediately obvious from context.
-
 ---
 
 #### 06-keep-test-files-next-to-source

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

@@ -262,3 +262,4 @@ AI projects are classified into three tiers — LLM, Agent, and Workflow — def
 - 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-028](../application/028-ai-eval-standards.md).
+- For the taxonomy of AI test types (safety, responsible-AI, quality-eval, prompt, code-level) and the golden dataset entry format, see [agentme-edr-030](../application/030-ai-test-types-taxonomy.md).

package/.xdrs/agentme/edrs/principles/009-error-handling.md

@@ -21,9 +21,7 @@ What error handling practices should be followed across all languages and projec
 
 #### 01-catch-only-where-handled
 
-Never catch an exception unless the catching site can genuinely recover from it, translate it into a meaningful domain error, or enrich it with context before re-throwing. Do **not** swallow exceptions silently. When suppressing an exception is intentional, always add a comment explaining exactly why, or log it at an appropriate level.
-
-*Why:* Swallowed exceptions hide bugs and make incidents impossible to diagnose. Every silent `catch` is a future mystery.
+MUST NOT catch an exception unless the catching site can genuinely recover from it, translate it into a meaningful domain error, or enrich it with context before re-throwing. MUST NOT swallow exceptions silently. When suppressing an exception is intentional, MUST add a comment explaining exactly why, or log it at an appropriate level.
 
 **Examples:**
 
@@ -77,9 +75,7 @@ except CacheError:
 
 #### 02-avoid-exceptions-in-public-interfaces
 
-At module and service boundaries, prefer returning a value that signals success or failure (e.g., a result type, a discriminated union, or a `(value, error)` tuple as in Go) over throwing exceptions. This forces callers to explicitly acknowledge and handle the error case before using the result.
-
-*Why:* Exceptions are invisible in signatures. A caller who doesn't know an exception can be thrown will never write a handler. Explicit error return values make the contract visible and encourage handling at the call site.
+At module and service boundaries, SHOULD prefer returning a value that signals success or failure (e.g., a result type, a discriminated union, or a `(value, error)` tuple as in Go) over throwing exceptions. This forces callers to explicitly acknowledge and handle the error case before using the result.
 
 **Examples:**
 
@@ -161,9 +157,7 @@ def fetch_user(user_id: str) -> Ok[User] | Err:
 
 #### 03-centralise-repetitive-catch-logic
 
-If the same `try/catch` pattern (e.g., logging, classifying HTTP errors, wrapping exceptions) appears in multiple places, extract it into a shared utility. Do not copy-paste catch blocks across the codebase.
-
-*Why:* Scattered catch blocks drift out of sync — one gets updated, the others don't. A central utility is tested once and applied everywhere consistently.
+If the same `try/catch` pattern (e.g., logging, classifying HTTP errors, wrapping exceptions) appears in multiple places, MUST be extracted into a shared utility. MUST NOT copy-paste catch blocks across the codebase.
 
 **Examples:**
 
@@ -213,13 +207,11 @@ def save_order(order: Order): ...
 
 #### 04-communicate-failure-at-boundaries
 
-Every system boundary must signal failure explicitly:
+Every system boundary MUST signal failure explicitly:
 
-- **OS processes** must exit with a **non-zero exit code** when something went wrong. Exit code `0` means success.
-- **HTTP services** must return a **non-2xx/3xx status code** on error, accompanied by a response body that describes the problem without exposing internal system details (stack traces, SQL queries, internal paths, etc.).
-- **All error responses** should be logged to the console/structured logger, especially system-level or unexpected errors. Operational teams must be able to find the cause from logs alone.
-
-*Why:* Orchestrators, CI runners, load balancers, and callers all rely on these signals to detect failures automatically. A process or service that reports success on failure leads to silent data corruption and missed alerts.
+- **OS processes** MUST exit with a **non-zero exit code** when something went wrong. Exit code `0` means success.
+- **HTTP services** MUST return a **non-2xx/3xx status code** on error, accompanied by a response body that describes the problem without exposing internal system details (stack traces, SQL queries, internal paths, etc.).
+- **All error responses** SHOULD be logged to the console/structured logger, especially system-level or unexpected errors. Operational teams must be able to find the cause from logs alone.
 
 **Examples:**
 
@@ -276,11 +268,9 @@ def create_order_endpoint(payload: OrderRequest):
 
 #### 05-write-test-cases-for-error-scenarios
 
-Every module that handles errors must have dedicated test cases that verify the error paths. Do not only test the happy path.
-
-*Why:* Error handling code is the code most likely to be broken and the code least likely to be exercised in manual testing. Without automated tests, regressions in error paths go undetected until production.
+Every module that handles errors MUST have dedicated test cases that verify the error paths. Do not only test the happy path.
 
-Typical error scenarios to cover:
+**Mocking strategy:** External dependencies (databases, HTTP services, file systems) MUST be mocked in error-path unit tests. Simulate failure by configuring the mock to throw or return an error value — do not rely on a real dependency being unavailable.
 
 - The dependency (DB, HTTP service, file system) is unavailable or times out.
 - The input is invalid, missing, or out of range.

package/.xdrs/agentme/edrs/principles/012-continuous-xdr-enrichment.md

@@ -17,16 +17,16 @@ Question: What policy should developers follow to continuously enrich XDRs so re
 
 **Develop features with shared-first XDR enrichment and controlled divergence**
 
-Developers must treat reusable missing guidance discovered during implementation as an XDR gap to be proposed and reviewed, not as permanent prompt-only context or repeated vibe coding.
+Developers MUST treat reusable missing guidance discovered during implementation as an XDR gap to be proposed and reviewed, not as permanent prompt-only context or repeated vibe coding.
 
 ### Details
 
-- The main objective is sharing, discussing, and converging practices across teams. Controlled divergence during exploration is acceptable, but recurring successful decisions must be converged into shared XDRs.
-- The non _local scope exists to share practices across projects, company areas, and functionally organized teams. Decisions placed in `_local` should be truly specific to the needs of a single application or repository.
-- When developers or coding agents need too much detailed steering to complete a task, they must reflect on whether those details would help other teams or future implementations. If yes, create or update an XDR proposal in the broadest appropriate shared scope.
-- This includes cases where an agent implemented a feature without a framework, pattern, coding standard, or other practice that should likely be standardized. Missing reusable guardrails should trigger an XDR proposal.
-- Teams should aim to keep at least 80% of big coding decisions covered by accepted XDRs. Big decisions include framework or tool selection, overall code organization, monorepo structure, complex business flows, and coding standards.
-- If a big decision is not yet covered, developers should either propose a new XDR or document why the decision is intentionally local and should not be shared.
+- The main objective is sharing, discussing, and converging practices across teams. Controlled divergence during exploration is acceptable, but recurring successful decisions MUST be converged into shared XDRs.
+- The non _local scope exists to share practices across projects, company areas, and functionally organized teams. Decisions placed in `_local` SHOULD be truly specific to the needs of a single application or repository.
+- When developers or coding agents need too much detailed steering to complete a task, they MUST reflect on whether those details would help other teams or future implementations. If yes, create or update an XDR proposal in the broadest appropriate shared scope.
+- This includes cases where an agent implemented a feature without a framework, pattern, coding standard, or other practice that should likely be standardized. Missing reusable guardrails SHOULD trigger an XDR proposal.
+- Teams SHOULD aim to keep at least 80% of big coding decisions covered by accepted XDRs. Big decisions include framework or tool selection, overall code organization, monorepo structure, complex business flows, and coding standards.
+- If a big decision is not yet covered, developers SHOULD either propose a new XDR or document why the decision is intentionally local and should not be shared.
 - Leaders responsible for the affected scope are accountable for reviewing XDR proposals, adjusting them, and publishing the accepted decision.
 - It is good practice to ask the coding agent which missing XDRs made the task harder, increased adjustment rounds, or forced more vibe coding. Those gaps should feed the XDR backlog.
 - In SDD, specifications describe the feature being built; XDRs describe reusable decisions and guardrails that should survive beyond one feature. Do not keep durable engineering policy only inside feature specs.

package/.xdrs/agentme/edrs/principles/016-cross-language-module-structure.md

@@ -17,7 +17,7 @@ What baseline structure rules must every buildable module follow regardless of l
 
 **Standardize every buildable module around its own folder root, with `dist/`, `.cache/`, sibling consumer examples, a module README, and predictable test locations.**
 
-Language-specific EDRs may add ecosystem details, but they must not redefine these baseline folder responsibilities.
+Language-specific EDRs MAY add ecosystem details, but they MUST NOT redefine these baseline folder responsibilities.
 
 ### Details
 
@@ -27,7 +27,7 @@ A module is the smallest independently buildable, testable, or publishable unit.
 
 - a `Makefile` following [agentme-edr-008](../devops/008-common-targets.md)
 - a `README.md` for the module itself
-- all configuration files required to build, lint, test, package, or publish that module
+- all configuration files needed to build, lint, test, package, or publish that module
 - its generated `dist/` directory when the module produces distributable artifacts
 - a module-local `.cache/` when tool caches are not intentionally shared with a parent aggregation root
 
@@ -44,11 +44,11 @@ Example module root:
 
 #### 02-parent-folders-are-aggregation-roots
 
-Parent folders such as a repository root, an application folder, or `lib/` may aggregate multiple modules. They may also hold shared consumer examples or multi-module test harnesses.
+Parent folders such as a repository root, an application folder, or `lib/` MAY aggregate multiple modules. They MAY also hold shared consumer examples or multi-module test harnesses.
 
-They MUST keep the public aggregation obvious: deleting an aggregation folder should remove a coherent API surface or entry-point area, not scatter unrelated internal implementation across the repository.
+They MUST keep the public aggregation obvious: deleting an aggregation folder SHOULD remove a coherent API surface or entry-point area, not scatter unrelated internal implementation across the repository.
 
-Recommended aggregation pattern:
+Example aggregation pattern:
 
 ```text
 <parent>/
@@ -88,7 +88,7 @@ Examples that demonstrate how to consume a library or reusable module MUST live
 Examples MUST exercise the module through its public distribution surface:
 
 - use the package built into `dist/` when the ecosystem supports local packaged artifacts
-- otherwise use the public module path or equivalent consumer-facing import surface, never relative source-file imports or direct references to internal implementation paths
+- otherwise use the public module path or equivalent consumer-facing import surface; **MUST NOT** use relative source-file imports or direct references to internal implementation paths
 
 Example:
 
@@ -106,7 +106,7 @@ Each module MUST contain a `README.md` that shows how to use the module as a con
 
 The end of the README MUST also include short developer instructions for that module, covering at least the standard build, lint, and test entry points.
 
-Repository-level READMEs may describe the workspace, but they do not replace the module README.
+Repository-level READMEs MAY describe the workspace, but they do not replace the module README.
 
 #### 07-tests-use-predictable-locations
 

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

@@ -142,6 +142,24 @@ Prefer fetching the secret inside the function that directly needs it rather tha
 
 Passing secrets via function arguments is acceptable when the consuming function cannot access the connector directly, but the default design should fetch at the point of use.
 
+#### 09-unit-testing-and-mocking-strategy
+
+Code that calls the secret connector MUST accept it as an injectable parameter. Unit tests MUST inject a fake connector that returns a pre-configured value without touching the OS keychain or any cloud secret manager.
+
+```python
+# Good — injectable connector; unit test provides a fake
+class MyService:
+    def __init__(self, secrets: SecretConnector):
+        self.api_key = secrets.get("api-key")
+
+def test_service_uses_api_key():
+    fake = FakeSecretConnector({"api-key": "test-key-123"})
+    svc = MyService(secrets=fake)
+    assert svc.api_key == "test-key-123"
+```
+
+Integration tests MAY use the real keychain on developer machines or CI after `make setup-secrets` has been run.
+
 ## References
 
 - [agentme-edr-008](../devops/008-common-targets.md) - Common development script names (defines Makefile target conventions)

package/.xdrs/agentme/edrs/principles/023-coding-abstraction-practices.md

@@ -21,9 +21,7 @@ What principles should guide the decision to introduce — or reject — an abst
 
 #### 01-prioritize-functional-programming
 
-Prefer functional programming: pure functions with clear input → processing → output flow. Object-oriented patterns (classes, inheritance) are allowed **only** when there is a clear benefit from the additional abstraction they bring — e.g., when complex context management or true inheritance hierarchies are intrinsically part of the best solution for a problem.
-
-*Why:* Functional units are simpler to reason about, test, and compose. OO introduces shared mutable state and implicit coupling that must earn its place.
+Prefer functional programming: pure functions with clear input → processing → output flow. Object-oriented patterns (classes, inheritance) MAY only be used when there is a clear benefit from the additional abstraction they bring — e.g., when complex context management or true inheritance hierarchies are intrinsically part of the best solution for a problem.
 
 ---
 
@@ -43,7 +41,7 @@ These patterns obfuscate the main program flow and create behavioral indirection
 
 #### 03-trivial-wrappers-are-prohibited
 
-A function that merely delegates to another function or API call without adding meaningful logic, domain intent, or readability **must be inlined**. A wrapper is justified only when it:
+A function that merely delegates to another function or API call without adding meaningful logic, domain intent, or readability **MUST be inlined**. A wrapper is justified only when it:
 
 - Encapsulates non-trivial logic (validation, retry, transformation).
 - Communicates a domain concept the underlying expression does not convey.
@@ -76,7 +74,7 @@ A function that constructs an object (e.g., configuration, options) is only just
 - Combines data in a non-linear or conditional way.
 - Is reused by multiple callers.
 
-A function that restructures simple static data in an almost 1-to-1 mapping forces the reader to trace indirection for no benefit and must be inlined.
+A function that restructures simple static data in an almost 1-to-1 mapping forces the reader to trace indirection for no benefit and MUST be inlined.
 
 **Bad — trivial factory:**
 

package/.xdrs/agentme/index.md

@@ -1,3 +1,12 @@
+---
+name: agentme
+description: Curated library of XDRs and skills encoding best practices for AI coding agents across JavaScript, Go, and Python projects.
+scope-type: standard
+follows: agentme-core
+apply-to: AI coding agents and developers adopting agentme engineering standards.
+valid-from: 2025-01-01
+---
+
 # agentme Scope Overview
 
 ## Overview

package/.xdrs/index.md

@@ -11,7 +11,15 @@ XDRS scopes listed last override the ones listed first
 ### _core
 
 Decisions about how XDRs work
-[View _core Scope Index](_core/index.md)
+[View scope _core](_core/index.md)
+
+---
+
+### agentme-core
+
+Meta-governance for the agentme scope (writing standards, content conventions, authoring guidance). Not distributed to consumers.
+
+[View scope agentme-core](agentme-core/index.md)
 
 ---
 
@@ -19,7 +27,7 @@ Decisions about how XDRs work
 
 Opiniated set of decisions and skills for common development tasks
 
-[View agentme Scope Index](agentme/index.md)
+[View scope agentme](agentme/index.md)
 
 ---
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "agentme",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "",
   "dependencies": {
-    "filedist": "^0.37.0"
+    "filedist": "^0.39.0"
   },
   "bin": "bin/filedist.js",
   "files": [
@@ -18,6 +18,6 @@
     "url": "https://github.com/flaviostutz/agentme.git"
   },
   "devDependencies": {
-    "xdrs-core": "^0.31.1"
+    "xdrs-core": "^0.37.1"
   }
 }