@danmoisan/drm-copilot-mcp 0.0.1

package/resources/claude-customizations/.claude/rules/general-code-change.md

@@ -0,0 +1,71 @@
+---
+paths:
+  - "**"
+description: Cross-language code change policy. Applies to all files.
+---
+
+# General Code Change Policy
+
+This rule file summarizes the cross-language code change policy for this repository.
+
+## Design Principles
+
+Apply these priorities in order when designing or changing code:
+
+1. **Simplicity first** — Prefer the simplest design that works and is readable. Avoid cleverness and deep indirection.
+2. **Reusability** — Factor out logic that is clearly reusable. Avoid copy-paste; share behavior via composition or helper methods.
+3. **Extensibility** — Design public APIs so they can be extended without breaking callers. Prefer keyword-style parameters with defaults. Prefer composition over inheritance. Use interfaces/abstract types/protocols to support multiple implementations.
+4. **Separation of concerns** — Keep pure logic (transforms, calculations, parsing) separate from I/O (disk, network, DB), UI/CLI, and framework-specific glue.
+
+## Classes, Functions, and APIs
+
+- Create a class when: there is a clear domain concept with data + behavior, state and invariants must travel together, multiple implementations behind an interface are expected, or a multi-step workflow shares context.
+- Create a standalone function when: the operation is pure, stateless, and simple; it is a small helper that does not naturally belong on a domain class; or it is a simple transformation from inputs to outputs.
+- Keep methods small and focused. Avoid god objects.
+- Use interfaces/abstract types/protocols when multiple implementations are likely.
+
+## Mandatory Toolchain Loop
+
+Run the full toolchain in this exact order and repeat until all steps pass in a single pass:
+
+1. **Formatting** (e.g., Black, Prettier, CSharpier, Invoke-Formatter)
+2. **Linting** (e.g., Ruff, ESLint, PSScriptAnalyzer, .NET analyzers)
+3. **Type checking** (e.g., Pyright, TSC, nullable analysis; skip for PowerShell)
+4. **Testing** (e.g., Pytest, Jest, MSTest, Pester)
+
+**Restart from step 1** if any step fails or auto-fixes any files. Do not stop the loop until all four steps complete without errors in a single pass.
+
+## File Size Limit
+
+- No production code, test code, or reusable script file may exceed **500 lines**.
+- Exceptions: temporary throwaway scripts created and deleted within an agent session; raw text fixtures for language-processing test data; Markdown documentation files.
+
+## Error Handling and Logging
+
+- **Fail fast and explicitly**: raise or return clear, specific errors when invariants are violated.
+- Do not silently ignore errors. Do not use broad catch-all handlers unless you immediately re-raise or propagate with added context.
+- Use the project's established logging pattern. Log at appropriate levels (`debug`, `info`, `warning`, `error`).
+- Enforce invariants at construction/initialization time.
+- Use assertions only for internal sanity checks, not user-facing error handling.
+
+## Naming
+
+- Names must be descriptive. Abbreviations are acceptable only when they are standard (`id`, `url`, `db`).
+- Language-specific conventions: `snake_case` for Python functions/variables, `PascalCase` for Python classes, `camelCase` for TypeScript/C# locals, `PascalCase` for TypeScript/C# types and public members.
+
+## Public APIs and Compatibility
+
+- Prefer keyword-style parameters with defaults.
+- Prefer composition over inheritance when possible.
+- Avoid breaking public APIs. If a breaking change is necessary, update all callers in-repo and call it out clearly in the change description.
+
+## Dependencies
+
+- Use only libraries already approved in the project unless explicitly told to add more.
+- If adding a dependency is unavoidable, choose a well-maintained, widely used package and document why it is required.
+
+## I/O Boundaries
+
+- Isolate I/O (disk, network, APIs) into specific classes or modules.
+- Core domain logic must be testable without touching the network or filesystem.
+- Use of temporary files within tests is strictly prohibited.

package/resources/claude-customizations/.claude/rules/general-unit-test.md

