agentme 0.24.2 → 0.25.2

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

@@ -23,7 +23,7 @@ These standards form a non-negotiable baseline. Individual projects may raise th
 
 #### 01-readme-must-have-getting-started
 
-`README.md` must include a **Getting Started** section in the first 20 lines with the minimal steps to install and use the project.
+`README.md` MUST include a **Getting Started** section in the first 20 lines with the minimal steps to install and use the project.
 
 **Required content:**
 - Installation or setup command(s)
@@ -52,7 +52,7 @@ myFunction({ input: "value" });
 
 #### 02-unit-tests-must-run-on-every-release
 
-A unit test suite must run automatically before every release. Failing tests must block the release — no silent skips or overrides.
+A unit test suite MUST run automatically before every release. Failing tests must block the release — no silent skips or overrides.
 
 **Requirements:**
 - A `make test` target must exist and run the full suite
@@ -67,7 +67,7 @@ A unit test suite must run automatically before every release. Failing tests mus
 
 #### 03-project-must-comply-with-xdrs
 
-All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../../index.md)) must be followed. A deviation requires a project-local XDR documenting the override.
+All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../../index.md)) MUST be followed. A deviation requires a project-local XDR documenting the override.
 
 **Requirements:**
 - Review applicable XDRs before any significant implementation
@@ -77,7 +77,7 @@ All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../
 
 #### 04-project-must-have-linting
 
-Projects larger than 10 files or 200 lines of code must have a linter configured and actively enforced. Lint failures block CI builds.
+Projects larger than 10 files or 200 lines of code MUST have a linter configured and actively enforced. Lint failures block CI builds.
 
 **Requirements:**
 - `make lint` runs the linter with zero-warning tolerance
@@ -93,7 +93,7 @@ Projects larger than 10 files or 200 lines of code must have a linter configured
 
 #### 05-project-structure-must-be-clear
 
-Directory and file layout must be self-explanatory: source code, tests, configuration, and examples must be clearly separated and named.
+Directory and file layout MUST be self-explanatory: source code, tests, configuration, and examples must be clearly separated and named.
 
 **Requirements:**
 - Directory names must reflect their purpose (`src/`, `lib/`, `tests/`, `examples/`, `docs/`)
@@ -118,7 +118,7 @@ Directory and file layout must be self-explanatory: source code, tests, configur
 
 #### 06-libraries-must-have-runnable-examples
 
-Projects that are libraries or shared utilities must include an `examples/` directory. Each subdirectory represents a usage scenario and must be independently runnable. Examples that are "offline" (require no external credentials, no running servers, no paid APIs, and no environment-specific configuration outside the repository) must be executed as part of `make test`. Examples that depend on external entities may be left out of `make test`.
+Projects that are libraries or shared utilities MUST include an `examples/` directory. Each subdirectory represents a usage scenario and must be independently runnable. Examples that are "offline" (require no external credentials, no running servers, no paid APIs, and no environment-specific configuration outside the repository) must be executed as part of `make test`. Examples that depend on external entities may be left out of `make test`.
 
 **Requirements:**
 - `examples/` must contain at least one subdirectory per major usage scenario
@@ -170,7 +170,7 @@ all:
 
 #### 07-statistical-models-must-have-eval-targets
 
-Projects that contain statistical models (e.g., ML models, LLM-based evaluators, classifiers, ranking systems, or any component whose output quality is measured probabilistically) must define measurable performance thresholds and verify them automatically.
+Projects that contain statistical models (e.g., ML models, LLM-based evaluators, classifiers, ranking systems, or any component whose output quality is measured probabilistically) MUST define measurable performance thresholds and verify them automatically.
 
 **Requirements:**
 - A `make eval` target must exist and execute all performance evaluations
@@ -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

@@ -29,7 +29,7 @@ All implementation practices derive from three guiding principles:
 
 #### 01-no-secrets-on-disk
 
-Secrets must never be stored on the disk of a developer machine or server. This includes `.env` files (even when gitignored), plaintext config files, embedded in source code, or any other file-based storage.
+Secrets MUST NEVER be stored on the disk of a developer machine or server. This includes `.env` files (even when gitignored), plaintext config files, embedded in source code, or any other file-based storage.
 
 The only acceptable local persistence is through the operating system's native secret manager (e.g., macOS Keychain, Windows Credential Manager, Linux Secret Service).
 
@@ -37,7 +37,7 @@ The only acceptable local persistence is through the operating system's native s
 
 #### 02-local-dev-uses-native-keychain
 
-During local development, secrets must be stored and retrieved using the native OS secret manager. Use cross-platform libraries to keep the code OS-agnostic:
+During local development, secrets MUST be stored and retrieved using the native OS secret manager. Use cross-platform libraries to keep the code OS-agnostic:
 
 | Language | Library |
 |----------|---------|
@@ -51,7 +51,7 @@ The "group" (service name) defaults to the module name. The secret identifier sh
 
 #### 03-fallback-lookup-order
 
