@danmoisan/drm-copilot-mcp 0.0.1

package/resources/customizations/.github/instructions/self-explanatory-code-commenting.instructions.md

@@ -0,0 +1,238 @@
+---
+description: "Guidelines for agent-authored code: mandatory robust docstrings + intent-level comments for control flow and multi-step blocks. Optimized for strongly-typed Python repos."
+applyTo: "**/*.py"
+---
+
+# Intent-First Docstrings & Comments (Python, strongly typed)
+
+## Core Principle
+
+Write code that is readable, but **assume the maintainer may not know the intent** (common with agent-authored code).
+Therefore:
+
+- **Docstrings are mandatory** for classes and functions/methods (including private helpers).
+- Inline comments are used to explain **intent, flow, and decision logic**—especially around iteration and branching.
+- Avoid low-value “narrate the obvious” comments.
+
+The goal is that a reader can understand the **purpose, usage, and flow** without reverse-engineering the implementation.
+
+---
+
+## 1) Mandatory class docstrings (robust)
+
+Every class must have a docstring that covers, at minimum:
+
+- **Purpose**: what the class represents or coordinates.
+- **Responsibilities**: what it does and does *not* do (scope boundaries).
+- **How it is intended to be used**: lifecycle, typical call pattern, 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, non-null IDs, caching semantics).
+- **Important side effects**: I/O, persistence, network calls, mutation, concurrency considerations.
+- **Attributes** (when non-obvious): what the stored fields mean and how they are populated.
+
+Preferred structure (Google-style, typed) for consistency:
+
+```python
+class Example:
+    """
+    One-sentence summary of the class’s role.
+
+    Purpose:
+        What problem this class solves and where it fits in the system.
+
+    Usage:
+        Typical usage pattern (brief pseudo-code is acceptable).
+
+    Flow:
+        High-level steps this class performs, in order.
+
+    Invariants / Constraints:
+        Key assumptions that callers must respect.
+
+    Side Effects:
+        External calls, mutation, persistence, logging, etc.
+
+    Attributes:
+        field_name (Type): Meaning and lifecycle (if not obvious from the name).
+    """
+````
+
+---
+
+## 2) Mandatory function/method docstrings (robust, C#-like completeness)
+
+Every function/method must have a docstring that includes:
+
+* **Purpose** and behavior (what it accomplishes).
+* **Parameters**: meaning, constraints, and how used (types included, even if hinted).
+* **Returns**: meaning and shape of return value (or explicitly say `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.
+
+Template:
+
+```python
+def method(self, x: XType, y: YType) -> ReturnType:
+    """
+    One-sentence summary of the method’s outcome.
+
+    Purpose:
+        What this method is responsible for and why it exists.
+
+    Args:
+        x (XType): Meaning, constraints, and how it influences behavior.
+        y (YType): Meaning, constraints, and how it influences behavior.
+
+    Returns:
+        ReturnType: What is returned and how to interpret it.
+
+    Raises:
+        SomeError: When/why this is raised (contract-level).
+
+    Side Effects:
+        Describe mutations, I/O, persistence, logging, caching, etc.
+    """
+```
+
+Notes:
+
+* Keep docstrings accurate and **contract-oriented**. If behavior changes, docstrings must be updated.
+* If the method is a thin wrapper around another call, say so explicitly (and why the wrapper exists).
+* For `@property` accessors, docstrings should describe **what is exposed and the semantics** (cached vs computed, cost, invariants).
+
+---
+
+## 3) Loops and list comprehensions must be explained
+
+Any `for` loop, `while` loop, or non-trivial list/dict/set comprehension must have an **intent comment** immediately above it.
+
+Good:
+
+```python
+# Aggregate per-user totals while preserving first-seen ordering for stable output.
+for row in rows:
+    ...
+```
+
+For comprehensions, if the intent cannot be explained cleanly in one short comment, prefer expanding to an explicit loop.
+
+Good:
+
+```python
+# Keep only canonicalized URLs that pass validation; used to drive dedupe and matching.
+valid_urls = [u for u in urls if (u := canonicalize(u)) and is_valid(u)]
+```
+
+Better (when complex):
+
+```python
+# Canonicalize + validate URLs before feeding them into the dedupe pipeline.
+valid_urls: list[str] = []
+for raw in urls:
+    canon = canonicalize(raw)
+    if canon and is_valid(canon):
+        valid_urls.append(canon)
+```
+
+---
+
+## 4) Branching must explain decision logic (if/elif/else, match/case)
+
+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** (why this branching exists).
+
+Good:
+
+```python
+# Branch by identifier quality:
+# - Prefer stable external IDs when present (prevents duplicate entities).
+# - Fall back to email match when IDs are missing.
+# - Finally, create a new entity if no safe match exists.
+if external_id:
+    ...
+elif email:
+    ...
+else:
+    ...
+```
+
+For `match/case`, include a short “routing table” explanation:
+
+```python
+# Dispatch by event type:
+# - "upsert" modifies or creates a record
+# - "delete" tombstones but preserves audit trail
+# - other events are ignored (forward compatibility)
+match event.type:
+    ...
+```
+
+---
+
+## 5) “Forest through the trees”: comment multi-step blocks that achieve a larger objective
+
+When a sequence of tactical lines collectively accomplishes a larger goal, precede the block with a **meta-what + why** comment.
+
+Good:
+
+```python
+# Enrich the dataset with original publish metadata:
+# inner-join on `source_id`, then remove duplicates to ensure one row per canonical entity.
+merged = left.merge(right, on="source_id", how="inner")
+merged = merged.drop_duplicates(subset=["canonical_id"])
+```
+
+If the block is substantial, strongly prefer extracting it into a helper method so the **docstring becomes the primary explanation**. If extraction is not done now, write the comment so that refactoring later is straightforward (describe inputs/outputs of the block).
+
+---
+
+## 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: ...`
+
+---
+
+## 7) “What vs why”: allow “meta-what” when it explains intent at the right level
+
+We still avoid line-by-line narration (e.g., “increment counter”), but we explicitly allow “meta-what” comments that describe what a *block* of code is doing, especially when the intent is not obvious from individual lines.
+
+Rule of thumb:
+
+* **Bad**: Restates a single obvious line.
+* **Good**: Explains the intent of a loop/branch/multi-step block and how it supports the method’s purpose.
+
+---
+
+## Anti-patterns (still avoid)
+
+* Outdated comments that contradict code.
+* Changelog/history comments in source.
+* Decorative dividers.
+* Commented-out dead code.
+
+---
+
+## 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/comprehensions have intent comments (or are expanded for clarity).
+* Branching has decision-logic comments.
+* Multi-step blocks have meta-what + rationale comments.
+* No numbered notes in comments/docstrings.
+* Comments remain accurate and add real explanatory value.