@@ -0,0 +1,60 @@
+---
+paths:
+  - "**"
+description: Cross-language unit test policy. Applies to all files.
+---
+
+# General Unit Test Policy
+
+This rule file summarizes the cross-language unit test policy for this repository.
+
+## Core Principles
+
+Every unit test must satisfy all five of these properties:
+
+1. **Independence** — Tests must be able to run in any order without impacting each other.
+2. **Isolation** — Each unit test targets a single function, method, or unit of behavior so failures clearly identify the faulty unit.
+3. **Fast execution** — Tests must be fast enough to support frequent runs and rapid feedback loops.
+4. **Determinism** — Given the same inputs and environment, tests must produce the same results. Avoid flakiness.
+5. **Readability and maintainability** — Test names, structure, and assertions must be clear and easy to understand.
+
+## Coverage Requirements
+
+- **Repository-wide line coverage must remain >= 80%.**
+- **Any new module, class, or method must target >= 90% coverage.**
+- Code changes or refactors must not reduce coverage for the lines that were changed.
+- Coverage is a supporting metric, not the sole quality gate. Untested critical behavior is not acceptable even if the overall percentage looks good.
+- Configure coverage tooling to exclude test files (e.g., `tests/`) so metrics reflect application code, not tests.
+
+## Scenario Completeness
+
+For each unit or behavior, tests must cover:
+
+- Positive flows with valid inputs
+- Negative flows for invalid or missing inputs
+- Edge cases and boundary conditions
+- Error-handling behavior
+- Concurrency behavior when relevant
+- State transitions for stateful components
+
+## Test Structure — Arrange–Act–Assert
+
+Organize each test into three sections:
+
+- **Arrange** — set up inputs, environment, and dependencies
+- **Act** — execute the behavior under test
+- **Assert** — verify outcomes via assertions
+
+Assertions must produce clear, actionable failure messages.
+
+## External Dependencies
+
+- Unit tests must not depend on external services (databases, networks, remote APIs, external processes).
+- Use mocks, stubs, or fakes to isolate the unit under test when code interacts with external systems.
+- **Creation and use of temporary files in tests is strictly prohibited.**
+- Tests must not rely on mutable global state or external configuration that can change between runs.
+
+## Documentation
+
+- Each test must clearly communicate its purpose via a descriptive name and/or a short docstring or comment summarizing the scenario and expected outcome.
+- Group related tests logically within the same file or test class.

package/resources/claude-customizations/.claude/rules/powershell.md

