agentme 0.11.0 → 0.12.0

package/.filedist-package.yml

@@ -1,5 +1,5 @@
 sets:
-  - package: xdrs-core@0.28.0
+  - package: xdrs-core@0.28.1
   # - package: git:https://github.com/flaviostutz/xdrs-core.git@main
     selector:
       files:

package/.xdrs/agentme/edrs/application/014-python-project-tooling.md

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-policy-014-python-project-tooling-and-structure
-description: Defines the standard Python project toolchain, layout, and Makefile workflow using Mise, uv, ruff, pyright, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
+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
 ---
@@ -15,7 +15,7 @@ What tooling and project structure should Python projects follow to ensure consi
 
 ## Decision Outcome
 
-**Use a Mise-managed Python and uv toolchain with `pyproject.toml`, `ruff`, `pyright`, `pytest`, `pytest-cov`, `pip-audit`, and a layout that follows [agentme-edr-016](../principles/016-cross-language-module-structure.md): a module root under `lib/`, runnable consumer examples in sibling `examples/`, and standardized `dist/` and `.cache/` locations.**
+**Use a Mise-managed Python and uv toolchain with `pyproject.toml`, `ruff`, `ty`, `pytest`, `pytest-cov`, `pip-audit`, and a layout that follows [agentme-edr-016](../principles/016-cross-language-module-structure.md): a module root under `lib/`, runnable consumer examples in sibling `examples/`, and standardized `dist/` and `.cache/` locations.**
 
 A single dependency manager, isolated package internals under `lib/`, and a standard Makefile contract keep Python projects predictable for contributors and CI while keeping the repository root clean.
 
@@ -29,12 +29,12 @@ A single dependency manager, isolated package internals under `lib/`, and a stan
 | **uv** | Dependency management, lockfile management, virtualenv sync, build, publish |
 | **pyproject.toml** | Single source of truth for package metadata and tool configuration |
 | **ruff** | Formatting, import sorting, linting, and common code-quality checks |
-| **pyright** | Static type checking |
+| **ty** | Static type checking |
 | **pytest** | Test runner |
 | **pytest-cov** | Coverage reporting and threshold enforcement |
 | **pip-audit** | Dependency CVE audit |
 
