agentme 0.25.0 → 0.26.0

package/.filedist-package.yml

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

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

@@ -61,7 +61,7 @@ coverageProvider: 'v8',
 coverageDirectory: '.cache/coverage',
 ```
 
-Builds that miss the threshold must not be merged.
+Builds that miss the threshold MUST NOT be merged.
 
 #### Project structure
 
@@ -105,7 +105,7 @@ Internal source code MUST be organized following [agentme-edr-026](026-pragmatic
 
 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/`.
 
-All tool caches, incremental state files, and workspace-local config outputs MUST be written under `.cache/`. This applies to every tool without exception. Cache and state paths MUST be declared in the tool's own configuration file — never on the command line — so that the location is enforced regardless of how the tool is invoked:
+All tool caches, incremental state files, and workspace-local config outputs MUST be written under `.cache/`. This applies to every tool without exception. Cache and state paths MUST be declared in the tool's own configuration file — MUST NOT be on the command line — so that the location is enforced regardless of how the tool is invoked:
 
 | Tool | Config file | Setting | Value |
 |------|------------|---------|-------|
@@ -114,7 +114,7 @@ All tool caches, incremental state files, and workspace-local config outputs MUS
 | **TypeScript** | `tsconfig.json` | `tsBuildInfoFile` | `.cache/tsbuildinfo` |
 | **Jest coverage** | `jest.config.js` | `coverageDirectory` | `.cache/coverage` |
 
-No tool MUST write cache or state files to the project root, `src/`, or any other directory outside `.cache/`. Passing cache paths as Makefile or CLI flags instead of config-file settings is not allowed.
+Tools MUST NOT write cache or state files to the project root, `src/`, or any other directory outside `.cache/`. Passing cache paths as Makefile or CLI flags instead of config-file settings is not allowed.
 
 Contributors and CI MUST invoke the commands below as `make <target>`. The Makefile recipes themselves MUST call the underlying tools through `mise exec -- <tool> ...`.
 
@@ -144,7 +144,7 @@ Contributors and CI MUST invoke the commands below as `make <target>`. The Makef
 
 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.