@@ -0,0 +1,97 @@
+---
+paths:
+  - "**/*.ps1"
+  - "**/*.psm1"
+  - "**/*.psd1"
+description: PowerShell-specific toolchain and coding standards.
+---
+
+# PowerShell Code Standards
+
+This rule file summarizes the PowerShell-specific policies for this repository.
+
+## Toolchain
+
+1. **Formatting — Invoke-Formatter**: Format all PowerShell files via PoshQC. MCP command: `mcp__drmCopilotExtension__run_poshqc_format`
+2. **Linting — PSScriptAnalyzer**: Run PoshQC analyzer with repo settings. MCP command: `mcp__drmCopilotExtension__run_poshqc_analyze`. Optional autofix: `mcp__drmCopilotExtension__run_poshqc_analyze_autofix`
+3. **Type checking**: Not applicable for PowerShell; skip to testing.
+4. **Testing — Pester (v5.x)**: Run tests via MCP. MCP command: `mcp__drmCopilotExtension__run_poshqc_test`. Use repo config at `scripts/powershell/PoshQC/settings/pester.runsettings.psd1`.
+
+Run the toolchain in order: format → analyze → test. Restart from step 1 if any step fails or changes files. Use the MCP server functions; do not substitute VS Code task wrappers.
+
+## Compatibility
+
+- All scripts must be compatible with **PowerShell 7+** (enforced via PSScriptAnalyzer settings).
+
+## Coding Standards
+
+- Prefer **advanced functions** with `CmdletBinding()` and named parameters.
+- Add `[Parameter(Mandatory = $true)]` and validation attributes where appropriate.
+- Implement **ShouldProcess/SupportsShouldProcess** for state-changing actions.
+- Avoid global state and mutable script-scoped variables; pass data explicitly.
+- Avoid `Invoke-Expression`, plaintext secrets, and hard-coded credentials/paths.
+- Use `Write-Error`/`throw` for failures; avoid silent catch-alls.
+- Use approved verbs and descriptive nouns for function names (PSScriptAnalyzer enforces this).
+- Keep scripts cohesive and under 500 lines.
+
+## Change Budget
+
+- Direct-mode overall scope: up to 2 production PowerShell files (plus corresponding tests). Requests exceeding this must be routed to `powershell-orchestrator` per `powershell-change-budget-router`.
+- Per-batch cap in all modes: at most 3 production files and 3 test files unless an explicit override has been approved.
+- If a batch would exceed the cap, split the work into smaller batches.
+
+## Design Seams (Minimal DI)
+
+Introduce the smallest seam that enables reliable mocking. Apply these options in order:
+
+1. **Wrapper function seam (preferred)** — extract external executable calls into a wrapper function:
+   - Signature: `Invoke-<Tool>Exe -<Tool>Args <string[]>` (for example `Invoke-GitExe -GitArgs <string[]>`).
+   - The wrapper accepts a single array parameter and splats into the executable: `git @GitArgs 2>&1`.
+   - Parameter names must not be `Args` (automatic variable collision). Use `GitArgs`, `ToolArgs`, or `Arguments`.
+2. **Injectable delegate / ScriptBlock seam** — only when a wrapper is insufficient, add a narrowly-scoped optional delegate or `ScriptBlock` parameter with a safe default. Do not introduce generic runner frameworks.
+3. **Adapter seams for non-executable boundaries** — for filesystem, environment, or clock dependencies, introduce tiny helpers or narrow injectable parameters rather than threading raw I/O through domain logic.
+
+## Testing Standards
+
+- Use **Pester** (v5.x) as the test framework.
+- Organize tests to mirror code structure (e.g., `tests/scripts/dev-tools/ScriptName.Tests.ps1`).
+- Name test files `*.Tests.ps1`.
+- Use `Describe`/`Context`/`It` blocks; one behavior per `It`.
+- Write focused tests exercising a single function or behavior.
+- Mock sparingly; prefer real code paths.
+- No external dependencies in unit tests.
+- Repository-wide line coverage must remain >= 80%.
+- Any new module, class, or method must reach >= 90% coverage.
+- Coverage regression on changed lines is a blocking finding.
+
+### Deterministic Test Requirements
+
+Tests must not depend on:
+
+- network access,
+- mutable machine PATH or profile state,
+- implicit working-directory assumptions,
+- external services or live executables.
+
+Tests must produce identical results in Terminal and the VS Code Test Explorer. Assume a different PATH, current working directory, profile, and host when tests are run from Test Explorer; do not rely on ambient environment resolution.
+
+### Mocking Rules
+
+1. **External executable mocking** — never mock `git`, `gh`, `actionlint`, or other executables directly. Mock the wrapper function (for example `Invoke-GitExe`) instead.
+2. **Mock signature parity** — mock signatures must match production named parameters exactly. Example:
+   - production: `Invoke-GitExe -GitArgs $gitArgs`
+   - test mock: `param([string[]]$GitArgs)`
+3. **Mock registration order** — register mocks before the code under test can resolve commands, so Test Explorer parity is preserved.
+4. **AST/ScriptBlock import order** — when importing script functions via AST or `ScriptBlock` patterns:
+   - dot-source the returned `ScriptBlock` in the test scope,
+   - import dependencies in the correct order,
+   - import wrapper seams before mocking them when executable calls exist.
+
+## Prohibited Behaviors
+
+- Broad refactors across unrelated scripts or modules.
+- Introducing generic process-runner frameworks to replace the wrapper seam pattern.
+- Creating PSScriptAnalyzer debt and deferring cleanup.
+- Weakening assertions merely to make tests pass.
+- Adding sleeps, retries, or timing hacks to stabilize flaky tests.
+- Claiming success without running the required toolchain.