package/resources/customizations/.github/instructions/tonality.instructions.md

@@ -0,0 +1,133 @@
+---
+applyTo: "**"
+name: "tonality-policy"
+description: "Required communication tone for agent-authored responses, documentation, reviews, and operational guidance in this repository"
+---
+
+# Tonality Policy
+
+This policy defines the required tone for all agent-authored content in this repository.
+
+It applies to:
+
+- Chat responses to users.
+- Pull request summaries, review comments, and audit artifacts.
+- Plans, issue updates, remediation notes, and status reports.
+- Inline guidance written into documentation, runbooks, and instruction files.
+
+If another instruction is more restrictive, follow the more restrictive instruction.
+
+## 1. Required default tone
+
+All written output must use a professional tone.
+
+Professional tone in this repository 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.
+
+## 2. Humor and joking are 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.
+
+## 3. Hyperbole is prohibited
+
+Do not use hyperbolic, inflated, or sensational language.
+
+Avoid statements such as:
+
+- Claims that something is perfect, flawless, amazing, incredible, revolutionary, or world-class unless that language is directly quoted from an authoritative source and clearly marked as a quotation.
+- Overstated certainty that goes beyond the verified evidence.
+- Dramatic framing that overstates urgency, difficulty, simplicity, risk, or impact.
+
+Use measured alternatives instead:
+
+- Replace absolute praise with evidence-based descriptions.
+- Replace dramatic warnings with specific risks and consequences.
+- Replace sweeping claims with concrete observations, test results, or documented limitations.
+
+## 4. Metaphors are tightly restricted
+
+Metaphor, analogy, and figurative language are not the default style.
+
+They may be used only when all of the following are true:
+
+- The metaphor is strictly utilitarian.
+- It is required to explain a technical concept that would otherwise be less clear.
+- It improves accuracy or comprehension for the intended audience.
+- It is brief, literal in effect, and not decorative.
+
+If a concept can be explained clearly without metaphor, do not use metaphor.
+
+Unacceptable metaphor usage includes:
+
+- Decorative imagery.
+- Emotional or dramatic comparisons.
+- Marketing-style slogans.
+- Extended analogies that distract from the technical point.
+
+Acceptable metaphor usage is limited to short, functional comparisons such as explaining that one component acts "as a queue" or that a layer serves "as a boundary" when those comparisons materially improve understanding.
+
+## 5. 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.
+
+## 6. Style guidance for 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.
+
+## 7. Examples
+
+Preferred:
+
+- The build failed during nullable analysis because `BridgeStateStore` introduces a new nullability warning.
+- `I updated the instruction file and verified that the repository reports no new markdown errors in the changed file.`
+- `This comparison is useful because the repository cache behaves as a boundary between Outlook data collection and RPC response shaping.`
+
+Not preferred:
+
+- `The build totally blew up.`
+- `This fix is amazing and should solve everything.`
+- `The cache is the beating heart of the system.`
+- `Good news: the code is finally behaving.`
+
+## 8. Final rule
+
+When tone is uncertain, choose the more restrained phrasing.
+
+The repository default is professionalism, clarity, and accuracy—not entertainment, flourish, or hype.

