agentme 0.25.2 → 0.27.0

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

@@ -21,15 +21,41 @@ Projects MUST keep a `CONTRIBUTING.md` file at the repository root. The file MUS
 
 ### Details
 
-- Every project **MUST** have a root `CONTRIBUTING.md`.
-- The guide **MUST** direct bug reports to issues.
-- The guide **MUST** direct feature ideas and feature discussions to issues before implementation starts.
-- The guide **MUST** state that fixes and features are contributed through pull requests.
-- The guide **MUST** state that pull requests come from feature branches targeting `main`.
-- The guide **MUST** ask reviewers and contributors to use [Conventional Comments](https://conventionalcomments.org/) for review feedback.
-- The guide **MUST** ask contributors to keep pull requests small enough to keep review and discussion focused.
-- Project scaffolding skills **SHOULD** create the file by default when they initialize a repository.
-- The content **SHOULD** stay concise and practical; do not turn `CONTRIBUTING.md` into a duplicate of `README.md`.
+#### 01-contributing-md-is-required
+
+Every project MUST have a root `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.
+
+#### 02-guide-must-direct-bug-reports-to-issues
+
+The guide MUST direct bug reports to issues.
+
+#### 03-guide-must-route-feature-discussions-to-issues
+
+The guide MUST direct feature ideas and feature discussions to issues before implementation starts.
+
+#### 04-guide-must-require-pull-requests
+
+The guide MUST state that fixes and features are contributed through pull requests.
+
+#### 05-guide-must-require-feature-branches
+
+The guide MUST state that pull requests come from feature branches targeting `main`.
+
+#### 06-guide-must-require-conventional-comments
+
+The guide MUST ask reviewers and contributors to use [Conventional Comments](https://conventionalcomments.org/) for review feedback.
+
+#### 07-guide-must-ask-for-small-pull-requests
+
+The guide MUST ask contributors to keep pull requests small enough to keep review and discussion focused.
+
+#### 08-scaffolding-should-create-contributing-md
+
+Project scaffolding skills SHOULD create the file by default when they initialize a repository.
+
+#### 09-content-should-be-concise
+
+The content SHOULD stay concise and practical; do not turn `CONTRIBUTING.md` into a duplicate of `README.md`.
 
 ## Considered Options
 

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

@@ -27,21 +27,36 @@ Synthetic views combining agentme XDRs and skills around a specific topic.
 
 Language and framework-specific tooling and project structure.
 
+### Language and framework tooling
+
 - [agentme-edr-003](application/003-javascript-project-tooling.md) - **JavaScript project tooling and structure** - Scaffold JavaScript libraries with the standard toolchain *(includes skill: [001-create-javascript-project](application/skills/001-create-javascript-project/SKILL.md))*
 - [agentme-edr-010](application/010-golang-project-tooling.md) - **Go project tooling and structure** - Scaffold Go CLIs and libraries with the standard layout *(includes skill: [003-create-golang-project](application/skills/003-create-golang-project/SKILL.md))*
 - [agentme-edr-014](application/014-python-project-tooling.md) - **Python project tooling and structure** - Scaffold Python packages and CLIs with the standard layout *(includes skill: [005-create-python-project](application/skills/005-create-python-project/SKILL.md))*
 - [agentme-edr-015](application/015-cli-tool-standards.md) - **CLI tool standards** - Define command UX and behavior for CLI tools
+- [agentme-edr-026](application/026-pragmatic-hexagonal-architecture.md) - **Pragmatic hexagonal architecture** - Organize application layers as External/Adapters/Application with practical coupling rules
+- [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
+
+### AI development
+
+Standards for building LLM, Agent, and Workflow components.
+
 - [agentme-edr-018](application/018-ai-llm-development-standards.md) - **AI LLM development standards** - Standard framework (LangChain) and patterns for simple LLM calls with explicit configuration (no environment variables)
 - [agentme-edr-019](application/019-ai-agents-development-standards.md) - **AI agents development standards** - Structural patterns for agents: framework selection, sandbox setup, naming conventions, composition, and system prompt structure
 - [agentme-edr-020](application/020-ai-agents-quality-standards.md) - **AI agents implementation quality standards** - Tool definition patterns, error handling, observability, and unit testing for agents
 - [agentme-edr-021](application/021-ai-workflow-development-standards.md) - **AI workflow development standards** - Standard toolchain (LangGraph), evaluation, and testing patterns for workflow projects
 - [agentme-edr-029](application/029-ai-workflow-naming-conventions.md) - **AI workflow naming conventions** - Node suffix/prefix roles, state type and attribute naming, judge output schema, workflow class names, and cross-element coherence rules
-- [agentme-edr-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
-- [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
+
+### AI evaluation and testing
+
+Standards for eval datasets, scripts, reports, and test type taxonomy.
+
+- [agentme-edr-030](application/030-ai-test-types-taxonomy.md) - **AI test types taxonomy** - Names AI test types (`functional`, `safety`, `smoke`, `repeatability`, `adversarial`, `fairness`, and 6 others) with group, objective, mocking constraint, and relevance, and defines the shared golden dataset entry envelope
+- [agentme-edr-028](application/028-ai-eval-core-standards.md) - **AI eval core standards** - Eval folder structure and Makefile interface; LLM-as-judge binary scoring contract applicable to all AI tiers and test types
+- [agentme-edr-031](application/031-ai-eval-script.md) - **AI eval script** - eval.py requirements: entry-first loop, --type filtering, mock_fixtures wiring, human entries, threshold enforcement, and MLflow experiment conventions
+- [agentme-edr-032](application/032-ai-eval-report-format.md) - **AI eval report format** - report-<type>.md template, Wilson score confidence interval, convergence analysis, and human-type checklist artifact
+- [agentme-edr-033](application/033-ai-eval-repeatability.md) - **AI eval repeatability** - Repeatability test type: REPEAT_COUNT loop exception, semantic-similarity and LLM-as-judge scoring, repeatability_accuracy metric, report shape, and run cadence
+- [agentme-edr-024](application/024-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
 
 ## Devops
 

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

@@ -45,7 +45,7 @@ All services **MUST** expose a `GET /health` endpoint that validates external de
 
 - `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 NOT expose credentials, internal IPs, or stack traces
 
 **Dependency validation rules:**
 

package/.xdrs/agentme/edrs/principles/004-unit-test-requirements.md

@@ -15,13 +15,15 @@ What unit testing practices should be followed to ensure tests are meaningful, r
 
 ## Decision Outcome
 
-**Every test must assert behavior, run offline without external dependencies, enforce 80% coverage, centralize shared setup, and prefer real code over mocks.**
+**Every test MUST assert behavior, run offline without external dependencies, enforce 80% coverage, centralize shared setup, and prefer real code over mocks.**
 
 ### Details
 
 #### 01-must-have-at-least-one-assertion-per-test
 
 Every test MUST have at least one assertion that validates the expected behavior.
+
+```typescript
 // bad — no assertion; passes even when code is broken
 it("processes the order", () => { processOrder(mockOrder); });
 
@@ -36,7 +38,7 @@ it("processes the order and returns a confirmation id", () => {
 
 #### 02-must-run-offline
 
-Unit tests MUST NOT depend on any external resources: no network calls, no running databases, no external APIs, no file system paths outside the repo. Tests must pass with only static code available.
+Unit tests MUST NOT depend on any external resources: no network calls, no running databases, no external APIs, no file system paths outside the repo. Tests MUST pass with only static code available.
 
 ```typescript
 // bad — hits a real HTTP endpoint
@@ -83,7 +85,7 @@ src/mymodule/group1/file1.ts        ← source
 src/mymodule/group1/file1.test.ts   ← test (same directory)
 ```
 
-**Exception — separate test folder:** When the framework makes co-location impractical (e.g. Python's common `tests/` convention), or when the community strongly favors a separate folder, a dedicated test root (e.g. `tests/`) is allowed. In that case the test folder **must mirror** the source folder structure exactly:
+**Exception — separate test folder:** When the framework makes co-location impractical (e.g. Python's common `tests/` convention), or when the community strongly favors a separate folder, a dedicated test root (e.g. `tests/`) is allowed. In that case the test folder MUST mirror the source folder structure exactly:
 
 ```
 src/mymodule/group1/file1.py          ← source
@@ -111,7 +113,7 @@ export function makeOrder(overrides: Partial<Order> = {}): Order {
 
 Tests SHOULD use the lowest-cost alternative that exercises real behavior:
 
-1. **Real implementation** — always prefer this
+1. **Real implementation** — MUST be preferred
 2. **In-memory / lightweight fake** — e.g. in-memory DB, stub HTTP server
 3. **Recorded fixture** — replay captured real responses
 4. **Mock / stub** — only for external APIs, irreversible operations, or hardware I/O

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

@@ -15,9 +15,9 @@ What minimum quality standards must every project in the organization meet to en
 
 ## Decision Outcome
 
-Every project must meet the minimum quality standards: a Getting Started section in its README, unit tests that run on every release, compliance with workspace XDRs, active linting enforcement, a structure that is clear to new developers, and — for libraries and utilities — a runnable examples folder verified on every test run. Integration tests are advised but not required. Projects with statistical models must have evaluation targets with performance thresholds.
+Every project MUST meet the minimum quality standards: a Getting Started section in its README, unit tests that run on every release, compliance with workspace XDRs, active linting enforcement, a structure that is clear to new developers, and — for libraries and utilities — a runnable examples folder verified on every test run. Integration tests are advised but not required. Projects with statistical models MUST have evaluation targets with performance thresholds.
 
-These standards form a non-negotiable baseline. Individual projects may raise the bar but must never fall below it.
+These standards form a non-negotiable baseline. Individual projects may raise the bar but MUST NOT fall below it.
 
 ### Details
 
@@ -52,14 +52,14 @@ 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
-- CI/CD must invoke it before publish/deploy
+- A `make test` target MUST exist and run the full suite
+- CI/CD MUST invoke it before publish/deploy
 - Test failures block the release
 
-**Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects must never be deployed to production.
+**Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects MUST NOT be deployed to production.
 
 **Reference:** [agentme-edr-004](004-unit-test-requirements.md) for detailed unit test requirements.
 
@@ -85,7 +85,7 @@ Projects larger than 10 files or 200 lines of code MUST have a linter configured
 - Linter config is checked in (e.g., `.eslintrc.js`, `pyproject.toml`, `.golangci.yml`)
 - CI runs `make lint` before merging or releasing
 
-**Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects must never be deployed to production.
+**Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects MUST NOT be deployed to production.
 
 **Reference:** [agentme-edr-003](../application/003-javascript-project-tooling.md) for JavaScript-specific tooling.
 
@@ -93,11 +93,11 @@ 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/`)
-- README must describe the top-level layout if non-obvious
+- Directory names MUST reflect their purpose (`src/`, `lib/`, `tests/`, `examples/`, `docs/`)
+- README MUST describe the top-level layout if non-obvious
 - No orphaned or unexplained directories or files at the project root
 
 **Example layout (TypeScript project):**
@@ -118,14 +118,14 @@ 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
-- Each scenario subdirectory must have a `Makefile` with a `run` target
-- Examples must import the library as an external consumer (not via relative `../src` imports)
-- `make test` in the root must run all offline examples; failures block CI and releases
-- Examples that depend on external entities must not be included in `make test`
+- `examples/` MUST contain at least one subdirectory per major usage scenario
+- Each scenario subdirectory MUST have a `Makefile` with a `run` target
+- Examples MUST import the library as an external consumer (not via relative `../src` imports)
+- `make test` in the root MUST run all offline examples; failures block CI and releases
+- Examples that depend on external entities MUST NOT be included in `make test`
 
 **Directory layout:**
 
@@ -173,25 +173,30 @@ all:
 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
-- Each evaluation must have a **documented minimum performance threshold** (e.g., accuracy ≥ 0.85, F1 ≥ 0.80, BLEU ≥ 0.70)
-- Thresholds must be declared explicitly in the project (e.g., in a config file, `Makefile` variable, or documented in `README.md`)
-- `make eval` must **exit with a non-zero status** (fail) if:
+- A `make eval` target MUST exist and execute all performance evaluations
+- Each evaluation MUST have a **documented minimum performance threshold** (e.g., accuracy ≥ 0.85, F1 ≥ 0.80, BLEU ≥ 0.70)
+- Thresholds and all scoring parameters MUST be declared as constants in `eval.py` — they are design decisions about acceptable quality for the component under test, not runtime configuration, and MUST NOT be passed as Makefile variables or CLI flags. See [agentme-edr-031](../application/031-ai-eval-script.md) rule `01`.
+- `make eval` MUST **exit with a non-zero status** (fail) if:
   - The evaluation cannot be executed (missing data, environment errors, model load failures)
   - Any metric falls below its defined minimum threshold
-- CI/CD must invoke `make eval` before releasing any version that changes model weights, prompts, or evaluation logic
+- CI/CD MUST invoke `make eval` before releasing any version that changes model weights, prompts, or evaluation logic
 
-**Threshold declaration example (Makefile):**
+**Threshold declaration example (eval.py):**
 
-```makefile
-EVAL_MIN_ACCURACY := 0.85
-EVAL_MIN_F1       := 0.80
+```python
+EVAL_MIN_ACCURACY = {"functional": 0.85, "smoke": 0.90}
+EVAL_MIN_F1 = {"functional": 0.80}
+
+# Thresholds are declared here and enforced by the script:
+if accuracy < EVAL_MIN_ACCURACY.get(test_type, 0):
+    raise SystemExit(f"Eval failed: {test_type} accuracy {accuracy:.2f} < {EVAL_MIN_ACCURACY[test_type]}")
+```
 
+**Makefile target (delegates to eval.py — no threshold variables here):**
+
+```makefile
 eval:
-	python eval.py \
-	  --min-accuracy $(EVAL_MIN_ACCURACY) \
-	  --min-f1 $(EVAL_MIN_F1) \
-	  || (echo "Evaluation failed: metrics below threshold"; exit 1)
+	mise exec -- uv run --project . python eval.py --type=all
 ```
 
 ---
@@ -261,5 +266,5 @@ AI projects are classified into three tiers — LLM, Agent, and Workflow — def
 - Evals MUST be executed before every release.
 - 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 eval folder structure and LLM-as-judge scoring, see [agentme-edr-028](../application/028-ai-eval-core-standards.md). For eval script requirements, see [agentme-edr-031](../application/031-ai-eval-script.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

@@ -211,7 +211,7 @@ 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.
+- **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:**
 

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

@@ -21,15 +21,33 @@ Developers MUST treat reusable missing guidance discovered during implementation
 
 ### 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.
-- 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.
+#### 01-reusable-guidance-must-become-shared-xdr
+
+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. 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.
+
+#### 02-local-scope-must-be-for-truly-specific-decisions
+
+Decisions placed in `_local` SHOULD be truly specific to the needs of a single application or repository. The non-`_local` scope exists to share practices across projects, company areas, and functionally organized teams.
+
+#### 03-steering-needs-must-trigger-xdr-reflection
+
+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.
+
+#### 04-coverage-target-should-be-80-percent
+
+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.
+
+#### 05-leaders-must-review-xdr-proposals
+
+Leaders responsible for the affected scope MUST review XDR proposals, adjust them as needed, and publish the accepted decision.
+
+#### 06-query-agents-for-missing-xdrs
+
+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.
+
+#### 07-xdrs-are-not-feature-specs
+
+In SDD, specifications describe the feature being built; XDRs describe reusable decisions and guardrails that MUST survive beyond one feature. Do not keep durable engineering policy only inside feature specs.
 
 ## Considered Options
 

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

@@ -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; **MUST NOT** use 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:
 

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).
 
@@ -96,31 +96,11 @@ $ 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.
 
 ---
 
@@ -132,7 +112,7 @@ Wherever possible, secrets SHOULD be fetched dynamically from the secret manager
 - 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.
 
 ---
 
@@ -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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.25.2",
+  "version": "0.27.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.39.0"