package/resources/claude-customizations/.claude/rules/python-suppressions.md

@@ -0,0 +1,143 @@
+---
+paths:
+  - "**/*.py"
+description: Pre-authorized Python Ruff and Pyright suppression patterns. Applies to Python files.
+---
+
+# Python Suppression Policy
+
+This rule file summarizes the suppression authorization policy for Python code.
+
+## Authorization Requirement
+
+All `# noqa` and `# type: ignore` suppressions must either:
+1. **Match a pre-authorized pattern** defined in this file, OR
+2. **Have explicit user approval** for that specific suppression.
+
+**Escalation path before requesting approval:**
+1. First, attempt to resolve the error without a suppression (refactor, restructure, use approved patterns).
+2. If that fails, try at least five more distinct approaches.
+3. Continue iterating until you solve the problem or clearly demonstrate why each approach fails.
+4. Only after multiple documented failed attempts may you request user approval, providing: the specific rule/error code, each approach tried and why it failed, and why a suppression is the only remaining option.
+
+## Pre-Authorized `# noqa` Patterns
+
+### S603 — Subprocess with validated executable
+
+**When authorized:** Subprocess calls where the executable is validated via `shutil.which()` before use.
+
+**Required comment format:** `# noqa: S603 - static analysis can't verify runtime validation`
+
+**Rationale:** Cross-platform compatibility requires runtime PATH resolution. Static analysis cannot trace the runtime validation, but the code is safe because the executable path is resolved from PATH (not user input), existence is verified before use, and hardcoding platform-specific paths would break portability.
+
+---
+
+### ARG002 — Unused method argument in test mocks
+
+**When authorized:** Test mock/stub implementations that must match interface signatures but do not use all parameters. Must be in test code (`tests/` directory) implementing a known interface.
+
+**Required comment format:** `# noqa: ARG002 - mock API signature` or `# noqa: ARG002 - match [InterfaceName] API`
+
+---
+
+### B008 — Function call in default argument (Typer)
+
+**When authorized:** Typer CLI option declarations where `Option()` must be evaluated at import time for CLI metadata. Must be a Typer option declaration in a CLI function signature.
+
+**Required comment format:** `# noqa: B008 - Typer framework pattern`
+
+---
+
+### TCH002 / TCH003 — Type checking block violations
+
+**When authorized:** Modules used for both runtime and type hints (pytest fixtures, Typer type hints, runtime `isinstance` checks). The module must be used at runtime and cannot be moved to a `TYPE_CHECKING` block without breaking functionality.
+
+**Required comment format:** `# noqa: TCH002 - [module] required at runtime for [reason]` or `# noqa: TCH003 - [module] required at runtime for [reason]`
+
+---
+
+### S310 — URL open with urllib (trusted endpoints)
+
+**When authorized:** Accessing documented, trusted HTTPS API endpoints with timeout. URL must be a validated HTTPS endpoint, domain must be a documented trusted source, timeout must be set, and the URL must not come from user input.
+
+**Required comment format:** `# noqa: S310 - trusted HTTPS endpoint: [domain]`
+
+---
+
+### S314 — XML parsing with ElementTree (trusted sources)
+
+**When authorized:** Parsing user's own local files (EPUB, configuration) or known-safe data sources (Wikipedia dumps, curated datasets). Must NOT be parsing untrusted network data.
+
+**Required comment format:** `# noqa: S314 - parsing trusted [source type]`
+
+---
+
+### BLE001 — Blind except (CLI entry points only)
+
+**When authorized:** Top-level CLI exception handlers for user-friendly error messages and clean exits. Must be at a CLI entry point, must log or display the error with context, and must exit cleanly. NOT allowed in library or internal code.
+
+**Required comment format:** `# noqa: BLE001 - CLI top-level error handling`
+
+---
+
+### S301 — Pickle deserialization (trusted model artifacts)
+
+**When authorized:** Loading known model artifacts from hardcoded trusted local paths. Path must be hardcoded or validated (not from user input or CLI args). Only for ML model/artifact loading.
+
+**Required comment format:** `# noqa: S301 - trusted model artifact from hardcoded path`
+
+---
+
+### S108 / S105 — Hardcoded paths/passwords in tests only
+
+**When authorized:** Test fixtures with example paths and test data literals. Must be in test code only. Not actual secrets or production paths.
+
+**Required comment format:** `# noqa: S108 - test fixture path` or `# noqa: S105 - test fixture data`
+
+---
+
+## Pre-Authorized `# type: ignore` Patterns
+
+### import-untyped — Optional third-party dependency without stubs
+
+**When authorized:** Optional third-party dependencies that lack type stubs or `py.typed` marker. Import must be in a `try/except ImportError` block; library must be optional; no type stubs available; library lacks `py.typed` marker.
+
+**Required comment format:** `# type: ignore[import-untyped]` with a comment on the same or adjacent line explaining the library and why stubs are absent.
+
+---
+
+## Explicitly Not Authorized (with Required Workarounds)
+
+### S110 — `try`-`except`-`pass` fallback chains
+
+**Not authorized.** Use explicit platform detection via `shutil.which()` or environment variable checks instead. `try`-`except`-`pass` chains hide lazy design and make behavior unpredictable.
+
+**Workaround:** Resolve the correct method at design time using `shutil.which()` for executables or explicit platform detection. Cache the result to avoid repeated detection overhead.
+
+---
+
+### TID252 — Relative imports beyond top-level package
+
+**Not authorized.** Use absolute imports (`from project.module import Thing`) instead of parent-relative imports (`from ..module import`).
+
+---
+
+### S607 — Starting process with partial executable path
+
+**Not authorized.** Resolve executables via `shutil.which()` first; use the full path returned by `which()`. This satisfies both S607 and the pre-authorized S603 pattern.
+
+---
+
+### D401, F401, UP017
+
+**Not authorized.** Fix the root cause: rewrite docstrings in imperative mood (D401), remove unused imports (F401), and use timezone-aware datetime (UP017).
+
+---
+
+## Policy Enforcement Checklist
+
+Before using any suppression, verify:
+- [ ] Pattern exactly matches a pre-authorized pattern above.
+- [ ] Required comment format is used verbatim.
+- [ ] All contextual requirements are met (e.g., in tests/, validated path, try/except block).
+- [ ] Suppression scope is as narrow as possible (single line, not file-level).