-Secret fetching must implement a fallback chain in the following order:
+Secret fetching MUST implement a fallback chain in the following order:
 
 1. **Native OS keychain** — attempt to retrieve the secret using the local keychain library (used during local development).
 2. **Cloud secret manager** — if not found locally, fetch from the configured cloud secret manager (AWS Secrets Manager, Azure Key Vault, etc.) (used in cloud environments).
@@ -66,13 +66,13 @@ Secret 'db-password' could not be found in keychain under group 'mymodule' or in
 
 #### 04-secret-fetching-in-connector
 
-The secret fetching logic (including the fallback chain from rule 03) must live in a dedicated "connector" module or function. This isolates secret-access concerns from business logic and provides a single point to configure secret sources, caching policy, and error handling.
+The secret fetching logic (including the fallback chain from rule 03) MUST live in a dedicated "connector" module or function. This isolates secret-access concerns from business logic and provides a single point to configure secret sources, caching policy, and error handling.
 
 ---
 
 #### 05-setup-secrets-makefile-target
 
-Every module that requires secrets must expose a `setup-secrets` Makefile target. This target:
+Every module that requires secrets MUST expose a `setup-secrets` Makefile target. This target:
 
 - Prompts the user for each required secret value interactively.
 - If the user provides an empty value, the existing secret is not updated.
@@ -120,13 +120,13 @@ In library code (Python, JS/TS, Go), continue using the cross-platform libraries
 
 #### 06-never-log-or-leak-secrets
 
-Secrets must never be logged under any circumstance or sent to any service that is not clearly the intended consumer of that secret (authentication, encryption, etc.). This applies to all log levels including debug and trace. Error messages must reference the secret name or identifier, never its value.
+Secrets MUST NEVER be logged under any circumstance or sent to any service that is not clearly the intended consumer of that secret (authentication, encryption, etc.). This applies to all log levels including debug and trace. Error messages must reference the secret name or identifier, never its value.
 
 ---
 
 #### 07-prefer-dynamic-fetching
 
-Wherever possible, fetch secrets dynamically from the secret manager at the time of use. Avoid storing secrets in global variables or caching them indefinitely. Dynamic fetching through a specialized service enables:
+Wherever possible, secrets SHOULD be fetched dynamically from the secret manager at the time of use. Avoid storing secrets in global variables or caching them indefinitely. Dynamic fetching through a specialized service enables:
 
 - Automatic password rotation without redeployment.
 - Immediate propagation of rotated secrets.
@@ -138,10 +138,28 @@ Short-lived caching (e.g., a few minutes) is acceptable when performance require
 
 #### 08-prefer-fetching-at-point-of-use
 
-Prefer fetching the secret inside the function that directly needs it rather than passing it through multiple layers as a function argument. This minimizes the exposure surface by reducing the number of code paths that handle the raw secret value.
+Developers SHOULD prefer fetching the secret inside the function that directly needs it rather than passing it through multiple layers as a function argument. This minimizes the exposure surface by reducing the number of code paths that handle the raw secret value.
 
 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,15 +21,13 @@ 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.
 
 ---
 
 #### 02-prefer-explicit-calls-over-indirections
 
-A sequence of direct calls to libraries and resources makes logic straightforward. Avoid:
+Developers SHOULD prefer a sequence of direct calls to libraries and resources to keep logic straightforward. Avoid:
 
 - Aspect-oriented programming (AOP)
 - Implicit context injection / dependency injection containers
@@ -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:**
 
@@ -105,7 +103,7 @@ function createServerConfig(opts: Partial<ServerOpts>): ServerConfig {
 
 #### 05-abstractions-for-business-logic-are-encouraged
 
-Extracting domain logic into a named function is **encouraged** when it:
+Developers SHOULD extract domain logic into a named function when it:
 
 - Encapsulates a business rule so the reader does not need to parse low-level conditions to understand domain intent.
 - Communicates intent at a glance, making compound conditions or multi-step checks self-describing.
@@ -124,6 +122,6 @@ if (event.status === 'active' && event.role !== 'guest' && event.quota > 0) { ..
 
 #### 06-idiomatic-framework-patterns-are-exempt
 
-React hooks, higher-order components, middleware chains, and similar patterns established by the framework in use are **not** considered unnecessary abstraction. The reader already expects them, and fighting the framework's idioms creates more confusion than it removes.
+React hooks, higher-order components, middleware chains, and similar patterns established by the framework in use MUST NOT be treated as unnecessary abstraction. The reader already expects them, and fighting the framework's idioms creates more confusion than it removes.
 
 This exemption does not override other rules — a trivial wrapper inside a hook is still prohibited.

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,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.24.2",
+  "version": "0.25.2",
   "description": "",
   "dependencies": {
     "filedist": "^0.39.0"
@@ -18,6 +18,6 @@
     "url": "https://github.com/flaviostutz/agentme.git"
   },
   "devDependencies": {
-    "xdrs-core": "^0.31.2"
+    "xdrs-core": "^0.38.0"
   }
 }