agentme 0.25.0 → 0.26.0

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

@@ -23,13 +23,13 @@ All implementation practices derive from three guiding principles:
 
 1. **Least exposure** — minimize the means, timespan, and surface of contact with the secret.
 2. **Easiness in secret rotation** — design so rotating a secret requires no code change or redeployment.
-3. **Support for local and cloud deployment runs** — the same application code must work transparently in both environments.
+3. **Support for local and cloud deployment runs** — the same application code MUST work transparently in both environments.
 
 ### Details
 
 #### 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 NOT 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.
@@ -96,49 +96,29 @@ $ make run
 # Application starts successfully
 ```
 
-#### 05a-makefile-uses-security-utility
-
-Makefile targets (e.g., `setup-secrets`) must use the macOS native `security` CLI to store and retrieve secrets from the keychain. This restricts Makefile-based secret management to macOS developer machines, which is acceptable since all contributors are expected to use macOS.
-
-Do **not** use `keyring` or other cross-platform libraries in Makefiles — `security` is simpler to invoke from shell and requires no additional dependencies.
-
-Storing a secret:
-```makefile
-security add-generic-password -a "$(USER)" -s "mymodule/api-key" -w "$(SECRET_VALUE)" -U
-```
-
-Retrieving a secret (e.g., to pass to a command):
-```makefile
-SECRET_VALUE := $(shell security find-generic-password -a "$(USER)" -s "mymodule/api-key" -w 2>/dev/null)
-```
-
-The `-U` flag updates the entry if it already exists. Use the format `<group>/<secret-id>` as the service name (`-s`) to mirror the module name and cloud secret manager ID convention defined in rule 02 and 05.
-
-In library code (Python, JS/TS, Go), continue using the cross-platform libraries defined in rule 02 (`keyring`, `cross-keychain`, `go-keyring`). The `security` utility is only for Makefile scripts.
-
 ---
 
 #### 06-never-log-or-leak-secrets
 
-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 NOT 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, MUST NOT include 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.
 - Reduced window of exposure if memory is compromised.
 
-Short-lived caching (e.g., a few minutes) is acceptable when performance requires it, but must have an explicit TTL.
+Short-lived caching (e.g., a few minutes) is acceptable when performance requires it, but MUST have an explicit TTL.
 
 ---
 
 #### 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.
 
@@ -160,6 +140,28 @@ def test_service_uses_api_key():
 
 Integration tests MAY use the real keychain on developer machines or CI after `make setup-secrets` has been run.
 
+---
+
+#### 10-makefile-uses-security-utility
+
+Makefile targets (e.g., `setup-secrets`) MUST use the macOS native `security` CLI to store and retrieve secrets from the keychain. This restricts Makefile-based secret management to macOS developer machines, which is acceptable since all contributors are expected to use macOS.
+
+Do not use `keyring` or other cross-platform libraries in Makefiles — `security` is simpler to invoke from shell and requires no additional dependencies.
+
+Storing a secret:
+```makefile
+security add-generic-password -a "$(USER)" -s "mymodule/api-key" -w "$(SECRET_VALUE)" -U
+```
+
+Retrieving a secret (e.g., to pass to a command):
+```makefile
+SECRET_VALUE := $(shell security find-generic-password -a "$(USER)" -s "mymodule/api-key" -w 2>/dev/null)
+```
+
+The `-U` flag updates the entry if it already exists. Use the format `<group>/<secret-id>` as the service name (`-s`) to mirror the module name and cloud secret manager ID convention defined in rule 02 and 05.
+
+In library code (Python, JS/TS, Go), continue using the cross-platform libraries defined in rule 02 (`keyring`, `cross-keychain`, `go-keyring`). The `security` utility is only for Makefile scripts.
+
 ## 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

@@ -27,7 +27,7 @@ Prefer functional programming: pure functions with clear input → processing
 
 #### 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
@@ -41,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.
@@ -103,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.
@@ -122,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/package.json

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