agentme 0.10.0 → 0.12.0

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

@@ -0,0 +1,112 @@
+---
+name: agentme-edr-policy-021-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-021: Pragmatic hexagonal architecture
+
+## Context and Problem Statement
+
+Applications often mix business logic with infrastructure concerns (database access, HTTP handling, environment variable reading), making code hard to test, refactor, and reuse.
+
+How should application source code be organized to separate business logic from infrastructure while avoiding unnecessary abstraction layers?
+
+## Decision Outcome
+
+**Organize application source code into three conceptual layers — External (not in codebase), Adapters (inbound/outbound I/O boundaries), and Application (business logic exposed as typed library interfaces) — following a pragmatic variant of Hexagonal Architecture that avoids unnecessary abstractions.**
+
+### Details
+
+#### 01-three-layer-separation
+
+Every application is conceptually divided into three layers:
+
+| Layer | Description |
+|-------|-------------|
+| **External** | Systems outside the codebase boundary (databases, third-party APIs, message brokers, filesystems, users) |
+| **Adapters** | Bridge between External and Application — translate external protocols into application calls and vice versa |
+| **Application** | Business logic that delegates I/O to adapters |
+
+#### 02-adapter-naming-conventions
+
+**Inbound adapters** receive external requests or events and trigger application logic. Each gets a flat folder under `adapters/`:
+
+- `cli/` — command-line interface entry point
+- `http/` — HTTP/REST server
+- `grpc/` — gRPC server
+- `ws/` — WebSocket server
+- `kafka/` — Kafka consumer
+- `mqtt/` — MQTT subscriber
+- Additional inbound adapters are allowed with descriptive names
+
+**Outbound adapters** are called by the application to reach external systems. They live under `adapters/connectors/` with one subfolder per external resource, named descriptively:
+
+- e.g.: `stripe-api/`, `config-file/`, `s3-datalake/`, `whatsapp/`, `postgres/`, `redis-cache/`
+
+**Clarification:** "inbound" means the adapter triggers application logic in response to an external stimulus. "Outbound" means the application calls the adapter to interact with an external system.
+
+#### 03-application-layer-rules
+
+- Expose functionality as typed library interfaces
+- All inputs must be explicitly passed as typed parameters
+- 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
+
+#### 04-mandatory-folder-structure
+
+```text
+mysystem/
+  Makefile             # targets to run different inbound interfaces (e.g. run-http, run-cli)
+  src/
+    adapters/          # mandatory
+      cli/             # if CLI exists — bootstrap/entry point for CLI
+      http/            # if HTTP server exists — bootstrap/entry point for HTTP
+      grpc/            # if gRPC exists
+      connectors/      # if external resource access exists
+        postgres/      # one folder per external resource
+        stripe-api/
+    app/               # mandatory — core business logic
+      feature1.ts
+      feature-group/   # optional subfolders for grouping
+    shared/            # utilities and functions shared among adapters and app
+      logging.ts
+      errors.ts
+```
+
+`shared/` must contain only infrastructure-agnostic utilities — not business rules or domain logic.
+
+#### 05-pragmatic-coupling
+
+- Application MAY import from Adapters when it simplifies the design
+- Avoid excessive abstractions, interface types, and indirection layers
+- Only introduce interfaces or abstract types when building a framework where the extra complexity demonstrably pays off
+- Prefer concrete implementations over abstract ports — skip the purism of classic Hexagonal Architecture in favor of practicality
+- Some coupling between Application and Adapters is acceptable and expected
+
+#### 06-bootstrap-and-entry-points
+
+- Each inbound adapter folder (`cli/`, `http/`, `grpc/`, etc.) contains 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](../devops/008-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
+
+- Trivial scripts and single-purpose tools (fewer than ~300 lines with a single I/O boundary) MAY skip this layering
+- All other projects MUST use this structure from the start
+
+#### 08-examples-of-data-flow
+
+```text
+HTTP request  →  adapters/http/     →  app/create-user     →  adapters/connectors/postgres/
+CLI command   →  adapters/cli/      →  app/create-dir      →  adapters/connectors/local-fs/
+Kafka message →  adapters/kafka/    →  app/process-event   →  adapters/connectors/stripe-api/
+```
+
+## References
+
+- [agentme-edr-016](../principles/016-cross-language-module-structure.md) — Defines the module-root structure (Makefile, dist/, .cache/) that wraps this internal layout
+- [agentme-edr-002](../principles/002-coding-best-practices.md) — File size limits and code organization practices that complement this architecture

package/.xdrs/agentme/edrs/application/skills/001-create-javascript-project/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: agentme-edr-skill-001-create-javascript-project
 description: >
-  Scaffolds the initial boilerplate structure for a JavaScript/TypeScript library project following
+  Scaffolds the initial boilerplate structure for a JavaScript/TypeScript project following
   the standard tooling and layout defined in agentme-edr-003. Activate this skill when the user
-  asks to create, scaffold, or initialize a new JavaScript or TypeScript library project, npm
+  asks to create, scaffold, or initialize a new JavaScript or TypeScript project, npm
   package, or similar project structure.
 metadata:
   author: flaviostutz
@@ -13,13 +13,14 @@ compatibility: JavaScript/TypeScript, Node.js 18+
 
 ## Overview
 
-Creates a complete JavaScript/TypeScript library project from scratch. The layout keeps the
-published package self-contained in its module root (`lib/`), places runnable consumer examples in
-the sibling `examples/` folder, redirects persistent caches into `.cache/`, and uses Makefiles as
-the only entry points. Boilerplate is derived from the [filedist](https://github.com/flaviostutz/filedist)
-project.
+Creates a complete JavaScript/TypeScript project from scratch. The layout keeps the
+package self-contained in its module root (`lib/`), organizes internal code following
+[agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md) (`adapters/`, `app/`, `shared/`),
+places runnable consumer examples in the sibling `examples/` folder, redirects persistent caches
+into `.cache/`, and uses Makefiles as the only entry points. Boilerplate is derived from the
+[filedist](https://github.com/flaviostutz/filedist) project.
 
-Related EDRs: [agentme-edr-003](../../003-javascript-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
+Related EDRs: [agentme-edr-003](../../003-javascript-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
 
 ## Instructions
 
@@ -82,7 +83,7 @@ dist/
 
 ### Phase 3: Create `lib/`
 
-**`lib/src/index.ts`** — public API entry point:
+**`lib/src/app/hello.ts`** — business logic:
 
 ```typescript
 export const hello = (name: string): string => {
@@ -90,10 +91,10 @@ export const hello = (name: string): string => {
 };
 ```
 
-**`lib/src/index.test.ts`** — co-located unit test:
+**`lib/src/app/hello.test.ts`** — co-located unit test:
 
 ```typescript
-import { hello } from './index';
+import { hello } from './hello';
 
 describe('hello', () => {
   it('should return a greeting', () => {
@@ -102,6 +103,20 @@ describe('hello', () => {
 });
 ```
 
+**`lib/src/index.ts`** — public API re-export from `app/`:
+
+```typescript
+export { hello } from './app/hello';
+```
+
+**`lib/src/adapters/`** — create empty directories for the hexagonal structure:
+
+- `lib/src/adapters/` — inbound adapters (add `cli/`, `http/`, etc. as needed)
+- `lib/src/adapters/connectors/` — outbound adapters (one folder per external resource)
+- `lib/src/shared/` — infrastructure-agnostic utilities
+
+Create a placeholder `.gitkeep` in `lib/src/adapters/` and `lib/src/shared/` so the directories are tracked.
+
 **`lib/Makefile`**:
 
 ```makefile

package/.xdrs/agentme/edrs/application/skills/003-create-golang-project/SKILL.md

@@ -12,9 +12,9 @@ compatibility: Go 1.21+
 
 ## Overview
 
-Creates a complete Go CLI project from scratch, following the layout from [agentme-edr-010](../../010-golang-project-tooling.md). Business logic lives in named feature packages; CLI wiring lives in `cli/<feature>/`; `main.go` is a thin dispatcher. The module root owns its `Makefile`, `README.md`, `dist/`, and `.cache/` folders.
+Creates a complete Go project from scratch, following the layout from [agentme-edr-010](../../010-golang-project-tooling.md) and [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md). Business logic lives in `app/<feature>/` packages; CLI wiring lives in `adapters/cli/`; outbound integrations live in `adapters/connectors/`; `main.go` is a thin dispatcher. The module root owns its `Makefile`, `README.md`, `dist/`, and `.cache/` folders.
 
-Related EDRs: [agentme-edr-010](../../010-golang-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
+Related EDRs: [agentme-edr-010](../../010-golang-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
 
 ## Instructions
 
@@ -67,7 +67,7 @@ import (
 	"fmt"
 	"os"
 
-	cli[Feature] "[module]/cli/[feature]"
+	cli "[module]/adapters/cli"
 )
 
 func main() {
@@ -78,7 +78,7 @@ func main() {
 
 	switch os.Args[1] {
 	case "[subcommand]":
-		cli[Feature].Run(os.Args)
+		cli.Run[Feature](os.Args)
 	default:
 		fmt.Printf("Unknown command: %s\n", os.Args[1])
 		fmt.Println("Usage: [binary] [[feature]]")
@@ -216,7 +216,7 @@ coverage.out
 
 ### Phase 3: Create the feature package
 
-**`[feature]/[feature].go`** (replace `[feature]`, `[Feature]`):
+**`app/[feature]/[feature].go`** (replace `[feature]`, `[Feature]`):
 
 ```go
 package [feature]
@@ -246,7 +246,7 @@ func Run(opts Options) (Result, error) {
 }
 ```
 
-**`[feature]/[feature]_test.go`** (replace `[feature]`, `[Feature]`):
+**`app/[feature]/[feature]_test.go`** (replace `[feature]`, `[Feature]`):
 
 ```go
 package [feature]
@@ -267,12 +267,12 @@ func Test[Feature]Run(t *testing.T) {
 
 ---
 
-### Phase 4: Create the CLI package
+### Phase 4: Create the CLI adapter
 
-**`cli/[feature]/[feature].go`** (replace `[module]`, `[feature]`, `[Feature]`, `[subcommand]`):
+**`adapters/cli/[feature].go`** (replace `[module]`, `[feature]`, `[Feature]`, `[subcommand]`):
 
 ```go
-package cli[Feature]
+package cli
 
 import (
 	"flag"
@@ -280,11 +280,11 @@ import (
 	"os"
 
 	"github.com/sirupsen/logrus"
-	"[module]/[feature]"
+	"[module]/app/[feature]"
 )
 
-// Run parses CLI flags for the [subcommand] command and calls the domain package.
-func Run(args []string) {
+// Run[Feature] parses CLI flags for the [subcommand] command and calls the domain package.
+func Run[Feature](args []string) {
 	fs := flag.NewFlagSet("[subcommand]", flag.ExitOnError)
 	verbose := fs.Bool("verbose", false, "Show verbose logs during processing")
 
@@ -309,6 +309,21 @@ func Run(args []string) {
 }
 ```
 
+**`shared/logging.go`** (optional, scaffold if needed):
+
+```go
+package shared
+
+import "github.com/sirupsen/logrus"
+
+// SetupLogging configures the global log level.
+func SetupLogging(verbose bool) {
+	if verbose {
+		logrus.SetLevel(logrus.DebugLevel)
+	}
+}
+```
+
 ---
 
 ### Phase 5: Verify and run
@@ -327,8 +342,10 @@ Fix any compile or lint errors before finishing.
 ## Conventions and reminders
 
 - `main.go` dispatches only — no logic.
-- Business logic only in `[feature]/` packages — no flag parsing, no `fmt.Println` for diagnostics.
-- `cli/[feature]/` owns flags, output, and calls domain. No logic here beyond reading flags and printing results.
+- Business logic only in `app/<feature>/` packages — no flag parsing, no `fmt.Println` for diagnostics.
+- `adapters/cli/` owns flag parsing, output formatting, and the wiring between flags and `app/` functions. No business logic lives in adapter packages.
+- Outbound adapters live under `adapters/connectors/` with one subfolder per external resource (e.g., `postgres/`, `stripe-api/`, `redis-cache/`).
+- `shared/` must contain only infrastructure-agnostic utilities — not business rules or domain logic.
 - All tests co-located (`*_test.go` next to the file under test).
 - Use `tests_integration/` for integration flows and `tests_benchmark/` when benchmarks need dedicated harnesses or datasets.
 - Log with `logrus`; never use `fmt.Println` for diagnostic/debug output.

package/.xdrs/agentme/edrs/application/skills/005-create-python-project/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: agentme-edr-skill-005-create-python-project
 description: >
-  Scaffolds the initial boilerplate structure for a Python library or CLI project following the
-  standard tooling and layout defined in agentme-edr-014. Activate this skill when the user asks
-  to create, scaffold, or initialize a new Python package, CLI, library, or similar project
-  structure.
+  Scaffolds the initial boilerplate structure for a Python project following the standard tooling
+  and layout defined in agentme-edr-014. Activate this skill when the user asks to create,
+  scaffold, or initialize a new Python package, CLI, or similar project structure.
 metadata:
   author: flaviostutz
   version: "1.0"
@@ -14,11 +13,12 @@ compatibility: Python 3.12+
 ## Overview
 
 Creates a complete Python project from scratch using Mise, `uv`, `pyproject.toml`, Ruff,
-Pyright, Pytest, and Makefiles. The default layout keeps the library self-contained under `lib/`,
-uses a shared root `.venv/`, redirects persistent caches into `.cache/`, and places runnable
-consumer projects under the sibling `examples/` folder.
+ty, Pytest, and Makefiles. The layout keeps the package self-contained under `lib/`,
+organizes internal code following [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
+(`adapters/`, `app/`, `shared/`), uses a shared root `.venv/`, redirects persistent caches into
+`.cache/`, and places runnable consumer projects under the sibling `examples/` folder.
 
-Related EDRs: [agentme-edr-014](../../014-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
+Related EDRs: [agentme-edr-014](../../014-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
 
 ## Instructions
 
@@ -30,7 +30,6 @@ Ask for or infer from context:
 - **Short description** - one sentence
 - **Author** name or GitHub username
 - **Python version** - default `3.13`
-- **Project kind** - `library` or `cli`
 - **Primary entry point** - first module or command name to scaffold
 - **GitHub repo URL** - optional, for project metadata
 - **Confirm target directory** - default: current workspace root
@@ -105,6 +104,7 @@ The root `Makefile` keeps the repository clean by delegating package work to `li
 .venv/
 dist/
 .cache/
+__pycache__/
 ```
 
 **`./README.md`**
@@ -157,13 +157,13 @@ build: install
 lint: install
 	$(MISE) uv run --project . ruff format --check .
 	$(MISE) uv run --project . ruff check .
-	$(MISE) uv run --project . pyright
+	$(MISE) uv run --project . ty check
 	$(MISE) uv run --project . pip-audit
 
 lint-fix: install
 	$(MISE) uv run --project . ruff format .
 	$(MISE) uv run --project . ruff check . --fix
-	$(MISE) uv run --project . pyright
+	$(MISE) uv run --project . ty check
 	$(MISE) uv run --project . pip-audit
 
 test-unit: install
@@ -203,7 +203,7 @@ dev = []
 [dependency-groups]
 dev = [
   "pip-audit>=2.9.0",
-  "pyright>=1.1.400",
+  "ty>=0.1.0",
   "pytest>=8.4.0",
   "pytest-cov>=6.1.0",
   "ruff>=0.11.0",
@@ -214,25 +214,40 @@ requires = ["hatchling>=1.27.0"]
 build-backend = "hatchling.build"
 
 [tool.ruff]
-line-length = 100
+cache-dir = ".cache/ruff"
+output-format = "grouped"
+line-length = 120
 target-version = "py313"
+src = ["src", "tests", "tests_integration"]
+
+[tool.ruff.format]
+docstring-code-format = true
+line-ending = "lf"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "B", "UP"]
+task-tags = ["TODO"]
+select = ["ERA", "FAST", "ANN", "ASYNC", "S", "BLE", "FBT", "B", "A", "COM",
+  "C4", "DTZ", "T10", "DJ", "EM", "EXE", "FIX", "INT", "ISC", "ICN", "LOG", "G",
+  "INP", "PIE", "T20", "PYI", "PT", "Q", "RSE", "RET", "SLF", "SIM", "SLOT", "TID",
+  "TC", "ARG", "PTH", "FLY", "I", "C90", "NPY", "PD", "N", "PERF", "E", "W",
+  "D", "F", "PGH", "PL", "UP", "FURB", "RUF", "TRY"]
+ignore = ["ANN002", "ANN003", "ANN401", "D100", "D101", "D102", "D103", "D104",
+  "D105", "D106", "D107", "COM812", "D203", "D213", "D400", "D401", "D404", "D415", "FIX002"]
+
+[tool.ruff.lint.pycodestyle]
+ignore-overlong-task-comments = true
 
-[tool.pyright]
-include = ["src", "tests"]
-venvPath = ".."
-venv = ".venv"
-typeCheckingMode = "standard"
+[tool.ty]
+src = ["src", "tests"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+python_files = "*_test.py"
 addopts = "-q"
 ```
 
 Use `lib/pyproject.toml` as the single configuration file for the package. Do not add
-`requirements.txt`, `setup.py`, `setup.cfg`, `ruff.toml`, or `pyrightconfig.json` by default.
+`requirements.txt`, `setup.py`, `setup.cfg`, `ruff.toml`, or `ty.toml` by default.
 
 **`lib/README.md`**
 
@@ -267,29 +282,37 @@ make test
 
 ### Phase 4: Create the package and tests inside `lib/`
 
-Create this baseline structure.
+Create this baseline structure following [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md).
 
 **`lib/src/[package_name]/__init__.py`**
 
 ```python
-from .core import hello
+from .app.hello import hello
 
 __all__ = ["hello"]
 ```
 
-**`lib/src/[package_name]/core.py`**
+**`lib/src/[package_name]/app/__init__.py`**
+
+```python
+```
+
+**`lib/src/[package_name]/app/hello.py`**
 
 ```python
 def hello(name: str) -> str:
     return f"Hello, {name}!"
 ```
 
-**`lib/src/[package_name]/__main__.py`**
+**`lib/src/[package_name]/adapters/__init__.py`**
+
+```python
+```
 
-Use this only for CLI-oriented projects.
+**`lib/src/[package_name]/adapters/cli/__init__.py`**
 
 ```python
-from .core import hello
+from [package_name].app.hello import hello
 
 
 def main() -> None:
@@ -300,10 +323,17 @@ if __name__ == "__main__":
     main()
 ```
 
-**`lib/tests/test_core.py`**
+**`lib/src/[package_name]/shared/__init__.py`**
+
+```python
+```
+
+Create empty `adapters/connectors/` directory with a `.gitkeep` for outbound adapters.
+
+**`lib/tests/hello_test.py`**
 
 ```python
-from [package_name].core import hello
+from [package_name].app.hello import hello
 
 
 def test_hello() -> None:
@@ -314,9 +344,9 @@ If two or more test files need shared fixtures, create `lib/tests/conftest.py` a
 
 If the module needs slower end-to-end coverage, place those tests in `lib/tests_integration/`. Put dedicated benchmark harnesses in `lib/tests_benchmark/`.
 
-### Phase 5: Create examples for libraries and utilities
+### Phase 5: Create examples
 
-If the project is a library or shared utility, add an `examples/` directory with one subdirectory per runnable consumer example. Each example must be its own Python project.
+Add an `examples/` directory with one subdirectory per runnable consumer example. Each example must be its own Python project.
 
 **`examples/basic-usage/pyproject.toml`**
 
@@ -355,14 +385,15 @@ After creating the files:
 
 ## Examples
 
-**Input:** "Create a Python library called `event_tools`"
+**Input:** "Create a Python project called `event_tools`"
 - Create `Makefile`, `README.md`, `lib/pyproject.toml`, `lib/Makefile`, `lib/src/event_tools/`, `lib/tests/`, and `examples/`
+- Scaffold `adapters/`, `app/`, `shared/` directories inside `lib/src/event_tools/`
 - Add `lib/README.md`, `.cache/` handling, and install examples from the built wheel in `lib/dist/`
-- Configure `uv`, Ruff, Pyright, Pytest, `pytest-cov`, and `pip-audit`
+- Configure `uv`, Ruff, ty, Pytest, `pytest-cov`, and `pip-audit`
 - Verify with `make lint-fix`, `make test`, and `make build`
 
 **Input:** "Scaffold a Python CLI package"
-- Add `lib/src/<package_name>/__main__.py`
+- Add CLI entry point in `lib/src/<package_name>/adapters/cli/__init__.py`
 - Add `[project.scripts]` in `lib/pyproject.toml` when the command name must differ from the module name
 - Keep the same Makefile and quality checks
 

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

@@ -20,7 +20,7 @@ What monorepo structure, naming conventions, tooling, and build standards should
 For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/002-monorepo-setup/SKILL.md).
 Module folder responsibilities, artifact locations, and test-folder conventions follow [agentme-edr-016](../principles/016-cross-language-module-structure.md).
 
-### Implementation Details
+### Details
 
 #### 01-top-level-directory-layout
 

package/.xdrs/agentme/edrs/devops/006-github-pipelines.md

@@ -19,7 +19,7 @@ What GitHub Actions workflows should every project follow to ensure a safe, pred
 
 Separating these concerns eliminates accidental publishes from CI runs, ensures monotag has access to the full git history, and makes each workflow independently auditable and re-runnable.
 
-### Implementation Details
+### Details
 
 #### Workflow overview
 

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

@@ -19,7 +19,7 @@ What standard set of Makefile target names and execution rules should projects a
 
 Standardizing both the target names and the execution chain removes per-project guesswork, makes CI pipelines reusable, and keeps tooling behavior visible in one place.
 
-### Implementation Details
+### Details
 
 #### 01-every-project-must-have-root-makefile
 

package/.xdrs/agentme/edrs/devops/017-tool-execution-and-scripting.md

@@ -19,7 +19,7 @@ How should projects execute development commands so the command surface stays pr
 
 This keeps local development and CI aligned, reduces indirection, and lets contributors understand project behavior by reading one command surface.
 
-### Implementation Details
+### Details
 
 - Every project MUST use a root `Makefile` as the authoritative entry point for developer and pipeline commands.
 - The target names in that `Makefile` MUST follow [agentme-edr-008](008-common-targets.md).
@@ -27,7 +27,7 @@ This keeps local development and CI aligned, reduces indirection, and lets contr
 - A Makefile target MUST execute the real operation through `mise exec --` before invoking the tool itself, so it always uses the version pinned in `.mise.toml`. Avoid intermediate script layers that hide the actual command.
 - Every Makefile target MUST start by echoing a concise summary of the target and folder or context, using fewer than 10 words. When delegating to another Makefile, echo the child path and delegated target before invoking it.
 - Direct delegation to another Makefile is allowed when traversing repo, app, or module boundaries, for example `$(MAKE) -C lib build`.
-- Calling the actual tool binary through its native executable launcher is allowed when that is the direct command under `mise exec --`, for example `mise exec -- pnpm exec eslint ./src`, `mise exec -- uv run pyright`, `mise exec -- go test`, or `mise exec -- npx -y monotag`.
+- Calling the actual tool binary through its native executable launcher is allowed when that is the direct command under `mise exec --`, for example `mise exec -- pnpm exec eslint ./src`, `mise exec -- uv run ty check`, `mise exec -- go test`, or `mise exec -- npx -y monotag`.
 - Makefile targets MUST use `mise exec --` consistently before routine tool commands and MUST NOT call `npm run`, `pnpm run`, `yarn run`, `just`, `task`, or similar abstraction layers for routine project commands.
 - Tool installation and environment preparation MUST be handled explicitly in developer setup instructions and CI workflow steps, using ecosystem-specific installation steps such as `actions/setup-node`, `actions/setup-go`, `astral-sh/setup-uv`, system package managers, or pinned install commands such as `mise install`.
 - `package.json` scripts are optional and MAY exist only as direct reverse-compatibility aliases to one Make target, for example `"test": "make test"`. They MUST stay one-to-one and add no extra orchestration.

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

@@ -19,7 +19,7 @@ What contributor workflow guidance must every project publish so contributors kn
 
 Projects must keep a `CONTRIBUTING.md` file at the repository root. The file must explain where bugs, feature discussions, and code changes belong so contributors follow a predictable workflow before opening pull requests.
 
-### Implementation Details
+### Details
 
 - Every project **MUST** have a root `CONTRIBUTING.md`.
 - The guide **MUST** direct bug reports to issues.

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

@@ -14,6 +14,7 @@ Foundational standards, principles, and guidelines.
 - [agentme-edr-009](principles/009-error-handling.md) - **Error handling** - Standardize explicit errors, logging, and propagation rules
 - [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy** - Promote recurring delivery lessons into reusable XDRs
 - [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure** - Organize modules consistently across supported languages
+- [agentme-edr-022](principles/022-secrets-management.md) - **Secrets management** - Handle secrets securely using native keychains and cloud secret managers
 
 ## Articles
 
@@ -32,6 +33,7 @@ Language and framework-specific tooling and project structure.
 - [agentme-edr-018](application/018-ai-agent-development-standards.md) - **AI agent development standards** - Standard toolchain, framework, evaluation, and workflow patterns for AI agent projects built with Python and LangGraph
 - [agentme-edr-019](application/019-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
 - [agentme-edr-020](application/020-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-021](application/021-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**
 
 ## Devops

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

@@ -19,7 +19,7 @@ How should services expose their health status and validate operational readines
 
 All services must expose a `GET /health` endpoint that validates external dependencies using read-only operations and returns structured status with appropriate HTTP codes.
 
-### Implementation Details
+### Details
 
 **Endpoint contract:**
 

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

@@ -17,7 +17,7 @@ What coding practices should be followed across all languages and projects to ke
 
 **Apply a set of language-agnostic structural and organizational practices that keep files small, logic decomposed, types co-located, tests co-located, and documentation always in sync.**
 
-### Implementation Details
+### Details
 
 #### 01-keep-files-short
 

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

@@ -17,7 +17,7 @@ What unit testing practices should be followed to ensure tests are meaningful, r
 
 **Every test must assert behavior, run offline without external dependencies, enforce 80% coverage, centralize shared setup, and prefer real code over mocks.**
 
-### Implementation Details
+### Details
 
 #### 01-must-have-at-least-one-assertion-per-test
 
@@ -70,7 +70,13 @@ Builds that miss the threshold must not be merged.
 
 #### 04-must-place-test-files-alongside-source
 
-Test files must live next to the source file they test, in the same directory, following the convention of the language/framework (e.g. `file.test.ts`, `file_test.go`, `file.spec.js`).
+Test files must live next to the source file they test, in the same directory, following the convention of the language/framework:
+
+| Language | Pattern | Example |
+|----------|---------|-------|
+| TypeScript/JavaScript | `[name].test.ts` or `[name].spec.js` | `file1.test.ts` |
+| Go | `[name]_test.go` | `file1_test.go` |
+| Python | `[name]_test.py` | `myfunc_test.py` |
 
 ```
 src/mymodule/group1/file1.ts        ← source