package/resources/claude-customizations/.claude/rules/python.md

@@ -0,0 +1,99 @@
+---
+paths:
+  - "**/*.py"
+description: Python-specific toolchain and coding standards.
+---
+
+# Python Code Standards
+
+This rule file summarizes the Python-specific policies for this repository.
+
+## Toolchain
+
+1. **Formatting — Black**: All Python code must be formatted with Black (default settings). Command: `poetry run black .`
+2. **Linting — Ruff**: Python code must pass Ruff using the project configuration. Command: `poetry run ruff check .` Suppressions require pre-authorization per `python-suppressions.instructions.md` or explicit user approval.
+3. **Type Checking — Pyright**: All Python code must be fully type-annotated and pass Pyright. Avoid `Any` unless unavoidable and commented. Command: `poetry run pyright`
+4. **Testing — Pytest**: All tests use Pytest. New logic must have test coverage >= 90%. Command: `poetry run pytest --cov --cov-report=term-missing`
+
+Run the toolchain in order: format → lint → type-check → test. Restart from step 1 if any step fails or changes files. Do not stop the loop until all four steps complete without errors in a single pass.
+
+If the environment prevents running tools, stop implementation and provide a plan and proposed diffs only, clearly marked **unverified**.
+
+## Coding Standards
+
+- **PEP 8 naming**: `snake_case` for functions/methods/variables, `PascalCase` for classes/exceptions, `CONSTANT_CASE` for module constants.
+- **Strong typing**: All public functions and methods must have full type hints for parameters and return values.
+- **Dataclasses**: Prefer `@dataclass` for value objects. Use `frozen=True` where appropriate. Enforce invariants in `__post_init__` (dataclasses) or `__init__`.
+- **Protocols**: Use `typing.Protocol` or `abc.ABC` when multiple implementations are expected.
+- **Imports**: Prefer absolute imports. Avoid circular dependencies.
+- **Error handling**: Fail fast with specific exceptions. Avoid broad `except:` or `except Exception:` without context. Reserve broad handlers for well-defined boundaries (CLI/entrypoints) with context logging.
+- **Assertions**: Use `assert` only for internal sanity checks, not for user-facing validation.
+- **Logging**: Use the standard `logging` module. No ad-hoc `print` statements for permanent behavior.
+
+## Python Design Rules
+
+### Small, cohesive modules
+
+- Each class or module has one clear purpose. Avoid grab-bag utilities.
+- Prefer explicit names and straightforward control flow.
+- Keep the public surface area small. Internal helpers are `_prefixed` or live in `_internal` modules.
+
+### Classes vs functions
+
+Create a class when at least one of the following is true:
+
+- A clear domain concept with data and behavior.
+- State and invariants must travel together.
+- Multiple implementations behind a common interface are expected.
+- A multi-step workflow shares context across steps.
+
+Create a standalone function when:
+
+- The operation is pure, stateless, and simple.
+- It is a small helper that does not naturally belong on a specific domain class.
+- It is a simple transformation from inputs to outputs.
+
+Keep methods small and focused. Avoid god objects that know about too many unrelated concerns. Avoid long, deeply branching functions; factor logic into smaller helpers.
+
+### Strong typing by default (Pyright-clean)
+
+- All public functions, methods, and constructors must have complete type hints.
+- Avoid `Any`. If unavoidable, isolate it by wrapping untyped libraries behind small typed adapters.
+- Use line-specific `# type: ignore[...]` only when justified with a brief comment.
+- Prefer `typing.Protocol` (or `abc.ABC`) only when multiple implementations are expected.
+
+### Dependency seams (testability without frameworks)
+
+Introduce the smallest seam that enables reliable testing:
+
+- Inject collaborators via constructor parameters (preferred).
+- Accept optional callables with sensible defaults for time/randomness (for example, `clock: Callable[[], datetime] = datetime.now`).
+- Extract boundary interactions into a tiny helper function and patch that helper in tests.
+
+Do not introduce generic service-locator patterns or heavy dependency-injection frameworks.
+
+## Pytest Rules
+
+- Use **Pytest** as the test runner.
+- One behavior per test. Follow Arrange–Act–Assert structure.
+- Use descriptive `test_...` function names.
+- Prefer behavioral assertions over implementation detail.
+- Use `pytest.mark.parametrize` for boundary matrices.
+- Fixtures should be narrow by default (function scope unless justified).
+- Mock sparingly; prefer real pure code paths. Use `monkeypatch` for environment variables and module attributes.
+- Patch at the **import location used by the unit under test**, not where a symbol originated.
+- No sleeps, retries, or timing hacks.
+- Organize tests to mirror code structure (for example, `tests/test_module_name.py` for `module_name.py`).
+- No external dependencies (network, databases, external processes, runtime filesystem temp files) in unit tests.
+- Repository-wide line coverage must remain >= 80%.
+- Any new module, class, or method must reach >= 90% coverage.
+- Coverage regression on changed lines is a blocking finding.
+
+## Prohibited Behaviors
+
+- Broad refactors across multiple modules outside the approved scope.
+- Adding new dependencies without explicit user instruction.
+- Reducing typing strictness to make Pyright pass.
+- Weakening tests to make them pass (removing assertions, overbroad exception checks).
+- Using runtime temp files or external services in unit tests.
+- Claiming success without running the toolchain.