package/resources/customizations/.github/instructions/typescript-code-change.instructions.md

@@ -0,0 +1,203 @@
+---
+description: "TypeScript-specific code change rules layered on top of the general code change policy"
+applyTo: "**/*.ts"
+name: typescript-code-change-policy
+---
+
+# TypeScript Code Change Policy
+
+This policy **extends** `general-code-change.instructions.md` and applies to all **TypeScript source, test, and script files** (`*.ts`) in this repo.
+
+These instructions assume TypeScript is built with **TypeScript 5.x (or newer)** targeting an **ES2022** JavaScript baseline.
+
+You must:
+
+- Apply **all** rules in the general code change policy.
+- Apply **all** TypeScript-specific rules in this file.
+- Apply the unit test policies (`general-unit-test.instructions.md` and `typescript-unit-test.instructions.md`) for any work involving TypeScript tests.
+
+If you encounter any conflicting instructions between these documents, **halt and notify the user.**
+
+---
+
+## 1. Tooling & Baseline for TypeScript
+
+These are the required tools for TypeScript code in this repo:
+
+1. **Formatting — Prettier**
+
+   - All TypeScript must be formatted with the repository’s Prettier configuration.
+   - Do not hand-format; if a diff disagrees with Prettier, Prettier wins.
+   - Approved command: `npm run format`
+
+2. **Linting — ESLint**
+
+   - TypeScript must pass ESLint using the repository’s configuration.
+   - Prefer fixing root causes over suppressions.
+   - Approved command: `npm run lint`
+
+3. **Type checking — TypeScript compiler (TSC)**
+
+   - TypeScript must pass the repository’s type-check.
+   - Avoid `any` (implicit or explicit). Prefer `unknown` plus narrowing.
+   - Approved command: `npm run typecheck`
+
+4. **Testing — Jest**
+
+   - TypeScript unit tests must pass Jest.
+   - Approved command: `npm run test:unit`
+
+> **Important:** The general code change policy requires the full toolchain loop: formatting → linting → type checking → testing.
+
+---
+
+## 2. TypeScript Design & Typing Principles
+
+These refine the general design principles for TypeScript code.
+
+1. **Strong typing by default**
+
+   - Public functions, methods, and exported APIs must have clear, intentional types.
+   - Avoid type assertions (`as X`) unless you can justify why the value is safe; prefer runtime guards.
+
+2. **Prefer explicit domain types**
+
+   - Model domain concepts with interfaces/types that encode invariants.
+   - Prefer discriminated unions for state machines and event shapes.
+
+3. **Avoid cleverness**
+
+   - Keep code readable in one pass.
+   - Favor small helpers and early returns over deeply nested branching.
+
+4. **Separation of concerns**
+
+   - Keep pure logic separate from:
+     - VS Code extension APIs
+     - filesystem/network I/O
+     - UI/presentation wiring
+   - Write core logic so it can be unit tested without VS Code host processes.
+
+---
+
+## 3. Imports, Modules, and Dependencies
+
+1. **Modules**
+
+   - Use ES modules. Do not introduce CommonJS patterns (`require`, `module.exports`).
+   - Prefer explicit imports; avoid barrel exports that obscure dependencies unless the repo already uses them for that area.
+
+2. **Dependencies**
+
+   - Do not add new runtime dependencies unless explicitly approved.
+   - If a dependency is unavoidable:
+     - Prefer widely used, well-maintained packages.
+     - Keep dependency surface area small (wrap behind a typed adapter when practical).
+
+---
+
+## 4. Error Handling and Logging
+
+- Fail fast with clear errors when invariants are violated.
+- Avoid catch-all `catch (e)` without rethrowing or adding context.
+- Use the repo’s established logging/telemetry patterns (where present) instead of ad-hoc `console.log` for permanent behavior.
+
+---
+
+## 5. Suppressions and Escape Hatches
+
+Suppressions are sometimes necessary, but they must be rare, tightly scoped, and well-justified.
+
+**Authorization requirement:**
+
+- Suppressions are allowed without explicit approval only when they match a **pre-authorized pattern** `typescript-suppressions.instructions.md`.
+- Any broader suppression (for example, disabling multiple rules, disabling a whole file, or using `@ts-ignore`) requires **explicit user approval**.
+
+**If you encounter an error that seems to require a suppression not matching a pre-authorized pattern:**
+
+1. First, attempt to resolve it without a suppression (refactor, restructure, adjust types).
+2. If that fails, try at least five more distinct approaches.
+3. Continue iterating until you solve the problem or demonstrate why each approach fails.
+4. Only after multiple documented failed attempts may you request user approval, providing:
+    - The specific rule/error and diagnostic code
+    - Each approach you tried and why it failed
+    - Why a suppression is the only remaining option
+
+All rules for ESLint and TypeScript suppressions are defined in:
+
+- `typescript-suppressions.instructions.md`
+
+---
+
+## 6. Public APIs and Compatibility
+
+- Avoid breaking changes to exported APIs unless explicitly required.
+- If a breaking change is necessary, update all callers in-repo and add/adjust unit tests that lock in the new contract.
+
+---
+
+## 7. Project Organization, Naming, and Documentation
+
+1. **Project organization**
+
+   - Follow the repository’s established folder and responsibility layout when adding new code.
+   - Keep VS Code extension API wiring and other I/O boundaries thin; push complex logic into pure, testable helpers/services.
+
+2. **File naming**
+
+   - Prefer **kebab-case** filenames for new files (for example, `user-session.ts`, `task-runner.ts`) unless the surrounding area of the repo already uses a different convention.
+
+3. **TypeScript naming conventions**
+
+   - Use **PascalCase** for classes, interfaces, enums, and type aliases; use **camelCase** for functions, methods, variables, and object properties.
+   - Do not introduce interface prefixes like `I` (for example, prefer `UserSession` over `IUserSession`).
+
+4. **Documentation expectations**
+
+   - Add JSDoc to exported/public APIs when it improves clarity for callers.
+   - When JSDoc is used and intent is non-obvious, prefer including a short rationale (and add `@example` / `@remarks` where it materially improves correct usage).
+
+---
+
+## 8. Security, Configuration, and External Integrations
+
+1. **Input validation and safety**
+
+   - Treat all external input as untrusted (user input, files, network responses, VS Code configuration).
+   - Prefer explicit runtime validation (type guards / schema validation) at trust boundaries.
+   - Avoid dynamic code execution and avoid rendering untrusted content as HTML without proper escaping/sanitization.
+
+2. **Secrets and configuration**
+
+   - Never hardcode secrets. Use the repo’s secure storage / configuration patterns.
+   - Guard against missing configuration (`undefined`) and surface clear errors when required configuration is absent.
+   - If you introduce new configuration keys, document them and add/update unit tests around validation and defaults.
+
+3. **External integrations (network / I/O)**
+
+   - Instantiate expensive clients outside hot paths and inject them for testability.
+   - For network or I/O operations, use clear error mapping and add context when rethrowing.
+   - Where applicable, apply retries/backoff and cancellation/timeout handling consistent with the repo’s existing patterns.
+
+---
+
+## 9. UI/UX and Lifecycle Hygiene (VS Code Extension Context)
+
+1. **UI layering**
+
+   - Keep UI layers thin; push business logic into services or pure functions.
+   - Prefer events/messaging to decouple UI from domain logic.
+
+2. **Lifecycle and disposal**
+
+   - Dispose resources deterministically and match existing initialization/disposal sequencing.
+   - When introducing long-lived services, consider explicit lifecycle hooks (for example, `initialize()` and `dispose()`) and unit tests that lock in lifecycle behavior.
+
+---
+
+## 10. Performance and Reliability
+
+- Avoid obvious hot-path allocations and repeated heavy work.
+- Prefer lazy-loading heavy dependencies when it materially reduces startup/activation cost.
+- Debounce or batch high-frequency events (for example, configuration changes) to avoid thrash.
+- Track resource lifetimes to prevent leaks (timers, listeners, file watchers, disposables).