agentme 0.28.1 → 0.30.0

package/.filedist-package.yml

@@ -1,5 +1,5 @@
 sets:
-  - package: xdrs-core@0.39.0
+  - package: xdrs-core@0.42.0
   # - package: git:https://github.com/flaviostutz/xdrs-core.git@main
     selector:
       files:
@@ -14,7 +14,7 @@ sets:
 
   - selector:
       files:
-        - .xdrs/agentme/edrs/application/skills/004-select-relevant-xdrs/**
+        - .xdrs/agentme/edrs/application/skills/010-select-relevant-xdrs/**
     output:
       path: .
       gitignore: false

package/.xdrs/agentme/edrs/application/{003-javascript-project-tooling.md → 101-javascript-project-tooling.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-003-javascript-project-tooling-and-structure
+name: agentme-edr-policy-101-javascript-project-tooling-and-structure
 description: Defines the standard JavaScript and TypeScript project toolchain and layout using Mise, pnpm, TypeScript, ESLint, Jest, and Makefiles. Use when scaffolding or reviewing JavaScript projects.
 apply-to: JavaScript and TypeScript projects
 valid-from: 2026-05-25
 ---
 
-# agentme-edr-policy-003: JavaScript project tooling and structure
+# agentme-edr-policy-101: JavaScript project tooling and structure
 
 ## Context and Problem Statement
 
@@ -32,7 +32,7 @@ Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelin
 | **eslint** | Linting — code style and quality enforcement |
 | **jest** | Testing — unit and integration test runner |
 
-All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root MUST define a `.mise.toml` that pins at least Node.js and pnpm. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../platform/017-tool-execution-and-scripting.md). Calling project tools directly in docs, CI, or daily workflows instead of `make <target>` is not allowed.
+All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root MUST define a `.mise.toml` that pins at least Node.js and pnpm. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-304](../platform/304-tool-execution-and-scripting.md). Calling project tools directly in docs, CI, or daily workflows instead of `make <target>` is not allowed.
 
 #### ESLint
 
@@ -48,7 +48,7 @@ When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `modu
 
 #### Coverage
 
-Jest must enforce 80% line and branch coverage, following [agentme-edr-004](004-unit-test-requirements.md). Configure thresholds in `lib/jest.config.js`:
+Jest must enforce 80% line and branch coverage, following [agentme-edr-122](122-unit-test-requirements.md). Configure thresholds in `lib/jest.config.js`:
 
 ```js
 coverageThreshold: {
@@ -82,7 +82,7 @@ Builds that miss the threshold MUST NOT be merged.
 │   ├── dist/              # compiled files and packed .tgz artifacts
 │   └── src/               # all TypeScript source files
 │       ├── index.ts       # public API re-exports from app/
-│       ├── adapters/      # I/O boundary layer (following agentme-edr-026)
+│       ├── adapters/      # I/O boundary layer (following agentme-edr-126)
 │       │   ├── cli/       # inbound: CLI bootstrap and entry point
 │       │   ├── http/      # inbound: HTTP server bootstrap and handlers
 │       │   └── connectors/ # outbound: one folder per external resource
@@ -101,7 +101,7 @@ Builds that miss the threshold MUST NOT be merged.
 
 The root `Makefile` delegates every target to `/lib` then `/examples` in sequence. Parent Makefiles should call child Makefiles directly, and each module Makefile is responsible for running its actual tool commands through `mise exec --`.
 
-Internal source code MUST be organized following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities). The public API entry point (`index.ts`) re-exports from `app/`.
+Internal source code MUST be organized following [agentme-edr-126](126-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities). The public API entry point (`index.ts`) re-exports from `app/`.
 
 When a repository contains multiple JavaScript/TypeScript packages, each package MUST live in its own module folder such as `lib/my-package/` or `services/my-service/`, each with its own `Makefile`, `README.md`, `dist/`, and `.cache/`.
 
@@ -154,7 +154,7 @@ The examples folder MUST exist for any libraries and utilities that are publishe
 
 ## References
 
-- [agentme-edr-004](004-unit-test-requirements.md) — Coverage and unit-test baseline
-- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Internal adapter/application layer separation for applications
-- [001-create-javascript-project](skills/001-create-javascript-project/SKILL.md) — scaffolds a new project following this structure
+- [agentme-edr-122](122-unit-test-requirements.md) — Coverage and unit-test baseline
+- [agentme-edr-126](126-pragmatic-hexagonal-architecture.md) — Internal adapter/application layer separation for applications
+- [050-create-javascript-project](skills/050-create-javascript-project/SKILL.md) — scaffolds a new project following this structure
 

package/.xdrs/agentme/edrs/application/{010-golang-project-tooling.md → 102-golang-project-tooling.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-010-go-project-tooling-and-structure
+name: agentme-edr-policy-102-go-project-tooling-and-structure
 description: Defines the standard Go project toolchain, layout, and Makefile workflow using Mise for agentme-based projects. Use when scaffolding or reviewing Go projects.
 apply-to: Go projects
 valid-from: 2026-05-25
 ---
 
-# agentme-edr-policy-010: Go project tooling and structure
+# agentme-edr-policy-102: Go project tooling and structure
 
 ## Context and Problem Statement
 
@@ -30,7 +30,7 @@ A predictable layout and minimal external tooling keep Go projects approachable,
 | **golangci-lint** | Linting — aggregates many linters in one fast run; configured via `.golangci.yml` |
 | **monotag** | Version tagging from git history for the `publish` target |
 
-All commands MUST be run exclusively through the Makefile and MUST NOT be called ad-hoc. The project root **MUST** define a `.mise.toml` that pins `go`, `golangci-lint`, and any other Go-related CLIs used by the project. Contributors and CI **MUST** bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe **MUST** execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../platform/017-tool-execution-and-scripting.md).
+All commands MUST be run exclusively through the Makefile and MUST NOT be called ad-hoc. The project root **MUST** define a `.mise.toml` that pins `go`, `golangci-lint`, and any other Go-related CLIs used by the project. Contributors and CI **MUST** bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe **MUST** execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-304](../platform/304-tool-execution-and-scripting.md).
 Direct installation of project-required Go CLIs with `go install ...@latest` as a repair step is **NOT** allowed unless an XDR for that repository explicitly permits it.
 
 #### Project structure
@@ -47,7 +47,7 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 ├── main.go                    # binary entry point — argument dispatch only, no logic
 ├── .cache/                    # GOCACHE, GOMODCACHE, golangci-lint cache, coverage
 ├── dist/                      # built binaries and packaged outputs
-├── adapters/                  # I/O boundary layer (following agentme-edr-026)
+├── adapters/                  # I/O boundary layer (following agentme-edr-126)
 │   ├── cli/                   # inbound: CLI wiring — flag parsing, output formatting
 │   │   └── *.go               # subfolders per feature only when complexity warrants it
 │   ├── http/                  # inbound: HTTP server bootstrap and handlers
@@ -73,7 +73,7 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 
 **Key layout rules:**
 
-- Internal source code is organized following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
+- Internal source code is organized following [agentme-edr-126](126-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
 - One Go module per project (`go.mod` at the project root). In a monorepo, each Go project has its own `go.mod` in its subdirectory. No nested modules within a single project unless explicitly justified.
 - In a multi-module repository, each Go module MUST live in its own folder root with its own `Makefile`, `README.md`, `dist/`, and `.cache/`.
 - `main.go` is solely an argument dispatcher — it reads `os.Args[1]` and delegates to an `adapters/cli/<feature>/Run*()` function. No domain logic lives in `main.go`.
@@ -178,5 +178,5 @@ Use the standard library `flag` package for CLI flags. Each `adapters/cli/<featu
 
 ## References
 
-- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Defines the adapter/application separation that this layout follows
-- [003-create-golang-project](skills/003-create-golang-project/SKILL.md) — scaffolds a new Go project following this structure
+- [agentme-edr-126](126-pragmatic-hexagonal-architecture.md) — Defines the adapter/application separation that this layout follows
+- [051-create-golang-project](skills/051-create-golang-project/SKILL.md) — scaffolds a new Go project following this structure

package/.xdrs/agentme/edrs/application/{014-python-project-tooling.md → 103-python-project-tooling.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-014-python-project-tooling-and-structure
+name: agentme-edr-policy-103-python-project-tooling-and-structure
 description: Defines the standard Python project toolchain, layout, and Makefile workflow using Mise, uv, ruff, ty, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
 apply-to: Python projects
 valid-from: 2026-05-25
 ---
 
-# agentme-edr-policy-014: Python project tooling and structure
+# agentme-edr-policy-103: Python project tooling and structure
 
 ## Context and Problem Statement
 
@@ -36,7 +36,7 @@ A single dependency manager, isolated package internals under `lib/`, and a stan
 
 All routine commands MUST run through the project `Makefile`. MUST NOT call `uv`, `ruff`, `pytest`, or `ty` directly in docs, CI, or daily development workflows.
 
-The repository root MUST define a `.mise.toml` that pins Python and uv. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../platform/017-tool-execution-and-scripting.md). Using routine project CLI commands directly outside the Makefile contract is not allowed.
+The repository root MUST define a `.mise.toml` that pins Python and uv. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-304](../platform/304-tool-execution-and-scripting.md). Using routine project CLI commands directly outside the Makefile contract is not allowed.
 
 The root `.venv/` is the canonical environment location for both the library and all examples. Subdirectory commands MUST set `UV_PROJECT_ENVIRONMENT` to the workspace root `.venv/` instead of creating nested virtual environments.
 
@@ -71,7 +71,7 @@ Tools MUST NOT write cache or state files to the project root, `src/`, `tests/`,
 │   ├── src/
 │   │   └── <package_name>/
 │   │       ├── __init__.py
-│   │       ├── adapters/       # I/O boundary layer (following agentme-edr-026)
+│   │       ├── adapters/       # I/O boundary layer (following agentme-edr-126)
 │   │       │   ├── cli/        # inbound: CLI bootstrap and entry point
 │   │       │   ├── http/       # inbound: HTTP server bootstrap
 │   │       │   └── connectors/ # outbound: one folder per external resource
@@ -96,9 +96,9 @@ Keep the repository root clean: source code, tests, distribution artifacts, and
 
 Use the `lib/src/` layout for import safety and packaging clarity. Keep tests under `lib/tests/` and shared test setup in `lib/tests/conftest.py`. Do not introduce `requirements.txt`, `setup.py`, `setup.cfg`, `tox.ini`, `ruff.toml`, or `ty.toml` by default; keep project metadata and tool configuration in `lib/pyproject.toml`.
 
-Internal source code MUST be organized following [agentme-edr-026](026-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
+Internal source code MUST be organized following [agentme-edr-126](126-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
 
-Libraries and shared utilities MUST include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../governance/007-project-quality-standards.md). Each example directory is its own Python project with its own `pyproject.toml`, and examples MUST import the library as a consumer would rather than reaching back into `lib/src/` with relative imports. Local example verification MUST install the wheel built into `lib/dist/`; do not use editable or path-based dependencies back to `lib/`.
+Libraries and shared utilities MUST include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-501](../governance/501-project-quality-standards.md). Each example directory is its own Python project with its own `pyproject.toml`, and examples MUST import the library as a consumer would rather than reaching back into `lib/src/` with relative imports. Local example verification MUST install the wheel built into `lib/dist/`; do not use editable or path-based dependencies back to `lib/`.
 
 Python keeps unit tests under `lib/tests/` by default because that remains the more common and maintainable convention for typed/package-based projects than co-locating tests beside every source file. Integration tests belong in `lib/tests_integration/`, and benchmark harnesses belong in `lib/tests_benchmark/` when they are more than a single micro-benchmark helper.
 
@@ -159,7 +159,7 @@ Adjust `target-version` to match the project's minimum supported Python version.
 
 ty MUST run on every lint pass. The default rule set is the minimum baseline; projects may enable stricter rules as the codebase matures.
 
-Pytest coverage MUST fail below 80% line and branch coverage, following [agentme-edr-004](004-unit-test-requirements.md).
+Pytest coverage MUST fail below 80% line and branch coverage, following [agentme-edr-122](122-unit-test-requirements.md).
 
 #### Makefile targets
 
@@ -198,7 +198,7 @@ The root `Makefile` is the only contract for CI and contributors. It delegates l
 | `dev` | Same as `run`, optionally with repository-specific dev defaults |
 | `publish` | `mise exec -- uv publish --project .` after versioning and packaging are complete |
 
-The root `Makefile` MUST remain the only contract for CI and contributors, in line with [agentme-edr-008](../platform/008-common-targets.md).
+The root `Makefile` MUST remain the only contract for CI and contributors, in line with [agentme-edr-303](../platform/303-common-targets.md).
 
 ## Considered Options
 
@@ -209,7 +209,7 @@ The root `Makefile` MUST remain the only contract for CI and contributors, in li
 
 ## References
 
-- [agentme-edr-004](004-unit-test-requirements.md) - Coverage and unit-test baseline
-- [agentme-edr-007](../governance/007-project-quality-standards.md) - Examples and quality requirements
-- [agentme-edr-008](../platform/008-common-targets.md) - Standard Makefile target names
-- [005-create-python-project](skills/005-create-python-project/SKILL.md) - Scaffold a project following this EDR
+- [agentme-edr-122](122-unit-test-requirements.md) - Coverage and unit-test baseline
+- [agentme-edr-501](../governance/501-project-quality-standards.md) - Examples and quality requirements
+- [agentme-edr-303](../platform/303-common-targets.md) - Standard Makefile target names
+- [052-create-python-project](skills/052-create-python-project/SKILL.md) - Scaffold a project following this EDR

package/.xdrs/agentme/edrs/application/{015-cli-tool-standards.md → 104-cli-tool-standards.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-015-cli-tool-standards
+name: agentme-edr-policy-104-cli-tool-standards
 description: Defines how distributable CLI tools should separate command handling from library logic and expose consistent command behavior. Use when designing or reviewing CLI interfaces.
 apply-to: Projects with distributable CLI tools
 valid-from: 2026-05-25
 ---
 
-# agentme-edr-policy-015: CLI tool standards
+# agentme-edr-policy-104: CLI tool standards
 
 ## Context and Problem Statement
 
@@ -34,7 +34,7 @@ This keeps the user-facing command predictable while preserving a clean library
 
 #### 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).
+- Structure the software as `cli -> app` — the CLI adapter delegates to the application layer, following [agentme-edr-126](126-pragmatic-hexagonal-architecture.md). For unit testing the application layer and mocking outbound connectors, follow [agentme-edr-126 rule `09`](126-pragmatic-hexagonal-architecture.md#09-unit-testing-and-mocking-strategy).
 - 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.
@@ -53,7 +53,7 @@ This keeps the user-facing command predictable while preserving a clean library
 #### 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](../platform/027-environment-variable-configuration.md) for when `.env` values should be referenced from within that file.
+- When configuration becomes long, nested, or repetitive, use a YAML config file instead of pushing all values into flags. See [agentme-edr-305](../platform/305-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`.
@@ -87,7 +87,7 @@ This keeps the user-facing command predictable while preserving a clean library
 - 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.
 - 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-101](101-javascript-project-tooling.md), [agentme-edr-102](102-golang-project-tooling.md), and [agentme-edr-103](103-python-project-tooling.md).
 
 ## Considered Options
 
@@ -98,11 +98,11 @@ This keeps the user-facing command predictable while preserving a clean library
 
 ## References
 
-- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) - Defines the adapter/application separation that the CLI layer follows
-- [agentme-edr-003](003-javascript-project-tooling.md) - JavaScript project packaging and structure
-- [agentme-edr-007](../governance/007-project-quality-standards.md) - README and examples baseline
-- [agentme-edr-008](../platform/008-common-targets.md) - Standard command names for project entry points
-- [agentme-edr-009](009-error-handling.md) - Process error signaling and error handling expectations
-- [agentme-edr-010](010-golang-project-tooling.md) - Go CLI structure and verbose logging baseline
-- [agentme-edr-014](014-python-project-tooling.md) - Python packaging and CLI entry-point guidance
-- [agentme-edr-027](../platform/027-environment-variable-configuration.md) - Environment variable configuration files; defines how `.env` values are referenced from YAML config files
+- [agentme-edr-126](126-pragmatic-hexagonal-architecture.md) - Defines the adapter/application separation that the CLI layer follows
+- [agentme-edr-101](101-javascript-project-tooling.md) - JavaScript project packaging and structure
+- [agentme-edr-501](../governance/501-project-quality-standards.md) - README and examples baseline
+- [agentme-edr-303](../platform/303-common-targets.md) - Standard command names for project entry points
+- [agentme-edr-123](123-error-handling.md) - Process error signaling and error handling expectations
+- [agentme-edr-102](102-golang-project-tooling.md) - Go CLI structure and verbose logging baseline
+- [agentme-edr-103](103-python-project-tooling.md) - Python packaging and CLI entry-point guidance
+- [agentme-edr-305](../platform/305-environment-variable-configuration.md) - Environment variable configuration files; defines how `.env` values are referenced from YAML config files

package/.xdrs/agentme/edrs/application/{002-coding-best-practices.md → 121-coding-best-practices.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-002-coding-best-practices
+name: agentme-edr-policy-121-coding-best-practices
 description: Defines cross-language coding practices for keeping code readable, modular, and synchronized with tests and documentation. Apply across projects adopting agentme engineering standards.
 apply-to: All software projects
 valid-from: 2026-05-25
 ---
 
-# agentme-edr-policy-002: Coding best practices
+# agentme-edr-policy-121: Coding best practices
 
 ## Context and Problem Statement
 
@@ -116,4 +116,4 @@ Types used in only **one** file MUST be declared in that same file. Move a type
 
 #### 06-keep-test-files-next-to-source
 
-Test files MUST be placed beside the source file they cover, following the co-location and naming conventions defined in [agentme-edr-004 rule 04](004-unit-test-requirements.md). For Rust, use inline `#[cfg(test)]` modules instead of a separate test file.
+Test files MUST be placed beside the source file they cover, following the co-location and naming conventions defined in [agentme-edr-122 rule 04](122-unit-test-requirements.md). For Rust, use inline `#[cfg(test)]` modules instead of a separate test file.

package/.xdrs/agentme/edrs/application/{004-unit-test-requirements.md → 122-unit-test-requirements.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-004-unit-test-requirements
+name: agentme-edr-policy-122-unit-test-requirements
 description: Defines unit test requirements for assertions, offline execution, coverage, shared setup, and real-code preference. Use when writing or reviewing tests.
 apply-to: All projects with unit tests
 valid-from: 2026-05-25
 ---
 
-# agentme-edr-policy-004: Unit test requirements
+# agentme-edr-policy-122: Unit test requirements
 
 ## Context and Problem Statement
 

package/.xdrs/agentme/edrs/application/{009-error-handling.md → 123-error-handling.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-009-error-handling
+name: agentme-edr-policy-123-error-handling
 description: Defines error handling practices for catching, propagating, surfacing, and testing failures consistently across projects. Use when implementing interfaces and failure paths.
 apply-to: All software projects
 valid-from: 2026-05-25
 ---
 
-# agentme-edr-policy-009: Error handling
+# agentme-edr-policy-123: Error handling
 
 ## Context and Problem Statement
 

package/.xdrs/agentme/edrs/application/{022-secrets-management.md → 124-secrets-management.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-022-secrets-management
+name: agentme-edr-policy-124-secrets-management
 description: Defines how secrets (API keys, passwords, tokens, credentials, private certificates) must be stored, fetched, and provisioned. Use when implementing secret handling in any language or deployment target.
 apply-to: All software projects handling secrets
 valid-from: 2026-05-28
 ---
 
-# agentme-edr-policy-022: Secrets management
+# agentme-edr-policy-124: Secrets management
 
 ## Context and Problem Statement
 
@@ -45,7 +45,7 @@ During local development, secrets MUST be stored and retrieved using the native
 | JavaScript/TypeScript | `cross-keychain` |
 | Go | `go-keyring` |
 
-The "group" (service name) defaults to the module name. The secret identifier should match the ID used in the cloud secret manager for consistency.
+The "group" (service name) defaults to the module name. The secret identifier SHOULD match the ID used in the cloud secret manager for consistency.
 
 ---
 
@@ -164,5 +164,5 @@ In library code (Python, JS/TS, Go), continue using the cross-platform libraries
 
 ## References
 
-- [agentme-edr-008](../platform/008-common-targets.md) - Common development script names (defines Makefile target conventions)
-- [agentme-edr-009](009-error-handling.md) - Error handling (governs how the fallback exception should be raised)
+- [agentme-edr-303](../platform/303-common-targets.md) - Common development script names (defines Makefile target conventions)
+- [agentme-edr-123](123-error-handling.md) - Error handling (governs how the fallback exception should be raised)

package/.xdrs/agentme/edrs/application/{023-coding-abstraction-practices.md → 125-coding-abstraction-practices.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-023-coding-abstraction-practices
-description: Defines when abstractions (functions, classes, wrappers, factories) are justified and when they must be avoided. Tightly related to agentme-edr-policy-002-coding-best-practices.
+name: agentme-edr-policy-125-coding-abstraction-practices
+description: Defines when abstractions (functions, classes, wrappers, factories) are justified and when they must be avoided. Tightly related to agentme-edr-policy-121-coding-best-practices.
 apply-to: All software projects
 valid-from: 2026-05-29
 ---
 
-# agentme-edr-policy-023: Coding abstraction practices
+# agentme-edr-policy-125: Coding abstraction practices
 
 ## Context and Problem Statement
 

package/.xdrs/agentme/edrs/application/{026-pragmatic-hexagonal-architecture.md → 126-pragmatic-hexagonal-architecture.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-026-pragmatic-hexagonal-architecture
+name: agentme-edr-policy-126-pragmatic-hexagonal-architecture
 description: Defines a pragmatic variant of Hexagonal Architecture for organizing application source code into Adapters (inbound/outbound I/O boundaries) and Application (business logic) layers, with explicit naming conventions and folder structure. Use when designing or reviewing the internal layout of application modules.
 apply-to: All application projects
 valid-from: 2026-05-28
 ---
 
-# agentme-edr-policy-026: Pragmatic hexagonal architecture
+# agentme-edr-policy-126: Pragmatic hexagonal architecture
 
 ## Context and Problem Statement
 
@@ -56,7 +56,7 @@ Adapters MUST follow these naming conventions:
 - No global variables, no direct environment variable access in `app/` or `shared/`
 - Business logic with well-defined input/output behavior
 - 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
+- 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
 
@@ -102,7 +102,7 @@ mysystem/
 #### 06-bootstrap-and-entry-points
 
 - Each inbound adapter folder (`cli/`, `http/`, `grpc/`, etc.) MUST contain the bootstrap and entry point for that interface
-- The project root Makefile must have targets to run the different inbound interfaces following [agentme-edr-008](../platform/008-common-targets.md) extension conventions (e.g. `run-http`, `run-grpc`)
+- The project root Makefile MUST have targets to run the different inbound interfaces following [agentme-edr-303](../platform/303-common-targets.md) extension conventions (e.g. `run-http`, `run-grpc`)
 - Bootstrap code lives in the adapter that receives inbound requests, not in a separate wiring layer
 
 #### 07-minimum-complexity-threshold
@@ -133,7 +133,7 @@ Inbound adapters (`cli/`, `http/`, `grpc/`) are entry points and do not need to
 
 #### 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-052](052-ai-test-types-taxonomy.md) rule `02`), define it in a dedicated `_mock` file rather than inline.
+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-152](152-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)
@@ -149,7 +149,7 @@ When a mock implementation needs to be **reused across multiple tests or importe
 | `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](004-unit-test-requirements.md) rule `04`:
+**Placement:** follows the project's test file placement convention per [agentme-edr-122](122-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`)
 
@@ -160,6 +160,6 @@ When a mock implementation needs to be **reused across multiple tests or importe
 ## 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](002-coding-best-practices.md) — File size limits and code organization practices that complement this architecture
-- [agentme-edr-004](004-unit-test-requirements.md) — Rule `04`: test file placement convention per language (governs `_mock` file placement in rule `10`)
-- [agentme-edr-052](052-ai-test-types-taxonomy.md) — Rule `02`: `mock_fixtures` golden dataset envelope that drives `_mock` usage in eval scripts
+- [agentme-edr-121](121-coding-best-practices.md) — File size limits and code organization practices that complement this architecture
+- [agentme-edr-122](122-unit-test-requirements.md) — Rule `04`: test file placement convention per language (governs `_mock` file placement in rule `10`)
+- [agentme-edr-152](152-ai-test-types-taxonomy.md) — Rule `02`: `mock_fixtures` golden dataset envelope that drives `_mock` usage in eval scripts

package/.xdrs/agentme/edrs/application/127-external-system-adapter-skills.md

@@ -0,0 +1,93 @@
+---
+name: agentme-edr-policy-127-external-system-adapter-skills
+description: Defines how agents must approach reading or mutating data in external systems (priority order, credential handling, browser configuration, mutation safety) and what constraints apply when encoding that knowledge as reusable adapter skills. Use when automating any interaction with an external system or when authoring adapter skills for a system.
+apply-to: All automation tasks that read from or write to external systems; all adapter skill authoring
+valid-from: 2026-08-04
+---
+
+# agentme-edr-policy-127: External system adapter skills
+
+## Context and Problem Statement
+
+When automating tasks that interact with external systems (SaaS tools, REST APIs, internal platforms), agents face recurring decisions: which integration channel to use, how to handle credentials, and how to capture accumulated system knowledge so it can be reused.
+
+How should agents approach external system interaction, and how should that knowledge be encoded as reusable skills?
+
+## Decision Outcome
+
+Use a priority-ordered integration approach — always leveraging the user's existing session context — and encode system-specific interaction knowledge as business-logic-free adapter skills.
+
+Rules 01–04 govern **runtime behavior** (an agent executing a task against an external system). Rule 05 governs **authoring** (a skill author writing an adapter skill).
+
+### Details
+
+#### 01-approach-priority-order
+
+Agents MUST attempt the following approaches in order, stopping at the first that is feasible:
+
+1. **API via curl** — If the system exposes an API, interact with it directly using the `curl` CLI. Another HTTP client MAY be used only when `curl` is insufficient for the specific operation (e.g. streaming, binary upload).
+2. **Playwright UI scraping** — If no API is available or the user cannot provide an API credential, use the `playwright` CLI (via `npx -y --package=@playwright/cli@latest playwright-cli`) to interact with the system's UI using the user's existing browser profile (see rule 03). Another browser automation tool MUST NOT be used.
+3. **Git clone** — If the target data is read-only and lives in a git repository, clone the repository locally and read from the local path. For private repositories, follow [agentme-edr-124](124-secrets-management.md) to retrieve the PAT or SSH key from the native keychain.
+4. **Local folder** — As a last resort, ask the user to provide a path to a local folder containing the relevant data.
+
+When a higher-priority approach is attempted and fails, the failure reason MUST be stated before trying the next approach.
+
+#### 02-api-credential-handling
+
+API credentials (keys, tokens, passwords) MUST be stored and retrieved using the native OS keychain following [agentme-edr-124](124-secrets-management.md). Agents MUST NOT hardcode, log, or persist credentials to disk. When a required credential is absent, agents MUST prompt the user to store it via the `setup-secrets` Makefile target before proceeding.
+
+#### 03-playwright-browser-config
+
+When using Playwright, agents MUST run the `playwright` CLI via `npx -y --package=@playwright/cli@latest playwright-cli` and MUST use the user's existing browser profile to preserve SSO sessions, CA certificates, cookies, and extensions that the target system depends on.
+
+- MUST use `--user-data-dir` pointing to the user's active browser profile directory, or attach to a running browser instance via CDP.
+- MUST NOT launch a blank, incognito, or freshly provisioned profile.
+- MUST keep the browser window visible throughout the interaction so the user can follow and intervene.
+- SHOULD prefer CDP attachment to an already-running browser over launching a new instance, when the browser is already open.
+
+When the `playwright` CLI is technically insufficient for a required integration capability (e.g., network response interception, which the CLI does not expose), the Playwright Node.js API MAY be used instead. The justification MUST be documented in a `## Conflicts` section within the adapter skill, following the same format used in Policy conflict declarations (citing the policy rule being overridden, the reason, and the mitigations applied).
+
+#### 04-human-in-the-loop-before-mutations
+
+Before executing any write, mutate, or delete operation on an external system, agents MUST present a plain-language summary containing at minimum:
+
+- **System:** name and environment (e.g. "ServiceNow production")
+- **Operation:** what action will be taken
+- **Fields/values:** which fields will be changed and to what values
+- **Estimated impact:** a brief statement of what the change will affect
+
+Agents MUST wait for explicit user confirmation before proceeding. Read-only and query operations do not require confirmation.
+
+#### 05-adapter-skill-no-business-logic
+
+Adapter skills MUST be pure I/O bridges between the agent and the external system. They MUST NOT contain business rules, domain decisions, validation logic, or application-layer concerns, which belong in the application or workflow layer following [agentme-edr-126](126-pragmatic-hexagonal-architecture.md).
+
+An adapter skill SHOULD provide only: session setup, navigation, field interaction, and response parsing specific to the target system.
+
+#### 06-connector-skill-naming
+
+A skill that serves as a base to connect to an external system via API, UI scraping, or file access MUST have a name ending with `-connector` (e.g. `servicenow-connector`, `sap-api-connector`).
+
+#### 07-connector-known-issues-section
+
+Every connector skill MUST contain a `## Known Issues` section documenting previous problems encountered when using that connector and how to overcome them. This section is read by running agents at execution time to self-correct without human intervention. Each entry SHOULD follow this structure:
+
+- **Symptom:** observable sign that the problem has occurred
+- **Cause:** brief explanation of the root cause
+- **Fix:** concrete steps the agent MUST take to resolve the issue
+
+---
+
+#### guidance
+
+> Non-normative. The following is illustrative guidance, not a requirement.
+
+Adapter skills for a given system benefit from layering so that knowledge at each level can be activated and reused independently:
+
+- **Base skill (connector)** — Session setup, authentication, system overview, and top-level screen or API structure. MUST follow the `-connector` naming rule (rule 06) and MUST include a `## Known Issues` section (rule 07). This skill gives the agent enough context to orient itself in the system. Examples: `servicenow-connector` (login, workspace layout, navigation patterns), `sap-api-connector` (base URL, API key retrieval, OpenAPI spec location).
+- **Domain skill** — A specific feature area, building on the base skill. Examples: `servicenow-incidents` (incident concept, workspace, field structure), `sap-api-mutations` (confirmation procedures, human-in-the-loop steps per rule 04).
+- **Operation skill** — A specific action within a domain, building on the domain skill. Examples: `servicenow-incidents-change` (open an incident, edit fields, click action buttons, handle known errors), `servicenow-vulnerabilities` (filter, triage, export).
+
+The depth of the hierarchy is discretionary. A simple system may need only a base skill. Complex systems benefit from the full three-layer structure. Higher-level skills SHOULD activate their lower-level dependencies explicitly at the start of their instructions.
+
+When creating adapter skills for a new system, document the chosen integration approach (rule 01) in the skill's frontmatter description, follow the `-connector` naming convention (rule 06) for the base skill, and populate the `## Known Issues` section (rule 07) as experience accumulates. All system-specific adapter skills SHOULD be placed in the `_local` scope of the consuming project.

package/.xdrs/agentme/edrs/application/{040-ai-llm-development-standards.md → 141-ai-llm-development-standards.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-040-ai-llm-development-standards
-description: Defines the standard framework, provider configuration, observability approach, and LLM mocking patterns for simple LLM calls in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls using LangChain, manages prompt context, or handles conversation history. For agentic patterns see agentme-edr-041, for workflow patterns see agentme-edr-043.
+name: agentme-edr-policy-141-ai-llm-development-standards
+description: Defines the standard framework, provider configuration, observability approach, and LLM mocking patterns for simple LLM calls in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls using LangChain, manages prompt context, or handles conversation history. For agentic patterns see agentme-edr-142, for workflow patterns see agentme-edr-144.
 apply-to: Python projects that make direct LLM calls, manage prompt context, or handle conversation threads
 valid-from: 2026-06-05
 ---
 
-# agentme-edr-policy-040: AI LLM development standards
+# agentme-edr-policy-141: AI LLM development standards
 
 ## Context and Problem Statement
 
@@ -29,7 +29,7 @@ Three distinct tiers of LLM-based computation are recognized in this policy. Eve
 
 These tiers nest: in general, a Workflow may contain Agent nodes; an Agent uses LLM calls internally. The tier of a component is determined by its outermost controlling structure.
 
-See [agentme-edr-041](041-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-043](043-ai-workflow-development-standards.md) for Workflow implementation standards.
+See [agentme-edr-142](142-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-144](144-ai-workflow-development-standards.md) for Workflow implementation standards.
 
 ### Details
 
@@ -44,7 +44,7 @@ Every component that interacts with an LLM MUST be classified as exactly one of
 **Function calling boundary:**
 
 - A **single** function call decided by the LLM (e.g., "call get_weather(location)") is still an LLM-tier interaction if the function is called once and the result is returned to the user.
-- An **iterative** function-calling loop where the LLM observes results and decides next actions autonomously is an Agent (see [agentme-edr-041](041-ai-agents-development-standards.md)).
+- An **iterative** function-calling loop where the LLM observes results and decides next actions autonomously is an Agent (see [agentme-edr-142](142-ai-agents-development-standards.md)).
 
 #### 02-llm-framework
 
@@ -71,7 +71,7 @@ llm = ChatOpenAI(
 Enable LangChain auto-tracing at every application entry point by calling `mlflow.langchain.autolog()` during startup, before any LLM call is made.
 
 - This captures inputs, outputs, token counts, and latency for every LangChain chain or runnable automatically.
-- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../platform/008-common-targets.md) rule `09-ai-project-dev-targets`.
+- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-303](../platform/303-common-targets.md) rule `09-ai-project-dev-targets`.
 
 #### 04-unit-test-mocking
 
@@ -213,11 +213,11 @@ Return a JSON object with:
 
 ## References
 
-- [agentme-edr-041](041-ai-agents-development-standards.md) — Agent implementation standards (deepagents, tool-invocation loops)
-- [agentme-edr-043](043-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, MLflow run-level tracking)
-- [agentme-edr-004](004-unit-test-requirements.md) — Unit test requirements including external API mocking guidance
-- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
-- [agentme-edr-007](../governance/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
-- [agentme-edr-051](051-ai-eval-core-standards.md) — AI eval core standards: eval folder structure (rule `01`) and LLM-as-judge binary scoring contract (rule `02`)
-- [agentme-edr-053](053-ai-eval-script.md) — AI eval script: entry-first loop, `--type` filtering, `mock_fixtures`, and MLflow conventions
-- [agentme-edr-054](054-ai-eval-report-format.md) — AI eval report format: `report-<type>.md` template, Wilson CI, and convergence analysis
+- [agentme-edr-142](142-ai-agents-development-standards.md) — Agent implementation standards (deepagents, tool-invocation loops)
+- [agentme-edr-144](144-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, MLflow run-level tracking)
+- [agentme-edr-122](122-unit-test-requirements.md) — Unit test requirements including external API mocking guidance
+- [agentme-edr-103](103-python-project-tooling.md) — Python project tooling and structure
+- [agentme-edr-501](../governance/501-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
+- [agentme-edr-151](151-ai-eval-standards.md) — AI eval core standards: eval folder structure (rule `01`) and LLM-as-judge binary scoring contract (rule `02`)
+- [agentme-edr-153](153-ai-eval-script.md) — AI eval script: entry-first loop, `--type` filtering, `mock_fixtures`, and MLflow conventions
+- [agentme-edr-154](154-ai-eval-report-format.md) — AI eval report format: `report-<type>.md` template, Wilson CI, and convergence analysis