package/resources/claude-customizations/.claude/rules/self-explanatory-code-commenting.md

@@ -0,0 +1,97 @@
+---
+paths:
+  - "**/*.py"
+description: Intent-first docstring and commenting standards. Applies to Python files.
+---
+
+# Code Commenting and Docstring Policy
+
+This rule file summarizes the code commenting and docstring requirements for Python code in this repository.
+
+## Core Principle
+
+Write code that is readable, but assume the maintainer may not know the intent. Docstrings are mandatory for classes and functions. Inline comments explain intent, flow, and decision logic — especially around iteration and branching. Avoid low-value comments that merely narrate the obvious.
+
+## Mandatory Class Docstrings
+
+Every class must have a docstring covering, at minimum:
+
+- **Purpose**: what the class represents or coordinates.
+- **Responsibilities**: what it does and does not do (scope boundaries).
+- **Usage**: lifecycle, typical call pattern, and collaboration with other objects.
+- **High-level flow**: the main steps the class performs or orchestrates.
+- **Key invariants/constraints**: expectations that must hold (e.g., sorted inputs, caching semantics).
+- **Important side effects**: I/O, persistence, network calls, mutation, concurrency.
+- **Attributes** (when non-obvious): what the stored fields mean and how they are populated.
+
+Preferred docstring style: Google-style with `Args:`, `Returns:`, `Raises:`, and `Attributes:` sections where applicable.
+
+## Mandatory Function and Method Docstrings
+
+Every function and method (including private helpers) must have a docstring that includes:
+
+- **Purpose and behavior**: what it accomplishes.
+- **Parameters**: meaning, constraints, and how used (types included, even when type hints are present).
+- **Returns**: meaning and shape of the return value (or explicitly state `None` for procedures).
+- **Raises**: key exceptions that are part of the contract (not every incidental exception, but contract-relevant ones).
+- **Side effects**: if it mutates inputs, writes to disk/DB, emits events, etc.
+
+Keep docstrings accurate and contract-oriented. If behavior changes, docstrings must be updated. If a method is a thin wrapper, say so explicitly and explain why the wrapper exists.
+
+## Loops and Comprehensions — Intent Comments Required
+
+Every `for` loop, `while` loop, and non-trivial list/dict/set comprehension must have an **intent comment immediately above it** explaining what the loop accomplishes and why.
+
+- If the intent of a comprehension cannot be explained clearly in one short comment, prefer expanding to an explicit loop with a comment.
+- Line-by-line narration of trivial loop counters is not required; explain the purpose of the iteration as a whole.
+
+## Branching — Decision-Logic Comments Required
+
+For any conditional branching beyond a trivial guard clause, add a comment that explains:
+
+- The decision criteria (what distinguishes branches).
+- Why the ordering matters (if it does).
+- The business/system rationale for why this branching exists.
+
+This applies to `if`/`elif`/`else` chains and `match`/`case` statements. For `match/case`, include a short "routing table" explanation of what each case handle.
+
+## Multi-Step Blocks — Meta-What Comments
+
+When a sequence of tactical lines collectively accomplishes a larger goal, precede the block with a **meta-what + why comment** that describes the overall purpose of the block and the rationale for its approach.
+
+If the block is substantial, strongly prefer extracting it into a helper method with its own docstring.
+
+## 6) Do not number notes
+
+In code comments and docstrings, **do not** use fragile numbered notes like:
+
+* `NOTE 1: ...`
+* `NOTE 2: ...`
+
+Prefer comments without tags for general explanations. But if a tag is necessary (e.g. follow-up is needed), use unnumbered tags instead:
+
+* `TODO: ...`
+* `WARNING: ...`
+* `PERF: ...`
+* `SECURITY: ...`
+
+## Meta-What vs. Narration
+
+- **Allowed:** Comments that describe the intent and purpose of a loop, branch, or multi-step block.
+- **Prohibited:** Line-by-line narration that merely restates what a single obvious line does.
+
+Example of prohibited narration: `# increment counter` above `count += 1`
+
+Example of allowed meta-what: `# Walk all changed files and collect those that exceed the size limit for the report` above a filtering loop.
+
+## Quality Checklist
+
+Before finalizing code:
+
+- [ ] Docstrings exist for every class and every function/method.
+- [ ] Docstrings explain purpose, usage, flow, args, returns, and contract-level raises/side effects.
+- [ ] Loops and comprehensions have intent comments (or are expanded for clarity).
+- [ ] Branching has decision-logic comments.
+- [ ] Multi-step blocks have meta-what + rationale comments above them.
+- [ ] No numbered notes (`NOTE 1:`, `NOTE 2:`) appear in comments or docstrings.
+- [ ] Comments remain accurate and add real explanatory value.

