Merge main into feature/ADR-191-oop-ml-pipeline

.claude/skills/developer-standards/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: developer-standards
+description: >
+  Use when planning new code, writing code, or reviewing code.
+  Loads project code guidelines and quality gates from CONTRIBUTING.md and CLAUDE.md.
+---
+
+Use this skill when:
+- You are planning new code, writing code, or reviewing code
+
+## Steps
+
+### 1 — Read code guidelines
+
+Read `CONTRIBUTING.md` for code guidelines: naming conventions, file structure, logging standards, and test conventions.
+
+### 2 — Read quality gates
+
+Read `CLAUDE.md` for quality gates and operational conventions specific to this repo.
+
+### 3 — Read `.editorconfig`
+
+Read `.editorconfig` and treat it as the authoritative code style specification. Follow every rule
+exactly as written — including indentation style, tab width, line endings, charset, trailing
+whitespace, final newlines, and any file-type-specific sections. Do not override any setting.
+
+Apply all three sets of standards to every file you write or review.

.claude/skills/ensure-working-branch/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ensure-working-branch
+description: >
+  Ensures the repository is on the correct working branch for a task, creating it from the
+  correct base branch if it does not yet exist.
+  Use this skill before reading or writing any repository files to confirm the branch is ready.
+argument-hint: <work-item-id>
+---
+
+Use this skill when:
+- You are about to write code or modify files and need to be on the correct working branch
+
+Do NOT use this skill when:
+- You already know the working branch is checked out and up to date
+
+## Arguments
+
+- First argument — a **work-item-id** (e.g. `ADR-123`, `Issue-444`). Required.
+
+## Determining work-item-type
+
+Derive `work-item-type` from the `work-item-id` pattern (see `identify-project-work-items`):
+
+| work-item-id pattern | work-item-type |
+|---|---|
+| `ADR-\d+` (Jira key) | `jira` |
+| `Issue-\d+` (GitHub issue) | `github` |
+
+## Steps
+
+### 1 — Compute the working branch name
+
+The working branch is always `dev/claude/<work-item-id>`. Derive it directly from the ID.
+
+### 2 — Determine the base branch
+
+#### 2a — Search the repo for a spec file
+
+Search the repository for `_spec_*.md` files that contain the work-item-id:
+
+```bash
+grep -rl "<work-item-id>" . --include="_spec_*.md"
+```
+
+If a spec file is found, read it and look for a Jira key (pattern `[A-Z]+-\d+`) that
+appears in a heading or field labelled `Epic:`, `Parent:`, or `Epic ID:`. That key is the
+Epic ID.
+
+#### 2b — Query Jira if no Epic ID found in spec
+
+If no Epic ID was found in step 2a and `work-item-type` is `jira`:
+
+Call `mcp__jira__getJiraIssue` with the `work-item-id`. Look for a `parent` or `epic`
+field on the returned issue and extract its key (e.g. `ADR-200`). That key is the Epic
+ID. If the issue has no parent or the parent is not a Jira key, continue with no Epic ID.
+
+#### 2c — Find the epic feature branch
+
+If an Epic ID was found in step 2a or 2b, search remote branches for it:
+
+```bash
+git fetch origin
+git branch -r | grep "feature/<epic-id>"
+```
+
+Strip the `origin/` prefix from the matching branch name (e.g. `feature/ADR-200-infrastructure`). That is the base branch. If more than one branch matches, prefer the one most recently pushed.
+
+#### 2d — Fallback: nearest ancestor feature branch
+
+If no Epic ID was found and step 2c was not reached, check for the nearest ancestor
+`feature/*` remote branch:
+
+```bash
+git branch -r --merged HEAD | grep "feature/"
+```
+
+Use the closest ancestor `feature/*` branch as the base branch.
+
+#### 2e — Fallback or error
+
+If no `feature/*` branch has been found:
+- `work-item-type` is `jira`: stop and report an error — a feature branch is required for
+  Jira tasks.
+- Otherwise: use `main` as the base branch.
+
+### 3 — Prepare the working branch
+
+Fetch the latest state from the remote:
+
+```bash
+git fetch origin
+```
+
+If the working branch already exists locally or on the remote, check it out and pull:
+
+```bash
+git checkout dev/claude/<work-item-id>
+git pull origin dev/claude/<work-item-id>
+```
+
+If the working branch does not yet exist, create it from the base branch:
+
+```bash
+git checkout -b dev/claude/<work-item-id> origin/<base-branch>
+```
+
+---
+
+If all steps complete successfully, respond with one word: `successful`
+
+If any step fails, stop and report the failure in detail.

