agentme 0.5.0 → 0.7.0

package/.xdrs/agentme/edrs/application/003-javascript-project-tooling.md

@@ -13,7 +13,7 @@ What tooling and project structure should JavaScript/TypeScript projects follow
 
 ## Decision Outcome
 
-**Use a Mise-managed Node.js and pnpm toolchain together with pnpm, tsc, esbuild, eslint, and jest in a standard layout separating library code (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level Makefiles.**
+**Use a Mise-managed Node.js and pnpm toolchain together with pnpm, tsc, esbuild, eslint, and jest in a module-root layout that follows [agentme-edr-016](../principles/016-cross-language-module-structure.md), with runnable usage examples in sibling `examples/` folders and Makefiles as the only entry points.**
 
 Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelines, and a predictable developer experience across projects.
 
@@ -23,14 +23,14 @@ Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelin
 
 | Tool | Purpose |
 |------|---------|
-| **Mise** | Tool version management for Node.js, pnpm, and project CLIs |
+| **Mise** | Mandatory tool version management and command runner for Node.js, pnpm, and project CLIs |
 | **pnpm** | Package manager — strict linking, workspace support, fast installs |
 | **tsc** | TypeScript compilation — type checking, declaration generation |
 | **esbuild** | Bundling — fast bundling for distribution or single-binary outputs |
 | **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, and Makefile targets must run through `mise exec --` or an activated Mise shell.
+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> ...` so command behavior does not depend on an activated shell. Using host-installed `node`, `pnpm`, or other project CLIs directly for routine project work is not allowed.
 
 #### ESLint
 
@@ -47,57 +47,73 @@ When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `modu
 #### Project structure
 
 ```
-/                          # workspace root
+/                          # workspace root or parent aggregation root
 ├── .mise.toml             # pinned Node.js and pnpm versions
+├── .gitignore             # MUST ignore dist/ and .cache/
 ├── Makefile               # delegates build/lint/test to /lib and /examples
-├── README.md              # Quick Start first; used as npm registry page
-├── lib/                   # the published npm package
+├── README.md              # workspace overview and quickstart
+├── lib/                   # one JavaScript/TypeScript module root
 │   ├── Makefile           # build, lint, test, publish targets
+│   ├── README.md          # package README used for publishing
 │   ├── package.json       # package manifest
 │   ├── tsconfig.json      # TypeScript config for build and linting
 │   ├── jest.config.js     # Jest config
 │   ├── eslint.config.mjs  # ESLint config (ESLint 9 flat config)
+│   ├── .cache/            # eslint, jest, tsc incremental state, coverage
+│   ├── dist/              # compiled files and packed .tgz artifacts
 │   └── src/               # all TypeScript source files
 │       ├── index.ts       # public API re-exports
 │       └── *.test.ts      # test files co-located with source
-└── examples/              # runnable usage examples
-    ├── Makefile           # build + test all examples in sequence
-    ├── usage-x/           # first example
-    │   └── package.json
-    └── usage-y/           # second example
-        └── package.json
+├── examples/              # runnable usage examples outside the module root
+│   ├── Makefile           # build + test all examples in sequence
+│   ├── usage-x/           # first example
+│   │   └── package.json
+│   └── usage-y/           # second example
+│       └── package.json
+├── tests_integration/     # optional cross-example or cross-module integration tests
+└── tests_benchmark/       # optional benchmark harnesses
 ```
 
-The root `Makefile` delegates every target to `/lib` then `/examples` in sequence and is expected to execute module commands inside the repository's Mise-managed environment.
+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 --`.
 
-The commands below assume they are invoked through `mise exec -- make <target>` or from an activated Mise shell.
+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/`.
+
+Persistent caches MUST live under `.cache/`. Recommended locations are Jest `cacheDirectory`, ESLint `--cache-location`, TypeScript `tsBuildInfoFile`, and coverage outputs.
+
+Contributors and CI MUST invoke the commands below as `make <target>`. The Makefile recipes themselves MUST call the underlying tools through `mise exec -- <tool> ...`.
 
 #### lib/Makefile targets
 
 | Target | Description |
 |--------|-------------|
-| `install` | `pnpm install --frozen-lockfile` |
-| `build` | compile with `tsc`, strip test files from `dist/`, then `pnpm pack` for local use by examples |
-| `build-module` | compile with `tsc` only (no pack) |
-| `lint` | `pnpm exec eslint ./src` |
-| `lint-fix` | `pnpm exec eslint ./src --fix` |
-| `test` | `pnpm exec jest --verbose` |
-| `test-watch` | `pnpm exec jest --watch` |
-| `clean` | remove `node_modules/` and `dist/` |
+| `install` | `mise exec -- pnpm install --frozen-lockfile` |
+| `build` | `mise exec -- pnpm exec tsc ...`, strip test files from `dist/`, then `mise exec -- pnpm pack` for local use by examples |
+| `build-module` | `mise exec -- pnpm exec tsc ...` only (no pack) |
+| `lint` | `mise exec -- pnpm exec eslint ./src` |
+| `lint-fix` | `mise exec -- pnpm exec eslint ./src --fix` |
+| `test` | `mise exec -- pnpm exec jest --verbose` |
+| `test-watch` | `mise exec -- pnpm exec jest --watch` |
+| `clean` | remove `node_modules/`, `dist/`, and `.cache/` |
 | `all` | `build lint test` |
-| `publish` | version-bump with `monotag`, then `npm publish --provenance` |
+| `publish` | `mise exec -- npx -y monotag ...`, then `mise exec -- npm publish --provenance` |
 
 #### lib/package.json key fields
 
 - `"main"`: `dist/index.js`
 - `"types"`: `dist/index.d.ts`
 - `"files"`: `["dist/**", "package.json", "README.md"]`
-- `"scripts"`: empty — all commands are driven by the Makefile
+- `"scripts"`: empty by default. If reverse compatibility requires scripts, each script must be a direct one-line delegation to one Makefile target.
 
 #### examples/
 
 Each sub-folder under `examples/` is an independent package. The Makefile installs the locally built `.tgz` pack from `lib/dist/` so examples simulate real external usage.
 
+Examples MUST remain outside the module root and MUST consume the package through the packed artifact in `dist/`, never through `../src` imports or other direct source links.
+
+Module-specific integration tests that are not just runnable examples belong in `lib/tests_integration/` or a sibling `tests_integration/` when they cover multiple modules.
+
+Benchmarks belong in `lib/tests_benchmark/` when they require dedicated harnesses; simple micro-benchmarks may stay co-located only if the local testing stack makes that idiomatic.
+
 The examples folder MUST exist for any libraries and utilities that are published or have more than 500 lines of code
 
 ### Related Skills

package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-010-go-project-tooling-and-structure
-description: Defines the standard Go project toolchain, layout, and Makefile workflow for agentme-based projects. Use when scaffolding or reviewing Go projects.
+description: Defines the standard Go project toolchain, layout, and Makefile workflow using Mise for agentme-based projects. Use when scaffolding or reviewing Go projects.
 ---
 
 # agentme-edr-010: Go project tooling and structure
@@ -13,7 +13,7 @@ What tooling and project structure should Go projects follow to ensure consisten
 
 ## Decision Outcome
 
-**Use the standard Go toolchain (`go build`, `go test`) with `golangci-lint` for linting, feature packages in subdirectories (no `internal/` by default), a `cli/` package for command wiring, and a Makefile as the single entry point for all development tasks, with the Go toolchain and related CLIs sourced from the repository's Mise-managed environment when the repository defines `.mise.toml`.**
+**Use a Mise-managed Go toolchain with `go build`, `go test`, and `golangci-lint`, module-root folder responsibilities from [agentme-edr-016](../principles/016-cross-language-module-structure.md), feature packages in subdirectories, a `cli/` package for command wiring, and a Makefile as the single entry point for all development tasks.**
 
 A predictable layout and minimal external tooling keep Go projects approachable, fast to build, and easy to distribute as cross-platform binaries.
 
@@ -23,80 +23,88 @@ A predictable layout and minimal external tooling keep Go projects approachable,
 
 | Tool | Purpose |
 |------|---------|
+| **Mise** | Mandatory tool version management and command runner for Go, `golangci-lint`, and project CLIs |
 | **go toolchain** | Compilation, testing, formatting (`go build`, `go test`, `go fmt`, `go vet`, `go mod`) |
 | **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 are run exclusively through the Makefile, never ad-hoc.
-When the repository has a root `.mise.toml`, `go`, `golangci-lint`, and any other Go-related CLIs used by the project **MUST** be pinned there and resolved from the Mise-managed environment rather than the host machine.
+All commands are run exclusively through the Makefile, never 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> ...`.
 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
 
 ```
-/                              # project root (single Go module)
+/                              # project root or Go module root inside a monorepo
+├── .mise.toml                 # pinned Go, golangci-lint, and related CLIs
 ├── Makefile                   # build, lint, test, publish, and utility targets
+├── README.md                  # module README with usage and development commands
+├── .gitignore                 # MUST ignore dist/ and .cache/
+├── .golangci.yml              # golangci-lint configuration
 ├── go.mod                     # module declaration (github.com/<owner>/<project>)
 ├── go.sum                     # locked dependency checksums
 ├── main.go                    # binary entry point — argument dispatch only, no logic
-├── .golangci.yml              # golangci-lint configuration
-├── .gitignore
-├── README.md
+├── .cache/                    # GOCACHE, GOMODCACHE, golangci-lint cache, coverage
+├── dist/                      # built binaries and packaged outputs
 ├── <feature-a>/               # domain package (e.g. ownership/, changes/, utils/)
 │   ├── *.go                   # business logic
 │   └── *_test.go              # unit tests co-located with source
 ├── <feature-b>/
 │   └── ...
-└── cli/                       # CLI wiring — ties flags to domain packages
-    ├── <feature-a>/
-    │   └── *.go
-    └── <feature-b>/
-        └── *.go
+├── cli/                       # CLI wiring — ties flags to domain packages
+│   ├── <feature-a>/
+│   │   └── *.go
+│   └── <feature-b>/
+│       └── *.go
+├── tests_integration/         # optional integration tests for this module
+├── tests_benchmark/           # optional benchmark harnesses and datasets
+└── examples/                  # optional sibling consumer examples for libraries
 ```
 
 **Key layout rules:**
 
 - 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 a `cli/<feature>/Run*()` function. No domain logic lives in `main.go`.
 - Business logic lives in named feature packages at the root (e.g., `ownership/`, `changes/`, `utils/`). These packages are importable and testable without any CLI concerns.
 - `cli/` packages own flag parsing, output formatting, and the wiring between flags and domain functions. No business logic lives in `cli/`.
 - Packages are flat by default; sub-packages are only introduced when a feature package itself exceeds ~400 lines or has clearly separable sub-concerns.
+- Consumer examples for reusable libraries belong in a sibling `examples/` folder and MUST import the public module path rather than reaching into internal source paths. Because Go libraries are not typically consumed from a local packaged artifact, local example validation may use a temporary module replacement for resolution, but the import path MUST remain the public module path.
 
 #### go.mod
 
 - Module path: `github.com/<owner>/<project>` (or the relevant VCS path for the project)
 - Use the latest stable Go version (e.g. `go 1.24`).
 - Separate `require` blocks: direct dependencies first, then `// indirect` dependencies.
-- If the repository uses Mise, the Go version declared in `go.mod` and the Go version pinned in `.mise.toml` **MUST** stay aligned.
+- The Go version declared in `go.mod` and the Go version pinned in `.mise.toml` **MUST** stay aligned.
 
 #### Makefile targets
 
 | Target | Description |
 |--------|-------------|
 | `all` | Default; runs `build lint test` in sequence |
-| `build` | `go mod download && go build -o dist/<binary>` |
+| `build` | `mise exec -- go mod download && mise exec -- go build -o dist/<binary>` with Go caches redirected into `.cache/` |
 | `build-all` | Cross-compile for all target platforms (darwin/linux/windows × amd64/arm64) |
 | `build-arch-os` | Compile for a specific `OS` and `ARCH` environment variable pair; output to `dist/${OS}-${ARCH}/<binary>` |
-| `install` | `go mod download` |
-| `lint` | `golangci-lint run ./...` |
-| `lint-fix` | `golangci-lint run --fix ./...` |
-| `test` | `go test -cover ./...` — runs all tests with coverage |
-| `test-unit` | `go test -cover ./...` — alias for unit tests only (same here; integration tests get a separate tag) |
-| `coverage` | `go tool cover -func ./coverage.out` — displays coverage summary |
-| `clean` | Remove `dist/` and any coverage files |
-| `start` | `go run ./ <default-args>` — launch the binary locally for dev use |
-| `publish` | Tag with `monotag`, then push tag + binaries to GitHub Releases |
-
-When the repository uses Mise, the intended invocation pattern is:
+| `install` | `mise exec -- go mod download` |
+| `lint` | `mise exec -- golangci-lint run ./...` with its cache redirected into `.cache/` |
+| `lint-fix` | `mise exec -- golangci-lint run --fix ./...` with its cache redirected into `.cache/` |
+| `test` | `mise exec -- go test -cover ./...` — runs all tests with coverage and stores disposable outputs under `.cache/` |
+| `test-unit` | `mise exec -- go test -cover ./...` — alias for unit tests only (same here; integration tests get a separate tag) |
+| `coverage` | `mise exec -- go tool cover -func .cache/coverage.out` — displays coverage summary |
+| `clean` | Remove `dist/` and `.cache/` |
+| `start` | `mise exec -- go run ./ <default-args>` — launch the binary locally for dev use |
+| `publish` | Tag with `mise exec -- npx -y monotag ...`, then push tag + binaries to GitHub Releases |
+
+The required invocation pattern is:
 
 ```sh
-mise install
-mise exec -- make build
-mise exec -- make test
-mise exec -- make lint
+make setup
+make build
+make test
+make lint
 ```
 
-Using `make build`, `make test`, or `make lint` from an already activated Mise shell is equivalent.
+The Makefile recipes themselves must use `mise exec --` for the underlying tool commands.
 
 #### Cross-platform binary distribution
 
@@ -112,8 +120,10 @@ When the project produces a CLI binary for end-users:
 - Tests are co-located with source: `<feature>/<file>_test.go`.
 - Use `github.com/stretchr/testify` (`assert`, `require`) for test assertions.
 - Run all tests: `go test -cover ./...`
-- Benchmarks: `go test -bench . -benchmem -count 20`
-- Integration or slow tests: guard with `//go:build integration` and skip in unit runs via `-tags=unit`.
+- Benchmarks: keep simple `Benchmark*` functions co-located in `*_test.go`; use `tests_benchmark/` when the benchmark needs dedicated harnesses or datasets.
+- Integration or slow tests: guard with `//go:build integration` and keep them in `tests_integration/` when they are not naturally co-located with one package.
+
+Redirect Go tool caches into `.cache/` using `GOCACHE`, `GOMODCACHE`, and `GOLANGCI_LINT_CACHE` from the module `Makefile` so the repository does not accumulate scattered cache directories.
 
 #### Linting
 

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

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-014-python-project-tooling-and-structure
-description: Defines the standard Python project toolchain, layout, and Makefile workflow using 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, pyright, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
 ---
 
 # agentme-edr-014: Python project tooling and structure
@@ -13,9 +13,9 @@ What tooling and project structure should Python projects follow to ensure consi
 
 ## Decision Outcome
 
-**Use a uv-managed Python project with `pyproject.toml`, `ruff`, `pyright`, `pytest`, `pytest-cov`, `pip-audit`, and a Makefile as the only development entry point.**
+**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.**
 
-A single dependency manager, one canonical config file, and standard targets keep Python projects predictable for contributors and CI.
+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.
 
 ### Implementation Details
 
@@ -23,6 +23,7 @@ A single dependency manager, one canonical config file, and standard targets kee
 
 | Tool | Purpose |
 |------|---------|
+| **Mise** | Mandatory tool version management and command runner for Python, uv, and project CLIs |
 | **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 |
@@ -33,42 +34,66 @@ A single dependency manager, one canonical config file, and standard targets kee
 
 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.
 
-When the repository defines a root `.mise.toml`, Python and uv must be pinned there and commands should run through `mise exec --` or an activated Mise shell.
+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> ...`. Using host-installed `python`, `uv`, or other project CLIs directly for routine project work 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.
+
+Persistent caches must live under `.cache/`, preferably the module `lib/.cache/` plus a shared root `.cache/uv/` when uv cache sharing is desired.
 
 #### Project structure
 
 ```text
 /
-├── .mise.toml              # optional but required when the repo uses Mise
-├── Makefile                # single entry point for build/lint/test/run tasks
-├── pyproject.toml          # package metadata + tool config
-├── uv.lock                 # committed lockfile
-├── README.md               # Getting Started near the top
-├── src/
-│   └── <package_name>/
-│       ├── __init__.py
-│       ├── __main__.py     # when the project exposes a CLI
-│       └── ...
-├── tests/
-│   ├── conftest.py         # shared fixtures when needed
-│   └── test_*.py
-└── examples/               # required for libraries and shared utilities
-    ├── Makefile
-    └── basic-usage/
+├── .mise.toml              # required; pins Python and uv
+├── .gitignore
+├── .cache/                 # optional shared uv cache at repo level
+├── .venv/                  # shared uv environment for lib/ and examples/
+├── Makefile                # root entry point; delegates to lib/ and runs examples/
+├── README.md               # workspace/repository overview
+├── lib/                    # everything the published library needs
+│   ├── Makefile            # build, lint, test, publish targets for the library
+│   ├── pyproject.toml      # package metadata + tool config
+│   ├── uv.lock             # committed lockfile for the library
+│   ├── README.md           # package README used for publishing
+│   ├── .cache/             # pytest, Ruff, coverage, Python bytecode cache
+│   ├── src/
+│   │   └── <package_name>/
+│   │       ├── __init__.py
+│   │       ├── __main__.py # when the project exposes a CLI
+│   │       └── ...
+│   ├── tests/
+│   │   ├── conftest.py     # shared fixtures when needed
+│   │   └── test_*.py
+│   ├── tests_integration/  # optional integration tests for this module
+│   ├── tests_benchmark/    # optional benchmark harnesses and datasets
+│   └── dist/               # wheels / sdists built from lib/
+└── examples/               # independent consumer projects
+    ├── example1/
+    │   ├── pyproject.toml
+    │   └── main.py
+    └── example2/
+        ├── pyproject.toml
+        └── main.py
 ```
 
-Use the `src/` layout for import safety and packaging clarity. Keep tests under `tests/` and shared test setup in `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 `pyproject.toml`.
+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`.
 
-Libraries and shared utilities must include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../principles/007-project-quality-standards.md).
+Libraries and shared utilities must include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../principles/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/`.
 
-#### `pyproject.toml`
+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.
+
+#### `lib/pyproject.toml`
 
 - Runtime dependencies belong in `[project.dependencies]`.
 - Development-only tooling belongs in `[dependency-groups].dev`.
-- Configure Ruff, Pyright, and Pytest in `pyproject.toml` under their `tool.*` sections.
-- Commit `uv.lock` and keep it in sync with `pyproject.toml`.
+- Configure Ruff, Pyright, 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"`.
+
 Ruff is the default formatter and linter. Do not add Black, isort, or Flake8 unless another XDR for that repository explicitly requires them.
 
 Pyright must run on every lint pass. `typeCheckingMode = "standard"` is the minimum baseline; projects may raise this to `strict` when the codebase is ready.
@@ -77,23 +102,40 @@ Pytest coverage must fail below 80% line and branch coverage, following [agentme
 
 #### Makefile targets
 
-The commands below assume invocation through `mise exec -- make <target>` when the repository uses Mise, or plain `make <target>` inside an activated project environment.
+Contributors and CI MUST invoke the commands below as `make <target>`. The Makefile recipes themselves MUST call the underlying tools through `mise exec -- <tool> ...`.
+
+#### Root `Makefile`
+
+The root `Makefile` is the only contract for CI and contributors. It delegates library work to `lib/` and runs each example project in `examples/` against the shared root `.venv/`.
 
 | Target | Description |
 |--------|-------------|
-| `install` | `uv sync --frozen --all-extras --dev` |
-| `build` | `uv sync --frozen --all-extras --dev && uv build` |
-| `lint` | `uv run ruff format --check . && uv run ruff check . && uv run pyright && uv run pip-audit` |
-| `lint-fix` | `uv run ruff format . && uv run ruff check . --fix && uv run pyright && uv run pip-audit` |
-| `test-unit` | `uv run pytest --cov=src/<package_name> --cov-branch --cov-report=term-missing --cov-fail-under=80` |
-| `test-examples` | Run `examples/` through its own `Makefile` when the project is a library/utility |
+| `setup` | Run `mise install`, then `lib/install` to create or update the shared root `.venv/` |
+| `install` | Run `lib/install` to create or update the shared root `.venv/` |
+| `build` | Run `lib/build` |
+| `lint` | Run `lib/lint` |
+| `lint-fix` | Run `lib/lint-fix` |
+| `test-unit` | Run `lib/test-unit` |
+| `test-examples` | For each `examples/*/pyproject.toml`, sync and run the example serially against the shared root `.venv/` |
 | `test` | Run `test-unit`, then `test-examples` when applicable |
-| `clean` | Remove `.venv/`, `dist/`, `.pytest_cache/`, `.ruff_cache/`, `.coverage`, `htmlcov/` |
+| `clean` | Remove the shared root `.venv/`, root `.cache/`, and delegate cleanup to `lib/` |
 | `all` | `build lint test` |
-| `update-lockfile` | `uv lock --upgrade` |
-| `run` | `uv run python -m <package_name>` or the project CLI entry point |
+
+#### `lib/Makefile`
+
+| Target | Description |
+|--------|-------------|
+| `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/` |
+| `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` |
+| `update-lockfile` | `mise exec -- uv lock --project . --upgrade` |
+| `run` | `mise exec -- uv run --project . python -m <package_name>` or the project CLI entry point |
 | `dev` | Same as `run`, optionally with repository-specific dev defaults |
-| `publish` | `uv publish` after versioning and packaging are complete |
+| `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](../devops/008-common-targets.md).
 
@@ -101,8 +143,8 @@ 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 + `pyproject.toml` + Ruff/Pyright/Pytest toolchain** - One dependency manager, one config file, and one Makefile entry point.
-  * Reason: Keeps packaging, dependency locking, static analysis, security auditing, and test execution consistent.
+* (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.
+  * Reason: Keeps packaging, dependency locking, static analysis, security auditing, and test execution consistent while aligning Python repositories with the established JavaScript layout.
 
 ## References