-All routine commands must run through the project `Makefile`, never by calling `uv`, `ruff`, `pytest`, or `pyright` directly in docs, CI, or daily development workflows.
+All routine commands must run through the project `Makefile`, never by calling `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](../devops/017-tool-execution-and-scripting.md). Using routine project CLI commands directly outside the Makefile contract is not allowed.
 
@@ -79,7 +79,7 @@ No tool MUST write cache or state files to the project root, `src/`, `tests/`, o
 │   │       └── shared/         # infrastructure-agnostic utilities
 │   ├── tests/
 │   │   ├── conftest.py     # shared fixtures when needed
-│   │   └── test_*.py
+│   │   └── *_test.py       # e.g. hello_test.py (named after the tested file)
 │   ├── tests_integration/  # optional integration tests for this module
 │   ├── tests_benchmark/    # optional benchmark harnesses and datasets
 │   └── dist/               # wheels / sdists built from lib/
@@ -94,7 +94,7 @@ No tool MUST write cache or state files to the project root, `src/`, `tests/`, o
 
 Keep the repository root clean: source code, tests, distribution artifacts, and package metadata live under `lib/`, while the root contains only orchestration and repository-level files.
 
-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 `pyrightconfig.json` by default; keep project metadata and tool configuration in `lib/pyproject.toml`.
+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-021](021-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
 
@@ -106,11 +106,11 @@ Python keeps unit tests under `lib/tests/` by default because that remains the m
 
 - Runtime dependencies belong in `[project.dependencies]`.
 - Development-only tooling belongs in `[dependency-groups].dev`.
-- Configure Ruff, Pyright, and Pytest in `lib/pyproject.toml` under their `tool.*` sections.
+- Configure Ruff, ty, and Pytest in `lib/pyproject.toml` under their `tool.*` sections.
 - Commit `lib/uv.lock` and keep it in sync with `lib/pyproject.toml`.
 - Expose CLI entry points with `[project.scripts]` when the project provides commands.
 
-When Pyright runs from `lib/`, configure it to discover the shared root virtual environment, for example with `venvPath = ".."` and `venv = ".venv"`.
+When ty runs from `lib/`, it auto-discovers the virtual environment via the `VIRTUAL_ENV` environment variable or the `UV_PROJECT_ENVIRONMENT` export set in the Makefile. No additional venv configuration is required in `pyproject.toml`.
 
 Ruff is the default formatter and linter. Do not add Black, isort, or Flake8 unless another XDR for that repository explicitly requires them.
 
@@ -119,6 +119,7 @@ All Python projects must configure the following sections in `lib/pyproject.toml
 ```toml
 [tool.pytest.ini_options]
 cache_dir = ".cache/pytest"
+python_files = "*_test.py"
 
 [tool.coverage.run]
 data_file = ".cache/.coverage"
@@ -156,7 +157,7 @@ ignore-overlong-task-comments = true
 
 Adjust `target-version` to match the project's minimum supported Python version. The `cache-dir` keeps Ruff's cache under `.cache/ruff` alongside other tool caches. The `src` list must include every directory that contains importable Python code. The `select` list enables a broad set of rules covering style, correctness, performance, security, and documentation. The `ignore` list suppresses rules that are either too noisy or conflict with the chosen docstring style.
 
-Pyright must run on every lint pass. `typeCheckingMode = "standard"` is the minimum baseline; projects may raise this to `strict` when the codebase is ready.
+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](../principles/004-unit-test-requirements.md).
 
@@ -187,8 +188,8 @@ The root `Makefile` is the only contract for CI and contributors. It delegates l
 |--------|-------------|
 | `install` | `mise exec -- uv sync --project . --frozen --all-extras --dev` using the shared root `.venv/` |
 | `build` | `mise exec -- uv sync --project . --frozen --all-extras --dev && mise exec -- uv build --project . --out-dir dist` |
-| `lint` | `mise exec -- uv run --project . ruff format --check . && mise exec -- uv run --project . ruff check . && mise exec -- uv run --project . pyright && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
-| `lint-fix` | `mise exec -- uv run --project . ruff format . && mise exec -- uv run --project . ruff check . --fix && mise exec -- uv run --project . pyright && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
+| `lint` | `mise exec -- uv run --project . ruff format --check . && mise exec -- uv run --project . ruff check . && mise exec -- uv run --project . ty check && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
+| `lint-fix` | `mise exec -- uv run --project . ruff format . && mise exec -- uv run --project . ruff check . --fix && mise exec -- uv run --project . ty check && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
 | `test-unit` | `mise exec -- uv run --project . pytest --cov=src/<package_name> --cov-branch --cov-report=term-missing --cov-fail-under=80`, with pytest and coverage outputs stored under `.cache/` |
 | `clean` | Remove `dist/` and `.cache/` inside `lib/` |
 | `all` | `build lint test-unit` |
@@ -203,7 +204,7 @@ The root `Makefile` must remain the only contract for CI and contributors, in li
 
 * (REJECTED) **Mixed Python tooling** - Separate tools and config files such as `pip`, `requirements.txt`, `setup.cfg`, `flake8`, and `mypy`.
   * Reason: Increases cognitive load, duplicates configuration, and weakens the standard command surface across projects.
-* (CHOSEN) **uv + `lib/` package layout + Ruff/Pyright/Pytest toolchain** - One dependency manager, package internals isolated under `lib/`, consumer examples under `examples/`, and one root Makefile contract.
+* (CHOSEN) **uv + `lib/` package layout + Ruff/ty/Pytest toolchain** - One dependency manager, package internals isolated under `lib/`, consumer examples under `examples/`, and one root Makefile contract.
   * Reason: Keeps packaging, dependency locking, static analysis, security auditing, and test execution consistent while aligning Python repositories with the established JavaScript layout.
 
 ## References

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

@@ -13,7 +13,7 @@ compatibility: Python 3.12+
 ## Overview
 
 Creates a complete Python project from scratch using Mise, `uv`, `pyproject.toml`, Ruff,
-Pyright, Pytest, and Makefiles. The layout keeps the package self-contained under `lib/`,
+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.
@@ -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",
@@ -237,19 +237,17 @@ ignore = ["ANN002", "ANN003", "ANN401", "D100", "D101", "D102", "D103", "D104",
 [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`**
 
@@ -332,7 +330,7 @@ if __name__ == "__main__":
 
 Create empty `adapters/connectors/` directory with a `.gitkeep` for outbound adapters.
 