.claude/skills/find-repo-documentation/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: find-repo-documentation
+description: >
+  Use when you need to learn the architecture from documentation in this repo.
+  Discovers available architecture docs and reads the ones relevant to the current task.
+argument-hint: <task context or area to research>
+---
+
+Use this skill when:
+- You need to learn the architecture from documentation in this repo
+
+## File format and locations
+
+Architecture documents are named `_doc_*.md` and live at the repo root and in subdirectories. Each one starts with a `Summary:` line that describes what it covers.
+
+## Steps
+
+### 1 — Discover available docs
+
+Find all architecture documents and their summaries in one pass:
+
+```bash
+grep -rn "^Summary:" . --include="_doc_*.md"
+```
+
+Each output line contains a file path and its `Summary:` value. Use this output directly to build your list of available docs and their topics — no additional reads are required for this step.
+
+### 2 — Select relevant docs
+
+From the task context or area you have been given, identify which subsystems and topics the task will touch. Select the docs whose summaries match those areas.
+
+### 3 — Read and summarize
+
+Read each selected doc in full. For each one, note:
+- File path
+- What it says about the areas this task will touch
+- Any constraints, patterns, or conventions the implementer must follow
+
+Internalize these findings as working context for the current task. For each doc consulted, note its file path and the constraints, patterns, or conventions that apply to the work ahead.

.claude/skills/identify-project-work-items/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: identify-project-work-items
+description: >
+  Defines the work item patterns for this project.
+  Use this skill when you need to know the active work-item-id or work-item-type, which can be used to create branches, look up specs, or access work item information online.
+---
+
+# Work item tracking for AdaptiveRemote and related projects
+
+Use this skill when:
+- Another skill requires `work-item-id` in `ADR-###` or `Issue-###` format
+
+Do NOT use this skill when:
+- You already know the `work-item-id` and `work-item-type` that is under active development
+
+This project uses Jira for work item planning and GitHub issues for tracking bugs and public discussions. The project prefix for all Jira work items is `ADR-`.
+
+
+## Patterns for recognizing work items
+
+Look for the following patterns in user input or previous discussion to identify the work item that is under active development.
+
+| Example patterns | Canonical `work-item-id` | `work-item-type` | `numeric-id` |
+|---|---|---|---|
+| ADR-123, Task 123, Epic 123, Jira 123 | `ADR-123` | `jira` | `123` |
+| `#42`, `Issue 42`, `GitHub 42` | `Issue-42` | `github` | `42` |
+
+Note: The canonical `work-item-id` is used by other skills to create git branch names and file paths. The `Issue-42` pattern is used for GitHub because the GitHub standard `#42` would not be valid in those contexts.
+
+## Output
+
+Return these fields as a short structured block:
+
+```
+work-item-id: ADR-123
+work-item-type: jira
+numeric-id: 123
+```
+
+If the input does not contain any matches for any known pattern, stop and ask: `What work item do you want to work on?`

.claude/skills/spec-task-work-items/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: spec-task-work-items
+description: >
+  Use when you are writing a new spec or a new part of an existing spec.
+  Updates the Jira epic and task descriptions with summaries after the spec is finalized.
+argument-hint: <epic-key> <spec-path>
+---
+
+Use this skill when:
+- You are writing a new spec or a new part of an existing spec
+- The spec is finalized and Jira work items need to reflect the decisions
+
+## Steps
+
+### 1 — Update the Jira epic description
+
+If `work-with-Jira-tasks` is listed as an available skill, invoke it to update the Jira epic's description. Otherwise, call `mcp__jira__editJiraIssue` directly. Update the Jira epic's description with a concise summary of the finalized design decisions from the spec:
+
+- Replace the original description (which typically contains early design thoughts) with a brief overview and a bulleted list of the key decisions and their outcomes
+- Include a link to the spec file in the repo
+
+### 2 — Update task descriptions
+
+For each Jira task created from the spec, update its description to reflect the finalized content:
+
+- One-paragraph overview of what the task implements
+- Bulleted list of key decisions and their outcomes relevant to this task
+- Reference to the spec section: `See spec: <relative path>`
+
+Replace initial notes or placeholders entirely — do not append.