package/resources/claude-customizations/.claude/rules/tonality.md

@@ -0,0 +1,80 @@
+---
+paths:
+  - "**"
+description: Required communication tone policy. Applies to all files and responses.
+---
+
+# Tonality Policy
+
+This rule file summarizes the required tone policy for all agent-authored content in this repository.
+
+## Required Professional Tone
+
+All written output must use a professional tone. Professional tone means:
+
+- Clear, direct, and factual language.
+- Neutral businesslike phrasing.
+- Measured statements that match the available evidence.
+- Concise explanations that prioritize clarity over personality.
+- Respectful wording, even when reporting defects, regressions, or disagreements.
+
+Preferred characteristics: specific rather than vague; literal rather than theatrical; calm rather than excited; precise rather than promotional.
+
+## Humor and Joking — Prohibited
+
+Do not use jokes, banter, playful remarks, sarcasm, puns, or comedic phrasing.
+
+This prohibition includes:
+- Lighthearted commentary intended to entertain.
+- Winking or self-aware jokes about tools, code, bugs, or the development process.
+- Casual filler that weakens a formal or operational message.
+- Mocking, teasing, or exaggerated "fun" framing, even when mild.
+
+When deciding between a playful sentence and a plain sentence, use the plain sentence.
+
+## Hyperbole — Prohibited
+
+Do not use hyperbolic, inflated, or sensational language. Avoid:
+
+- Claims that something is perfect, flawless, amazing, incredible, revolutionary, or world-class (unless directly quoting an authoritative source and clearly marking it as a quotation).
+- Overstated certainty that goes beyond the verified evidence.
+- Dramatic framing that overstates urgency, difficulty, simplicity, risk, or impact.
+
+Use measured alternatives: replace absolute praise with evidence-based descriptions; replace dramatic warnings with specific risks and consequences; replace sweeping claims with concrete observations.
+
+## Metaphors — Tightly Restricted
+
+Metaphor, analogy, and figurative language are not the default style. They may be used only when ALL of the following are true:
+
+1. The metaphor is strictly utilitarian.
+2. It is required to explain a technical concept that would otherwise be less clear.
+3. It improves accuracy or comprehension for the intended audience.
+4. It is brief, literal in effect, and not decorative.
+
+If a concept can be explained clearly without metaphor, do not use metaphor.
+
+## Evidence-First Wording
+
+Match the strength of the wording to the strength of the evidence:
+
+- If something was verified, say it was verified and state how.
+- If something is likely but unconfirmed, say that it is likely or appears to be the case.
+- If something is unknown, say that it is unknown.
+- Do not imply certainty, completion, safety, or correctness without support.
+
+## Difficult Messages
+
+When reporting failures, defects, or policy violations:
+- State the issue directly.
+- Describe the impact without dramatizing it.
+- Identify the next corrective action when available.
+- Avoid blame-oriented or emotionally charged wording.
+
+When giving recommendations:
+- Prefer imperative, concrete language.
+- Explain the rationale briefly when it is not obvious.
+- Avoid motivational language, sales language, or celebratory phrasing.
+
+## Final Rule
+
+When tone is uncertain, choose the more restrained phrasing. The repository default is professionalism, clarity, and accuracy — not entertainment, flourish, or hype.