-**`lib/tests/test_hello.py`**
+**`lib/tests/hello_test.py`**
 
 ```python
 from [package_name].app.hello import hello
@@ -391,7 +389,7 @@ After creating the files:
 - 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"

package/.xdrs/agentme/edrs/devops/017-tool-execution-and-scripting.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/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
 

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

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

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

@@ -0,0 +1,128 @@
+---
+name: agentme-edr-policy-022-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
+
+## Context and Problem Statement
+
+A "secret" is any sensitive information whose exposure would compromise security or access control. Examples include API keys, passwords, authentication tokens, credentials, and private certificates. Plain configuration data (feature flags, endpoint URLs, port numbers) is not a secret.
+
+Secrets stored on disk — even in `.env` files excluded from version control — are vulnerable to accidental exposure, tooling leaks, and lateral movement after a compromise. Hardcoded or cached secrets resist rotation and create synchronization headaches across environments.
+
+What practices should projects follow to handle secrets securely across local development and cloud deployments?
+
+## Decision Outcome
+
+**Use native OS keychains for local development and cloud secret managers for deployed environments, accessed through a unified connector with ordered fallback.**
+
+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.
+
+### 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.
+
+The only acceptable local persistence is through the operating system's native secret manager (e.g., macOS Keychain, Windows Credential Manager, Linux Secret Service).
+
+---
+
+#### 02-local-dev-uses-native-keychain
+
+During local development, secrets must be stored and retrieved using the native OS secret manager. Use cross-platform libraries to keep the code OS-agnostic:
+
+| Language | Library |
+|----------|---------|
+| Python | `keyring` |
+| 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.
+
+---
+
+#### 03-fallback-lookup-order
+
+Secret fetching must implement a fallback chain in the following order:
+
+1. **Native OS keychain** — attempt to retrieve the secret using the local keychain library (used during local development).
+2. **Cloud secret manager** — if not found locally, fetch from the configured cloud secret manager (AWS Secrets Manager, Azure Key Vault, etc.) (used in cloud environments).
+3. **Raise an exception** — if both lookups fail, raise an exception with a clear message indicating both failed paths.
+
+Example error message:
+```
+Secret 'db-password' could not be found in keychain under group 'mymodule' or in AWS Secrets Manager under secretId 'db-password'
+```
+
+---
+
+#### 04-secret-fetching-in-connector
+
+The secret fetching logic (including the fallback chain from rule 03) must live in a dedicated "connector" module or function. This isolates secret-access concerns from business logic and provides a single point to configure secret sources, caching policy, and error handling.
+
+---
+
+#### 05-setup-secrets-makefile-target
+
+Every module that requires secrets must expose a `setup-secrets` Makefile target. This target:
+
+- Prompts the user for each required secret value interactively.
+- If the user provides an empty value, the existing secret is not updated.
+- Stores the provided value in the native OS keychain.
+- Uses the module name as the default group (service name).
+- Uses secret identifiers that match the cloud secret manager IDs.
+
+The desired developer flow:
+
+```text
+$ make run
+Error: Secret 'api-key' could not be found in keychain under group 'mymodule'
+       or in AWS Secrets Manager under secretId 'api-key'
+
+$ make setup-secrets
+Enter value for 'api-key' (leave empty to skip):
+> ****
+Secret 'api-key' stored in keychain under group 'mymodule'.
+
+$ make run
+# Application starts successfully
+```
+
+---
+
+#### 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.
+
+---
+
+#### 07-prefer-dynamic-fetching
+
+Wherever possible, fetch secrets dynamically from the secret manager at the time of use. Avoid storing secrets in global variables or caching them indefinitely. Dynamic fetching through a specialized service enables:
+
+- Automatic password rotation without redeployment.
+- Immediate propagation of rotated secrets.
+- Reduced window of exposure if memory is compromised.
+
+Short-lived caching (e.g., a few minutes) is acceptable when performance requires it, but must have an explicit TTL.
+
+---
+
+#### 08-prefer-fetching-at-point-of-use
+
+Prefer fetching the secret inside the function that directly needs it rather than passing it through multiple layers as a function argument. This minimizes the exposure surface by reducing the number of code paths that handle the raw secret value.
+
+Passing secrets via function arguments is acceptable when the consuming function cannot access the connector directly, but the default design should fetch at the point of use.
+
+## References
+
+- [agentme-edr-008](../devops/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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.34.1"
@@ -22,6 +22,6 @@
     "url": "https://github.com/flaviostutz/agentme.git"
   },
   "devDependencies": {
-    "xdrs-core": "^0.28.0"
+    "xdrs-core": "^0.28.1"
   }
 }