Orchestrator/bahn/teamlandkarte-mcp/openspec/changes/add-capacity-to-task-matching-tools/specs/capacity-to-task-matching/spec.md

Spec Delta: Capacity→Task Matc### Requirement: Match tasks### Requirement: Role inference tool is embe### Requirement: Task validation uses embedding-based role and competence inference

Task validation SHALL use embedding similarity against role and competence vocabularies and SHALL NOT call the Azure chat API. Output SHALL include Markdown tables for inferred roles and competences with similarity scores.

Scenario: Validate task requirements without chat calls

• WHEN the client calls validate_task_requirements(task_id=...)
• THEN the server infers the task's primary role via the role vocabulary (embeddings)
• AND the output includes a Markdown table with columns Role | Similarity (single row)
• AND the server infers competences via the competence vocabulary (embeddings) honoring configured max/threshold
• AND the output includes a Markdown table with columns Competence | Similarity in descending order by similarity
• AND the output remains table-first and includes inferred role/competences with similarity scoresy and returns a single closest role

Role inference SHALL be based on embedding similarity between a task's combined text and the Data Lake role vocabulary and SHALL return only the single closest role as a Markdown table.

Scenario: Infer primary role from task_id or task_text

• WHEN the client calls infer_primary_role(task_id=...)

• THEN the system builds a combined text consisting of the task title (if present) and the task description

• AND the combined text is embedded and compared against the available role list

• AND the output is a Markdown table with columns Role | Similarity containing the single best matching role

• WHEN the client calls infer_primary_role(task_text=...)

• THEN the system embeds the provided text and compares it against the available role list

• AND the output is a Markdown table with columns Role | Similarity containing the single best matching role

• AND exactly one of task_id or task_text MUST be provided

• AND the legacy infer_roles(...) tool MUST be removed completelyThe system SHALL expose a tool find_matching_tasks(capacity_id) that matches a capacity against all published tasks using role + competence similarity.

Scenario: Match tasks for a capacity using role + competence similarity

• GIVEN a capacity has a role name and a competence list
• AND at least one open/published task exists in the Data Lake
• WHEN the client calls find_matching_tasks(capacity_id=<id>)
• THEN the server infers each task's primary role before computing similarity
• AND the server infers each task's competences using embedding similarity with configured max/threshold
• AND the server returns a Markdown table with columns: task_id, Title, Required Competences, Availability, Score, Category
• AND results are sorted by similarity score in descending order
• AND the output structure matches find_matching_capacities (summary counts table + results table)
• AND the server returns categorized results (Top/Good/Partial/Low) using the same conventions as find_matching_capacities+ Embedding-based Inference

ADDED Requirements

Requirement: List free capacities

The system SHALL expose a tool list_free_capacities(limit=20) to list the most recent active capacities in a table-first Markdown format.

Scenario: List free capacities ordered by creation_date

• WHEN the client calls list_free_capacities(limit=3)
• THEN the server returns a Markdown table with columns:
  • capacity_id
  • Owner/Team (sourced from the capacity’s owner_name column)
  • Role
  • Competences
  • Availability
• AND the entries are ordered by creation_date descending
• AND Competences is rendered as a comma-separated list (or (none))
• AND Availability is rendered as begin_date .. end_date (using (open) when the end date is missing)
• AND when there are zero results, the output still contains a valid Markdown table (a dummy row is acceptable)

Requirement: Get capacity details

The system SHALL expose a tool get_capacity_details(capacity_id) that returns a single capacity entry in the same table-first format as list_free_capacities.

Scenario: Get capacity details for a known capacity_id

• WHEN the client calls get_capacity_details(capacity_id=<id>)
• THEN the server returns a table-first Markdown output containing the same fields as list_free_capacities
• AND the output MAY include a “Next steps” section pointing to find_matching_tasks(capacity_id=...)

Requirement: Match tasks for a capacity

The system SHALL expose a tool find_matching_tasks(capacity_id, ...) that matches a capacity against all published tasks using role + competence similarity.

Scenario: Match tasks for a capacity using role + competence similarity

• GIVEN a capacity has a role name and a competence list
• AND at least one open/published task exists in the Data Lake
• WHEN the client calls find_matching_tasks(capacity_id=<id>)
• THEN the server infers each task’s primary role before computing similarity
• AND the server returns categorized results (Top/Good/Partial/Low) using the same conventions as find_matching_capacities

MODIFIED Requirements

Requirement: Role inference tool is embeddings-only and returns a single closest role

Role inference SHALL be based on embedding similarity between a task’s combined text and the Data Lake role vocabulary and SHALL return only the single closest role.

Scenario: Infer primary role from task_id or task_text

• WHEN the client calls infer_primary_role(task_id=...)

• THEN the system builds a combined text consisting of the task title (if present) and the task description

• AND the combined text is embedded and compared against the available role list

• AND the output is the single best matching role

• WHEN the client calls infer_primary_role(task_text=...)

• THEN the system embeds the provided text and compares it against the available role list

• AND the output is the single best matching role

• AND exactly one of task_id or task_text MUST be provided

• AND the legacy infer_roles(...) tool MUST be removed completely

Requirement: Competence inference is configurable by max count and threshold

Competence inference for validation SHALL be derived via embedding similarity against the competence vocabulary and MUST support limiting by both maximum count and a minimum similarity threshold. Output SHALL be a Markdown table.

Scenario: Select top X competences above threshold

• GIVEN max_competences = X and min_similarity = T are configured
• WHEN competences are inferred for a task
• THEN only competences with similarity >= T are considered
• AND from those, the top X competences by similarity are returned
• AND the output is a Markdown table with columns Competence | Similarity in descending order by similarity

Requirement: Task validation uses embedding-based role and competence inference

Task validation SHALL use embedding similarity against role and competence vocabularies and SHALL NOT call the Azure chat API.

Scenario: Validate task requirements without chat calls

• WHEN the client calls validate_task_requirements(task_id=...)
• THEN the server infers the task’s primary role via the role vocabulary (embeddings)
• AND the server infers competences via the competence vocabulary (embeddings) honoring configured max/threshold
• AND the output remains table-first and includes inferred role/competences with similarity scores

Requirement: Startup-only embedding preload with runtime fallback

The server SHOULD preload embeddings on startup to reduce runtime Azure calls, but MUST still embed on-demand for any cache misses encountered during tool execution.

Scenario: Preload only cache-missing embeddings and fall back at runtime

• WHEN the server starts
• THEN it fetches role vocabulary + competence vocabulary from the Data Lake
• AND it embeds only cache-missing role/competence vocabulary entries
• AND it fetches all open tasks (no limit)
• AND it builds combined task text (title + "\n\n" + description) and embeds only cache-missing task text embeddings keyed by task_id
• AND during runtime, if an embedding is still missing, the server retrieves it on-demand (strict semantics)

REMOVED Requirements

Requirement: Chat-based extraction for roles and competences

The system SHALL NOT require Azure chat completions for role inference or task validation once this change is implemented.

Scenario: Azure chat API is not required for matching and validation

• WHEN a matching or validation tool is executed
• THEN no Azure chat completion request is made
• AND only Azure embeddings are used where LLM intelligence is required