.claude/skills/write-e2e-test/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: write-e2e-test
+description: >
+  Use when you are writing E2E tests.
+  Establishes where to put feature files, how to write Gherkin scenarios, and how step definitions should be structured.
+---
+
+Use this skill when:
+- You are writing E2E tests
+
+## Location
+
+Write new feature files in the headless E2E host:
+
+```
+test/AdaptiveRemote.EndToEndTests.Host.Headless/Features/
+```
+
+Follow all conventions in `test/_doc_EndToEndTests.md`.
+
+## Scenario writing rules
+
+**Use existing steps whenever possible.** Before writing a new step, search for existing step definitions and their patterns:
+
+```bash
+grep -rEn "\[(Given|When|Then)\(" test/ --include="*.cs"
+```
+
+**Write generalized step phrasing.** Each `Given`, `When`, and `Then` step must describe something a human could do or observe manually — not an internal implementation detail.
+
+- Good: `When the user opens the settings panel`
+- Bad: `When SettingsViewModel.OpenCommand is executed`
+
+**One scenario per behaviour.** Keep scenarios focused. A scenario that covers multiple independent behaviours is harder to diagnose when it fails.
+
+**Represent the correct behaviour.** For bug investigations, first write the scenario to observe the bad behaviour (it should pass), then modify it to assert the correct behaviour (it should now fail). This failing test is the investigation anchor.
+
+## Step definition rules
+
+Step definitions must delegate logic to test service methods — they must not contain application logic. The step definition's only job is to translate the human-readable step into a call to the appropriate service method, verifying inputs have valid values when necessary. 

.claude/skills/write-repo-documentation/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: write-repo-documentation
+description: >
+  Use when you are drafting or updating architecture documentation in this repo.
+  Establishes where to put new documents, what they must contain, and the expected structure.
+---
+
+Use this skill when:
+- You are drafting or updating architecture documentation in this repo
+
+## File naming and location
+
+Architecture documents are named `_doc_<FeatureName>.md` in PascalCase and live in the directory of the code they describe — not at the repo root.
+
+Each `_spec_*.md` file includes a status note indicating it will become a `_doc_` file once implementation is complete:
+
+```
+> **Will become:** `_doc_<FeatureName>.md` once implementation is complete
+```
+
+When implementation is done, rename the spec file to `_doc_<FeatureName>.md` and remove the `> **Will become:** ...` status line.
+
+## Required content
+
+Every `_doc_*.md` must start with a `Summary:` line — a single line description of what the document covers. This is used by tooling and other skills to discover relevant docs:
+
+```
+Summary: <one-line description of the subsystem or feature this doc covers>
+```
+
+After the summary, include:
+
+- **Overview:** what this subsystem does and why it exists
+- **Responsibilities & Boundaries:** what it owns, what it delegates, what it integrates with
+- **Key Design Decisions:** decisions already made and their trade-offs — use the same ADR format as the spec
+- **Key Classes / Interfaces:** the public surface — classes, interfaces, and their responsibilities
+- **Data Flow:** how data moves through the subsystem
+
+Omit sections that don't apply. Do not add sections not listed here. Do not go into implementation details, just link to the source files for implementation details.
+
+## Updating an existing doc
+
+When an implementation changes the design described in an existing `_doc_` file, update the doc as part of the same PR. A PR that changes a subsystem without updating its doc is incomplete.
+
+If a new interface, responsibility, or dependency is added, reflect it in the doc. If a decision is reversed, update the Key Design Decisions section and note why.