+Examples MUST remain outside the module root and MUST consume the package through the packed artifact in `dist/`. MUST NOT use `../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.
 

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

@@ -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 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> ...`, following [agentme-edr-017](../devops/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-017](../devops/017-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
@@ -80,7 +80,7 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 - Business logic lives in named feature packages under `app/` (e.g., `app/ownership/`, `app/changes/`). These packages are importable and testable without any CLI or adapter concerns.
 - `adapters/cli/` packages own 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, named descriptively (e.g., `postgres/`, `stripe-api/`, `redis-cache/`).
-- `shared/` must contain only infrastructure-agnostic utilities — not business rules or domain logic.
+- `shared/` MUST contain only infrastructure-agnostic utilities — not business rules or domain logic.
 - Packages are flat by default; sub-packages are only introduced when a feature package itself exceeds ~400 lines or has clearly separable sub-concerns.
 - Application MAY import from Adapters when it simplifies the design (pragmatic coupling per edr-022 rule 05).
 - 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.
@@ -120,7 +120,7 @@ make test
 make lint
 ```
 
-The Makefile recipes themselves must use `mise exec --` for the underlying tool commands.
+The Makefile recipes themselves MUST use `mise exec --` for the underlying tool commands.
 
 #### Cross-platform binary distribution
 
@@ -148,7 +148,7 @@ All tool caches, incremental state files, and build outputs MUST be written unde
 | **golangci-lint cache** | `GOLANGCI_LINT_CACHE` env var | `export GOLANGCI_LINT_CACHE := $(CURDIR)/.cache/golangci-lint` |
 | **Test coverage output** | `-coverprofile` flag in `test` target | `.cache/coverage.out` |
 
-No tool MUST write cache or state files to the project root or any directory outside `.cache/`. Passing cache paths as per-recipe environment overrides instead of top-level Makefile exports is not allowed.
+Tools MUST NOT write cache or state files to the project root or any directory outside `.cache/`. Passing cache paths as per-recipe environment overrides instead of top-level Makefile exports is not allowed.
 
 #### Linting
 

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

@@ -34,13 +34,13 @@ A single dependency manager, isolated package internals under `lib/`, and a stan
 | **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 `ty` directly in docs, CI, or daily development workflows.
+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](../devops/017-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.
+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.
 
-All tool caches, incremental state files, and workspace-local outputs MUST be written under `.cache/`. Cache paths MUST be declared in the tool's own configuration file — never on the command line or as Makefile CLI flags — so the location is enforced regardless of how the tool is invoked. Configure the following in `lib/pyproject.toml`:
+All tool caches, incremental state files, and workspace-local outputs MUST be written under `.cache/`. Cache paths MUST be declared in the tool's own configuration file — MUST NOT be on the command line or as Makefile CLI flags — so the location is enforced regardless of how the tool is invoked. Configure the following in `lib/pyproject.toml`:
 
 | Tool | Config section | Setting | Value |
 |------|---------------|---------|-------|
@@ -50,7 +50,7 @@ All tool caches, incremental state files, and workspace-local outputs MUST be wr
 | **coverage HTML** | `[tool.coverage.html]` | `directory` | `".cache/coverage-html"` |
 | **uv** | `[tool.uv]` in `lib/pyproject.toml` | `cache-dir` | `".cache/uv"` |
 
-No tool MUST write cache or state files to the project root, `src/`, `tests/`, or any directory outside `.cache/`. Passing cache paths as CLI flags or Makefile recipe-level env overrides instead of `pyproject.toml` settings is not allowed.
+Tools MUST NOT write cache or state files to the project root, `src/`, `tests/`, or any directory outside `.cache/`. Passing cache paths as CLI flags or Makefile recipe-level env overrides instead of `pyproject.toml` settings is not allowed.
 
 #### Project structure
 
@@ -98,7 +98,7 @@ Use the `lib/src/` layout for import safety and packaging clarity. Keep tests un
 
 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).
 
-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/`.
+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/`.
 
 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.
 
@@ -114,7 +114,7 @@ When ty runs from `lib/`, it auto-discovers the virtual environment via the `VIR
 
 Ruff is the default formatter and linter. Do not add Black, isort, or Flake8 unless another XDR for that repository explicitly requires them.
 
-All Python projects must configure the following sections in `lib/pyproject.toml`. The cache-related settings are mandatory per the `.cache/` policy above:
+All Python projects MUST configure the following sections in `lib/pyproject.toml`. The cache-related settings are mandatory per the `.cache/` policy above:
 
 ```toml
 [tool.pytest.ini_options]
@@ -155,11 +155,11 @@ ignore = ["ANN002", "ANN003", "ANN401", "D100", "D101", "D102", "D103", "D104",
 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.
+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.
 
-ty must run on every lint pass. The default rule set is the minimum baseline; projects may enable stricter rules as the codebase matures.
+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).
+Pytest coverage MUST fail below 80% line and branch coverage, following [agentme-edr-004](../principles/004-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](../devops/008-common-targets.md).
+The root `Makefile` MUST remain the only contract for CI and contributors, in line with [agentme-edr-008](../devops/008-common-targets.md).
 
 ## Considered Options
 

package/.xdrs/agentme/edrs/application/018-ai-llm-development-standards.md

@@ -51,7 +51,7 @@ Every component that interacts with an LLM MUST be classified as exactly one of
 All direct LLM calls MUST use **LangChain** via the `langchain` packages.
 
 - Use `langchain-openai` as the provider integration layer. It supports both OpenAI and Azure OpenAI.
-- **Always configure LLM providers using explicit library attributes** such as `api_key`, `base_url`, `model`, `api_version`, etc. Never rely on environment variables for LLM configuration.
+- LLM providers MUST be configured using explicit library attributes such as `api_key`, `base_url`, `model`, `api_version`, etc. MUST NOT rely on environment variables for LLM configuration.
 - Configuration MUST be passed via constructor parameters or configuration objects, making dependencies explicit and testable.
 
 **Example of explicit configuration:**

package/.xdrs/agentme/edrs/application/019-ai-agents-development-standards.md

@@ -46,11 +46,11 @@ When an agent requires a **local sandbox** — an isolated environment where the
 Use deepagents sandbox whenever ANY of the following is true:
 - The agent needs to execute shell commands or scripts in a controlled environment.
 - The agent needs to list, read, or search files across multiple directories at runtime.
-- The agent operates on user-supplied or generated file trees that must not escape a sandboxed boundary.
+- The agent operates on user-supplied or generated file trees that MUST NOT escape a sandboxed boundary.
 
 **Integration requirements:**
 
-- The sandbox MUST always be initialized with `virtual_mode=True` to prevent the agent from reading or writing files outside the mounted workspace. Omitting this flag allows the agent unrestricted host filesystem access, which is a security violation.
+- The sandbox MUST be initialized with `virtual_mode=True` to prevent the agent from reading or writing files outside the mounted workspace. Omitting this flag allows the agent unrestricted host filesystem access, which is a security violation.
 - Initialize the sandbox at the start of the agent run and shut it down in the same `try/finally` block.
 - Pass the sandbox handle into the agent's state so all tool calls share the same sandbox instance.
 - If the host-side code needs to pass files into the sandbox (e.g. generated config or input data), create a temporary directory with `tempfile.mkdtemp()`, write the files there, and mount it into the sandbox. Clean it up in the `finally` block.
@@ -108,11 +108,11 @@ When agents are used as nodes in workflows, the node name MUST use the `_agent`
 
 #### 05-agent-composition
 
-When multiple agents are needed:
+When multiple agents are needed, one of these composition patterns MUST be chosen:
 
 - **Single agent with multiple tools:** Use when tools share a common goal and context (e.g., a code analysis agent with `read_file`, `search_code`, and `analyze_pattern` tools).
 - **Multiple agents as workflow nodes:** Use when agents have distinct responsibilities and outputs that feed into each other. Orchestrate them using LangGraph per [agentme-edr-021](021-ai-workflow-development-standards.md).
-- Do NOT create nested agent loops (agent calling agent autonomously). Use workflows for multi-agent orchestration.
+- Nested agent loops (agent calling agent autonomously) MUST NOT be created. Use workflows for multi-agent orchestration.
 
 **Decision criteria:**
 
@@ -120,11 +120,11 @@ When multiple agents are needed:
 |---|---|
 | Single agent + tools | All tools serve the same goal; agent completes in one session |
 | Multiple workflow-orchestrated agents | Each agent has a distinct goal; outputs flow between agents; deterministic sequencing needed |
-| Nested agents (FORBIDDEN) | Never — always use workflow orchestration instead |
+| Nested agents (FORBIDDEN) | MUST NOT use nested agents; MUST use workflow orchestration instead |
 
 #### 06-agent-system-prompt-structure
 
-Every agent system prompt MUST follow this XML-section template. Sections must appear in this order. Required sections must always be present; optional sections may be omitted when they genuinely do not apply; never reorder them.
+Every agent system prompt MUST follow this XML-section template. Sections MUST appear in this order. Required sections MUST be present; optional sections may be omitted when they genuinely do not apply; MUST NOT be reordered.
 
 ```xml
 [specific task description to the agent. if not defined use the default prompt "Execute your objective taking into consideration the inputs provided and all the sections described below"]
@@ -189,7 +189,7 @@ The current OS is: [operating system name].
 |---|---|---|
 | `<SYSTEM_CONTEXT>` | Optional | Runtime environment context injected at invocation time (e.g., current date in YYYY-MM-DD, OS). Include whenever the agent may need temporal or environment awareness. Time MUST NOT be included — it changes every second and breaks prompt caching. |
 | `<OBJECTIVE>` | Required | One or two sentences summarising the agent's main deliverable. |
-| `<ROLE>` | Required | Agent persona and expertise. When inside a workflow, MUST reference its node name from `<WORKFLOW_CONTEXT>`. |
+| `<AGENT_ROLE>` | Required | Agent persona and expertise. When inside a workflow, MUST reference its node name from `<WORKFLOW_CONTEXT>`. |
 | `<INPUT>` | Required | List ALL inputs. For workflow agents: workflow-level inputs first, then agent-specific inputs. |
 | `<STEPS>` | Optional | Include when the agent follows a non-trivial numbered sequence of steps. |
 | `<TOOL_GUIDANCE>` | Optional | Include when tool use order or conditions need explicit direction. |
@@ -200,7 +200,7 @@ The current OS is: [operating system name].
 **Formatting rules:**
 
 - MUST use XML tags to delimit every section.
-- The content of each section MUST start on the line immediately after the opening tag — never inline with it.
+- The content of each section MUST start on the line immediately after the opening tag — MUST NOT be inline with it.
 - Each closing tag MUST be followed by a blank line before the next opening tag, so sections are visually separated.
 
 ```xml
@@ -208,9 +208,9 @@ The current OS is: [operating system name].
 Produce a plan for the current batch of files.
 </OBJECTIVE>
 
-<ROLE>
+<AGENT_ROLE>
 You are the batch_plan_agent.
-</ROLE>
+</AGENT_ROLE>
 ```
 
 #### 07-agent-output-format

package/.xdrs/agentme/edrs/application/021-ai-workflow-development-standards.md

@@ -37,11 +37,11 @@ Use **MLflow** for all workflow observability and evaluation:
 
 #### 04-dataset-driven-accuracy-measurement
 
-Eval dataset and implementation requirements are defined in [agentme-edr-028](028-ai-eval-standards.md). Testing requirements (when evals are required, release gates) are defined in [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09-ai-project-testing-requirements`.
+Projects MUST follow the eval dataset and implementation requirements defined in [agentme-edr-028](028-ai-eval-standards.md). Testing requirements (when evals are required, release gates) are defined in [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09-ai-project-testing-requirements`.
 
 #### 05-flow-documentation
 
-Each workflow MUST be documented as a **Mermaid graph** in a `README.md`. The diagram must match the LangGraph `StateGraph` definition:
+Each workflow MUST be documented as a **Mermaid graph** in a `README.md`. The diagram MUST match the LangGraph `StateGraph` definition:
 
 - Use `graph TD` or `graph LR` direction.
 - Label each node with its Python function name.
@@ -101,20 +101,17 @@ lib/src/<package_name>/
 
 #### 08-workflow-evals
 
-Eval folder structure and script requirements are defined in [agentme-edr-028](028-ai-eval-standards.md).
+Projects MUST follow the eval folder structure and script requirements defined in [agentme-edr-028](028-ai-eval-standards.md).
 
 #### 09-node-naming-conventions
 
-See [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `01-node-naming-conventions`.
+Nodes MUST follow the naming conventions defined in [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `01-node-naming-conventions`.
 
 #### 10-workflow-unit-testing
 
-All LLM calls within workflow nodes are external API calls and MUST be mocked in unit tests per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`. Workflow unit tests must run fully offline with no real LLM provider calls.
+All LLM calls within workflow nodes are external API calls and MUST be mocked in unit tests per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`. Workflow unit tests MUST run fully offline with no real LLM provider calls.
 
-Choose the mock utility based on what the node under test expects from the model:
-
-- Use **`FakeListChatModel`** when nodes only read `AIMessage.content` (e.g. a routing node that checks a text label).
-- Use **`GenericFakeChatModel`** when any node in the workflow expects tool calls, structured outputs, or when the workflow contains `_agent` nodes that drive a tool-invocation loop.
+Choose the mock utility per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`. For workflows containing `_agent` nodes that drive a tool-invocation loop, MUST use `GenericFakeChatModel`.
 
 **Example — workflow with plain-text LLM nodes:**
 
@@ -159,15 +156,15 @@ Workflows MUST accept the LLM instance as a constructor parameter so that unit t
 
 #### 11-state-type-conventions
 
-See [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `02-state-type-conventions`.
+State types MUST follow the conventions defined in [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `02-state-type-conventions`.
 
 #### 12-workflow-naming-conventions
 
-See [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `04-workflow-naming-conventions`.
+Workflows MUST be named following the conventions in [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `04-workflow-naming-conventions`.
 
 #### 13-judge-node-output-format
 
-See [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `03-judge-node-output-format`.
+Judge nodes MUST use the output format defined in [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `03-judge-node-output-format`.
 
 #### 15-workflow-state-persistence
 
@@ -200,7 +197,7 @@ result = graph.invoke(input_state, config={"thread_id": "session-123"})
 
 #### 16-cross-element-naming-coherence
 
-See [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `05-cross-element-naming-coherence`.
+All workflow elements MUST maintain naming coherence as defined in [agentme-edr-029](029-ai-workflow-naming-conventions.md) rule `05-cross-element-naming-coherence`.
 
 ## References
 

package/.xdrs/agentme/edrs/application/025-ai-agent-xdrs-knowledge-layer.md

@@ -79,7 +79,7 @@ Follow [agentme-edr-019 rule 02-local-sandbox](019-ai-agents-development-standar
 | `lib/data/.xdrs/` | XDRS Policy and Skill documents | `/.xdrs/` (read-only) |
 | Generated at startup | `AGENTS.md` instructing the agent to consult XDRS | `/AGENTS.md` (read-only) |
 
-XDRS documents MUST always be mounted at `/.xdrs/`. `AGENTS.md` MUST always be placed at the sandbox root (`/AGENTS.md`).
+XDRS documents MUST be mounted at `/.xdrs/`. `AGENTS.md` MUST be placed at the sandbox root (`/AGENTS.md`).
 
 Example XDRS mount additions:
 

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

@@ -21,7 +21,7 @@ How should application source code be organized to separate business logic from
 
 #### 01-three-layer-separation
 
-Every application is conceptually divided into three layers:
+Every application MUST be organized into these three conceptual layers:
 
 | Layer | Description |
 |-------|-------------|
@@ -31,6 +31,8 @@ Every application is conceptually divided into three layers:
 
 #### 02-adapter-naming-conventions
 
+Adapters MUST follow these 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
@@ -50,7 +52,7 @@ Every application is conceptually divided into three layers:
 #### 03-application-layer-rules
 
 - Expose functionality as typed library interfaces
-- All inputs must be explicitly passed as typed parameters
+- 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)
@@ -66,6 +68,8 @@ Kafka message →  adapters/kafka/    →  app/process-event   →  adapters/con
 
 #### 04-mandatory-folder-structure
 
+All projects MUST follow this folder structure:
+
 ```text
 mysystem/
   Makefile             # targets to run different inbound interfaces (e.g. run-http, run-cli)
@@ -97,7 +101,7 @@ mysystem/
 
 #### 06-bootstrap-and-entry-points
 
-- Each inbound adapter folder (`cli/`, `http/`, `grpc/`, etc.) contains the bootstrap and entry point for that interface
+- 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](../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
 
@@ -135,7 +139,7 @@ When a mock implementation needs to be **reused across multiple tests or importe
 - Single-test use → define the mock inline inside the test file (per rule `09` example; no file needed)
 - Reusable across multiple tests OR used from `eval.py` → define in a separate `_mock` file
 
-**Scope:** applies to any source file in `adapters/connectors/`, `app/`, or `shared/`. MUST NOT be used for inbound adapters (`cli/`, `http/`, `grpc/`) — those are entry points and are never mocked (rule `09`).
+**Scope:** applies to any source file in `adapters/connectors/`, `app/`, or `shared/`. MUST NOT be used for inbound adapters (`cli/`, `http/`, `grpc/`) — those are entry points and MUST NOT be mocked (rule `09`).
 
 **Naming:** insert `_mock` immediately before the file extension:
 
@@ -151,7 +155,7 @@ When a mock implementation needs to be **reused across multiple tests or importe
 
 **Mock contract:**
 - MUST accept a `fixtures` parameter (constructor argument or factory function argument); the value is whatever `mock_fixtures[key]` contains from the dataset entry — its internal structure is opaque and interpreted by the mock implementation
-- MUST NOT fall back to real external calls under any circumstance — if a call cannot be satisfied from the provided fixtures, MUST raise an explicit error (never silently return `null`, `undefined`, or an empty value)
+- MUST NOT fall back to real external calls under any circumstance — if a call cannot be satisfied from the provided fixtures, MUST raise an explicit error (MUST NOT silently return `null`, `undefined`, or an empty value)
 
 ## References
 

package/.xdrs/agentme/edrs/application/028-ai-eval-standards.md

@@ -88,8 +88,8 @@ Each `eval.py` script MUST:
 
 - Load the golden dataset from `golden_dataset/` in the same eval folder, following [agentme-edr-024](024-ml-dataset-structure.md) and the entry envelope in [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `02` (one JSON file per entry, `test_types` array, `input`, `expected_output`, optional `mock_fixtures`).
 - Accept a required `--type=<test_type>|all` CLI argument and filter entries whose `test_types` array contains the requested value; `--type=all` includes every entry.
-- Iterate **entry-first**: for each entry in the filtered set, invoke the real component exactly once; then score that single `actual_output` for every `test_types` value the entry carries that falls within the current `--type` scope — never invoke the component more than once per entry per run.
-- When an entry contains `mock_fixtures` ([agentme-edr-030](030-ai-test-types-taxonomy.md) rule `02`), configure each named mock adapter with its fixture data BEFORE invoking the component for that entry. Each entry MUST use fresh mock instances so fixture state does not bleed across entries. `mock_fixtures` applies to all test types including `human`. `mock_fixtures` MUST NOT configure LLM adapters — the LLM call MUST always be real (see [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `03`). How mock adapters are discovered and instantiated is left to the project; see [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) rule `10` for the `_mock` file naming and placement convention.
+- Iterate **entry-first**: for each entry in the filtered set, invoke the real component exactly once; then score that single `actual_output` for every `test_types` value the entry carries that falls within the current `--type` scope — MUST NOT invoke the component more than once per entry per run.
+- When an entry contains `mock_fixtures` ([agentme-edr-030](030-ai-test-types-taxonomy.md) rule `02`), configure each named mock adapter with its fixture data BEFORE invoking the component for that entry. Each entry MUST use fresh mock instances so fixture state does not bleed across entries. `mock_fixtures` applies to all test types including `human`. `mock_fixtures` MUST NOT configure LLM adapters — the LLM call MUST be real (see [agentme-edr-030](030-ai-test-types-taxonomy.md) rule `03`). How mock adapters are discovered and instantiated is left to the project; see [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) rule `10` for the `_mock` file naming and placement convention.
 - Run every component invocation against **real LLM providers** (not mocked responses), to capture model drift.
 - For `human` entries: invoke the component to capture `actual_output`, export each entry's `input`, `expected_output.human_test` instructions, and `actual_output` into a manual-review checklist (`report-human.md`). MUST NOT invoke an automated scorer and MUST NOT enforce a pass/fail threshold for it. Other `test_types` on the same entry (e.g. `functional`) are still scored automatically.
 - After all entries are processed, compute aggregate metrics per test type, log them to a local MLflow experiment (see rule `04`), write one `report-<type>.md` per evaluated test type (rule `03`), and exit with a non-zero status when any metric falls below its defined threshold per [agentme-edr-007](../principles/007-project-quality-standards.md) rule `07-statistical-models-must-have-eval-targets`. The `human` type has no threshold and does not trigger a non-zero exit.
@@ -235,7 +235,7 @@ Where $\hat{p}$ is observed accuracy and $n$ is sample count. Accuracy and F1 ar
 - MLflow run: experiment `workflow-document-review/eval-basic`, tag `test_types=functional` — view with `mlflow ui`
 ```
 
-**`human` type artifact:** instead of `report-human.md` with metrics, `--type=human` produces a checklist artifact (still named `report-human.md`) listing, per entry, its `input`, `expected_output.human_test` instructions, and the captured `actual_output` — with no Overall Results table, threshold, or PASS/FAIL section, since this type is never auto-scored.
+**`human` type artifact:** instead of `report-human.md` with metrics, `--type=human` produces a checklist artifact (still named `report-human.md`) listing, per entry, its `input`, `expected_output.human_test` instructions, and the captured `actual_output` — with no Overall Results table, threshold, or PASS/FAIL section, since this type MUST NOT be auto-scored.
 
 #### 04-eval-mlflow-unique-port
 

package/.xdrs/agentme/edrs/application/029-ai-workflow-naming-conventions.md

@@ -46,7 +46,7 @@ def code_reviewer_agent(state): ...
 graph.add_node("code_reviewer_agent", code_reviewer_agent)
 ```
 
-Names MUST NOT use generic labels such as `node1`, `process`, or `run`. Each name must clearly express what action the node performs.
+Names MUST NOT use generic labels such as `node1`, `process`, or `run`. Each name MUST clearly express what action the node performs.
 
 Judge nodes use a **prefix** convention instead of a suffix: the name MUST start with `evaluate_` followed by the subject being judged (e.g. `evaluate_progress`, `evaluate_quality`, `evaluate_completeness`, `evaluate_relevance`). This makes judge nodes immediately distinguishable from all other node types at a glance.
 

package/.xdrs/agentme/edrs/application/030-ai-test-types-taxonomy.md

@@ -21,7 +21,7 @@ Each test type is named with its group, objective, mocking constraint, applicabi
 
 #### 01-golden-dataset-concept
 
-A **golden dataset** comprises all eval case entries used to test an AI component (LLM, Agent, or Workflow tier); each entry is labeled with the `test_types` (rule `04`) it applies to. It is the dataset consumed by [agentme-edr-028](028-ai-eval-standards.md) evals and stored as one JSON file per entry per [agentme-edr-024](024-ml-dataset-structure.md) rule `04`, at `evals/<component>/eval-<name>/golden_dataset/`.
+Projects MUST use a golden dataset to test AI components. A **golden dataset** comprises all eval case entries used to test an AI component (LLM, Agent, or Workflow tier); each entry is labeled with the `test_types` (rule `04`) it applies to. It is the dataset consumed by [agentme-edr-028](028-ai-eval-standards.md) evals and stored as one JSON file per entry per [agentme-edr-024](024-ml-dataset-structure.md) rule `04`, at `evals/<component>/eval-<name>/golden_dataset/`.
 
 #### 02-golden-dataset-entry-envelope
 
@@ -41,8 +41,8 @@ Every golden dataset entry (a JSON file in `golden_dataset/data/`) MUST have thi
 
 - `test_types` — array, values MUST come from rule `04`'s enum, MUST contain at least one value. An entry MAY carry more than one value additively (e.g. `["functional", "smoke", "human"]`) — no test type excludes another.
 - `input` — for Prompt-tier components, a raw prompt string or the prompt template's input parameters object; for Agent/Workflow-tier components, the input attributes object passed to the component.
-- `expected_output` — the fields used to score the entry under each of its automated `test_types`: output attributes for an LLM-as-judge rubric, a target for vector-similarity scoring, or exact attribute values for strict comparison. When `human` is one of the entry's `test_types`, `expected_output` MUST additionally include a `human_test` string field with manual-verification instructions (e.g. `"check for ethical issues, verify record change in system X"`) — this supplements, and never replaces, the entry's automated scoring fields.
-- `mock_fixtures` — optional object; keys identify the adapter or external system to mock (SHOULD match the connector folder name under `adapters/connectors/<name>` for readability, though not enforced), values are any valid JSON interpreted by the mock implementation. When present, eval.py MUST configure each named mock adapter with its fixture data BEFORE invoking the component for that entry; each entry MUST use fresh mock instances to prevent state from bleeding across entries. `mock_fixtures` applies to all `test_types` including `human` — the component is still invoked for human entries to capture `actual_output`. `mock_fixtures` MUST NOT include keys for LLM adapters: all golden dataset test types are rated `mocks disallowed for LLM calls` (rule `03`), so the LLM call MUST always be real; LLM provider mocking belongs exclusively to unit tests via [agentme-edr-018](018-ai-llm-development-standards.md) rule `04`. See [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) rule `10` for the `_mock` file naming and placement convention.
+- `expected_output` — the fields used to score the entry under each of its automated `test_types`: output attributes for an LLM-as-judge rubric, a target for vector-similarity scoring, or exact attribute values for strict comparison. When `human` is one of the entry's `test_types`, `expected_output` MUST additionally include a `human_test` string field with manual-verification instructions (e.g. `"check for ethical issues, verify record change in system X"`) — this supplements, and MUST NOT replace, the entry's automated scoring fields.
+- `mock_fixtures` — optional object; keys identify the adapter or external system to mock (SHOULD match the connector folder name under `adapters/connectors/<name>` for readability, though not enforced), values are any valid JSON interpreted by the mock implementation. When present, eval.py MUST configure each named mock adapter with its fixture data BEFORE invoking the component for that entry; each entry MUST use fresh mock instances to prevent state from bleeding across entries. `mock_fixtures` applies to all `test_types` including `human` — the component is still invoked for human entries to capture `actual_output`. `mock_fixtures` MUST NOT include keys for LLM adapters: all golden dataset test types are rated `mocks disallowed for LLM calls` (rule `03`), so the LLM call MUST be real; LLM provider mocking belongs exclusively to unit tests via [agentme-edr-018](018-ai-llm-development-standards.md) rule `04`. See [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) rule `10` for the `_mock` file naming and placement convention.
 - The dataset's `dataset.schema.json` MUST require `test_types`, `input`, and `expected_output`, and SHOULD declare `mock_fixtures` as optional (`"type": "object", "additionalProperties": {}`), per [agentme-edr-024](024-ml-dataset-structure.md) rule `04`.
 
 #### 03-mocks-allowed-values
@@ -61,6 +61,8 @@ A golden dataset entry's `test_types` array MUST only use these values: `safety`
 
 #### 05-test-type-taxonomy
 
+Test types MUST be selected from this taxonomy. Each test type is named with its group, objective, mocking constraint, applicability, and relevance:
+
 | Test Type Name | Group | Test Objective | Mocks Allowed | When to Apply | Relevance – Business | Relevance – Development Team | Priority (1-5) |
 |---|---|---|---|---|---|---|---|
 | Safety/content eval | Safety & adversarial | Detect harmful, biased, or policy-violating output | mocks disallowed for LLM calls | Any user-facing release | Avoids reputational harm; acceptable-use compliance | Automated content gate before merge/release | 5 |
@@ -79,11 +81,11 @@ A golden dataset entry's `test_types` array MUST only use these values: `safety`
 
 #### 06-priority-and-relevance-are-descriptive-only
 
-Priority, Relevance, and When to Apply in rule `05` are guidance for prioritization conversations — they do NOT mandate which test types a project must implement, nor their thresholds. [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09` remains the only tier-level testing requirement in force (Workflow unit tests + functional evals). Once a project chooses to implement and threshold a test type, [agentme-edr-028](028-ai-eval-standards.md) rule `02`'s failing-threshold behavior applies uniformly, regardless of this table's priority rating — a project may enforce fairness at 70% and functional at 90%, or skip fairness entirely; that choice is a project/business decision, not one this Policy makes.
+Priority, Relevance, and When to Apply in rule `05` are guidance for prioritization conversations — they MUST NOT be treated as mandating which test types a project must implement, nor their thresholds. [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09` remains the only tier-level testing requirement in force (Workflow unit tests + functional evals). Once a project chooses to implement and threshold a test type, [agentme-edr-028](028-ai-eval-standards.md) rule `02`'s failing-threshold behavior applies uniformly, regardless of this table's priority rating — a project may enforce fairness at 70% and functional at 90%, or skip fairness entirely; that choice is a project/business decision, not one this Policy makes.
 
 #### 07-smoke-is-distinct-from-test-smoke
 
-The `smoke` test type (surfaced as the `eval-smoke` Makefile target, a fast subset of the golden-dataset functional eval) is a different concept from [agentme-edr-008](../devops/008-common-targets.md)'s existing `test-smoke` target (a fast subset of code-level tests). Both may exist in the same project; do not conflate them.
+The `smoke` test type (surfaced as the `eval-smoke` Makefile target, a fast subset of the golden-dataset functional eval) is a different concept from [agentme-edr-008](../devops/008-common-targets.md)'s existing `test-smoke` target (a fast subset of code-level tests). Both MAY exist in the same project; teams MUST NOT conflate them.
 
 ## References
 

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

@@ -53,60 +53,60 @@ Module folder responsibilities, artifact locations, and test-folder conventions
 #### 02-application-folders
 
 - Represent a cohesive unit with its own lifecycle (e.g., `mymobileapp`, `graph-visualizer`).
-- **MUST** depend only on resources in `/shared/`. Direct cross-application dependencies are forbidden; use published artifacts (container images, published libraries) instead.
-- **MUST** contain a `README.md` with: purpose, architecture overview, how to build, and how to run.
-- **MAY** contain `examples/`, `tests_integration/`, and `tests_benchmark/` when those artifacts apply to multiple modules inside the application.
+- MUST depend only on resources in `/shared/`. Direct cross-application dependencies are forbidden; use published artifacts (container images, published libraries) instead.
+- MUST contain a `README.md` with: purpose, architecture overview, how to build, and how to run.
+- MAY contain `examples/`, `tests_integration/`, and `tests_benchmark/` when those artifacts apply to multiple modules inside the application.
 
 #### 03-module-folders
 
 - A module is a subfolder inside an application that is independently compilable and produces a build artifact.
 - May depend on sibling modules within the same application or on `/shared/` resources.
-- **MUST NOT** depend on modules from other applications.
-- **MUST** contain its own `Makefile`, `README.md`, and language/tooling configuration.
-- **MUST** keep build outputs under `dist/` and persistent caches under `.cache/`, following [agentme-edr-016](../principles/016-cross-language-module-structure.md).
-- **MUST NOT** keep consumer examples inside the module folder; those belong in a sibling `examples/` folder at the nearest parent aggregation root.
+- MUST NOT depend on modules from other applications.
+- MUST contain its own `Makefile`, `README.md`, and language/tooling configuration.
+- MUST keep build outputs under `dist/` and persistent caches under `.cache/`, following [agentme-edr-016](../principles/016-cross-language-module-structure.md).
+- MUST NOT keep consumer examples inside the module folder; those belong in a sibling `examples/` folder at the nearest parent aggregation root.
 
 #### 04-naming-conventions
 
-- All folder and file names **MUST** be **lowercase**.
+- All folder and file names MUST be lowercase.
 - Use hyphens (`-`) to separate words (e.g., `data-loader`, `graph-visualizer`).
 - Avoid abbreviations unless universally understood in the domain (e.g., `cli`, `api`).
 
 #### 05-makefiles-at-every-level
 
-A `Makefile` **MUST** be present at the repository root, in every application folder, and in every module folder.
+A `Makefile` MUST be present at the repository root, in every application folder, and in every module folder.
 
-All Makefiles **MUST** use the shared target vocabulary from [agentme-edr-008](008-common-targets.md).
+All Makefiles MUST use the shared target vocabulary from [agentme-edr-008](008-common-targets.md).
 
-Repository, application, and module Makefiles **MUST** define at minimum: `all`, `build`, `lint`, `test`, and `clean`.
+Repository, application, and module Makefiles MUST define at minimum: `all`, `build`, `lint`, `test`, and `clean`.
 
-Module Makefiles **SHOULD** also provide `lint-fix` and `install` when the underlying tooling supports them.
+Module Makefiles SHOULD also provide `lint-fix` and `install` when the underlying tooling supports them.
 
-The root `Makefile` **MUST** also define a `setup` target that guides a new contributor to prepare their machine.
-The root `setup` target **MUST** run `mise install` and any small repository bootstrap required before routine targets work.
+The root `Makefile` MUST also define a `setup` target that guides a new contributor to prepare their machine.
+The root `setup` target MUST run `mise install` and any small repository bootstrap required before routine targets work.
 
 #### 06-mise-for-tooling-management
 
-- [Mise](https://mise.jdx.dev/) **MUST** be used to pin all tool versions (compilers, runtimes, CLI tools).
-- A `.mise.toml` **MUST** exist at the repository root.
-- Every language runtime or CLI referenced by any module `Makefile`, CI workflow, or README command **MUST** be pinned in `.mise.toml`.
-- Contributors and CI run `make setup` after cloning or checkout; this target must call `mise install`.
-- Agents and contributors **MUST** check `.mise.toml` before using a system-installed compiler, runtime, or CLI.
-- When `.mise.toml` exists, all build, test, lint, and code-generation commands **MUST** run through `make <target>`, and the Makefile recipes **MUST** execute the underlying tools via `mise exec -- <command>`, following [agentme-edr-017](017-tool-execution-and-scripting.md).
-- If a required tool is missing, the first remediation step **MUST** be to update `.mise.toml` or run `mise install`, not to install ad-hoc global tools with language-specific installers such as `go install`, `npm install -g`, `pip install --user`, or `cargo install`.
-- Root and module `Makefile` targets **MUST** work when invoked as plain `make <target>` after `make setup`.
+- [Mise](https://mise.jdx.dev/) MUST be used to pin all tool versions (compilers, runtimes, CLI tools).
+- A `.mise.toml` MUST exist at the repository root.
+- Every language runtime or CLI referenced by any module `Makefile`, CI workflow, or README command MUST be pinned in `.mise.toml`.
+- Contributors and CI run `make setup` after cloning or checkout; this target MUST call `mise install`.
+- Agents and contributors MUST check `.mise.toml` before using a system-installed compiler, runtime, or CLI.
+- When `.mise.toml` exists, all build, test, lint, and code-generation commands MUST run through `make <target>`, and the Makefile recipes MUST execute the underlying tools via `mise exec -- <command>`, following [agentme-edr-017](017-tool-execution-and-scripting.md).
+- If a required tool is missing, the first remediation step MUST be to update `.mise.toml` or run `mise install`, not to install ad-hoc global tools with language-specific installers such as `go install`, `npm install -g`, `pip install --user`, or `cargo install`.
+- Root and module `Makefile` targets MUST work when invoked as plain `make <target>` after `make setup`.
 
 #### 07-root-readme
 
-The root `README.md` **MUST** include: overview, machine setup, quickstart, and a repository map.
+The root `README.md` MUST include: overview, machine setup, quickstart, and a repository map.
 
 #### 08-root-gitignore
 
-The repository root **MUST** ignore `dist/` and `.cache/` so module artifacts and tool caches are never committed accidentally.
+The repository root MUST ignore `dist/` and `.cache/` so module artifacts and tool caches MUST NOT be committed accidentally.
 
 #### 09-git-tagging-and-artifact-versioning
 
-All releases **MUST** be tagged using the format `<module-name>/<semver>` (e.g., `graphvisualizer/renderer/1.0.0`, `shared/libs/mylib/2.1.0`).
+All releases MUST be tagged using the format `<module-name>/<semver>` (e.g., `graphvisualizer/renderer/1.0.0`, `shared/libs/mylib/2.1.0`).
 
 `<module-name>` is preferably the path-like identifier of the module being released. A custom name is allowed but the folder name is strongly preferred.
 
@@ -114,6 +114,8 @@ All releases **MUST** be tagged using the format `<module-name>/<semver>` (e.g.,
 
 #### 11-summary-of-requirements
 
+All requirements marked 'Yes' MUST be met. The table below summarizes the mandatory requirements:
+
 | Requirement | Scope | Mandatory |
 |---|---|---|
 | Lowercase folder/file names | All | Yes |

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

@@ -29,7 +29,7 @@ Separating these concerns eliminates accidental publishes from CI runs, ensures
 | `release.yml` | `workflow_dispatch` | Tag the next version using monotag |
 | `publish.yml` | `push` of tags matching `*` | Publish artifacts for the tagged version |
 
-All workflows run on `ubuntu-latest`. Tool versions MUST be managed by Mise via `jdx/mise-action`. Projects should have a .mise.toml file to configure it
+All workflows run on `ubuntu-latest`. Tool versions MUST be managed by Mise via `jdx/mise-action`. Projects SHOULD have a `.mise.toml` file to configure it
 
 ---
 
@@ -37,7 +37,7 @@ All workflows run on `ubuntu-latest`. Tool versions MUST be managed by Mise via
 
 File: `.github/workflows/ci.yml`
 
-Triggered on every PR targeting `main` and every push to `main`. Runs the standard `build`, `lint`, and `test` targets from the root Makefile and fails the workflow if any step exits non-zero.
+Projects MUST configure this workflow, triggered on every PR targeting `main` and every push to `main`. It runs the standard `build`, `lint`, and `test` targets from the root Makefile and fails the workflow if any step exits non-zero.
 
 ```yaml
 name: ci
@@ -67,9 +67,9 @@ jobs:
 
 File: `.github/workflows/release.yml`
 
-Manually dispatched (`workflow_dispatch`). Calculates the next semantic version tag using **monotag** and pushes that tag to the repository. Pushing the tag then automatically triggers the publish workflow.
+Projects MUST use this manually dispatched (`workflow_dispatch`) workflow. It calculates the next semantic version tag using **monotag** and pushes that tag to the repository. Pushing the tag then automatically triggers the publish workflow.
 
-The checkout step **must** use `fetch-depth: 0` so monotag can traverse the full commit history to determine the correct next version.
+The checkout step MUST use `fetch-depth: 0` so monotag can traverse the full commit history to determine the correct next version.
 
 ```yaml
 name: release
@@ -112,7 +112,7 @@ jobs:
 
 File: `.github/workflows/publish.yml`
 
-Triggered exclusively when a tag matching `v*.*.*` is pushed to the repository. This ensures only explicitly tagged commits produce published artifacts. Runs `make publish` against the tagged commit.
+Projects MUST configure this workflow, triggered exclusively when a tag matching `v*.*.*` is pushed to the repository. This ensures only explicitly tagged commits produce published artifacts. Runs `make publish` against the tagged commit.
 
 ```yaml
 name: publish