Migrate all repos into monorepo context folders
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)
Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
This commit is contained in:
+99
@@ -0,0 +1,99 @@
|
||||
# Capacity Matching Specification
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Workflow overview (Round 6)
|
||||
|
||||
The system SHALL support two primary workflows:
|
||||
|
||||
1. **Database task workflow (Phase 0)**: Users browse published tasks from the database, inspect details, optionally validate, and run a capacity search for an existing task.
|
||||
2. **Ad-hoc workflow (Phases 1-3)**: Users gather requirements (free-text extraction, structured input, or guided capture), optionally update requirements, explicitly confirm, execute search, and refine results.
|
||||
|
||||
The system SHALL expose the MCP tools required to support the workflows below. The implementation MAY add additional tools over time.
|
||||
|
||||
#### Scenario: Tool surface includes both DB-task and ad-hoc workflows
|
||||
|
||||
**Phase 0 – Task Management (Database tasks)**
|
||||
- `list_open_tasks(limit=20)`
|
||||
- `get_task_details(task_id)`
|
||||
- `validate_task_requirements(task_id)`
|
||||
- `find_capacities_for_task(task_id)`
|
||||
- `infer_roles(task_id? | task_description?, limit=5)`
|
||||
|
||||
**Phase 1 – Requirement Gathering (Ad-hoc)**
|
||||
- `extract_requirements(task_description)` → writes pending requirements
|
||||
- `collect_structured_requirement_data(role_name?, competences?, date_start?, date_end?, description?)` → writes pending requirements
|
||||
- `update_requirements(change_description)` → writes pending requirements
|
||||
- Guided capture tools:
|
||||
- `start_guided_capture()`
|
||||
- `guided_set_description(description)`
|
||||
- `guided_set_role(role_name)`
|
||||
- `guided_set_time_range(date_start?, date_end?)` (open-ended allowed)
|
||||
- `guided_set_competences(competences)` → writes pending requirements
|
||||
- Review/ask tools:
|
||||
- `show_pending_requirements()` → returns a review table and marks that user confirmation was requested
|
||||
- `request_requirements_confirmation()` → marks that the assistant asked the user to confirm (no table)
|
||||
- `confirm_requirements(confirm: bool = True)`
|
||||
|
||||
**Phase 2 – Search Execution (Ad-hoc)**
|
||||
- `find_matching_capacities(role_name, competences, date_start?, date_end?)`
|
||||
|
||||
**Phase 3 – Result Refinement**
|
||||
- `filter_search_results(search_id, role_filter?, competence_filter?, availability_date_start?, availability_date_end?, min_similarity=0.7)` → returns `filter_id`
|
||||
- `get_results_by_category(search_id, filter_id?, category="Top", page=1, page_size=20)`
|
||||
|
||||
### Requirement: Confirmation gating
|
||||
|
||||
The system SHALL ensure that matching execution is confirmation-gated by default and behaves deterministically based on configuration.
|
||||
|
||||
#### Scenario: Matching is refused until requirements are confirmed (default)
|
||||
|
||||
- Confirmation gating:
|
||||
- The server's confirmation state is stored in in-memory session state and is **not** safe as a multi-client / multi-tenant source of truth.
|
||||
Therefore, treat confirmation gating primarily as a **client-side UX rule**: clients should only trigger matching after an explicit user Yes/No.
|
||||
- If `matching.require_confirmation = true` (default), matching tools MUST refuse to run unless requirements have been explicitly confirmed.
|
||||
- If `matching.require_confirmation = false`, clients MUST NOT ask for confirmation and MUST NOT call confirmation tools; matching MUST proceed once requirements are complete.
|
||||
- The confirmation flow MUST be two-step:
|
||||
1) `show_pending_requirements()` (preferred) OR `request_requirements_confirmation()`
|
||||
2) user explicitly confirms in chat
|
||||
3) `confirm_requirements(confirm=true)`
|
||||
- Servers MAY refuse `confirm_requirements(confirm=true)` if step (1) did not occur.
|
||||
|
||||
### Requirement: Tool outputs and result headers
|
||||
|
||||
The system SHALL emit table-first tool output formats and deterministic, machine-readable headers for search-session tools.
|
||||
|
||||
#### Scenario: Tool results are table-first and include deterministic header metadata
|
||||
|
||||
- Tool outputs:
|
||||
- `get_task_details` MUST be table-first (summary table + description below)
|
||||
- `validate_task_requirements` MUST be table-first (single comparison table + short written summary)
|
||||
- `infer_roles` MUST return a ranked table: `Rank | Role | Rationale`
|
||||
|
||||
- Search session output headers (robust client parsing):
|
||||
- The tools `find_matching_capacities`, `filter_search_results`, and `get_results_by_category` MUST emit deterministic, machine-readable header lines.
|
||||
- On success, the first line MUST be exactly:
|
||||
- `Using SEARCH_ID=<uuid>`
|
||||
- The output MUST also contain:
|
||||
- `SEARCH_ID=<uuid>`
|
||||
- `FILTER_ID=<uuid>` (only if a filter was created/used)
|
||||
- `META=<json>` (MUST include at least `{ "search_id": "...", "status": "ok"|... }`)
|
||||
|
||||
### Requirement: Search session validation and table guarantees
|
||||
|
||||
The system SHALL validate search session identifiers deterministically and MUST always return well-formed Markdown tables for search result tools.
|
||||
|
||||
#### Scenario: Invalid or expired search_id inputs produce deterministic errors and tables are always present
|
||||
|
||||
- Search session validation:
|
||||
- `search_id` inputs MUST be validated as UUIDs.
|
||||
- If the `search_id` is not a UUID, the tool MUST return `META.status=invalid_search_id_format` and guidance to copy the id from tool output.
|
||||
- If the `search_id` is unknown/expired, the tool MUST return `META.status=unknown_or_expired` and guidance to re-run the matching tool.
|
||||
|
||||
- Table-first guarantees for search results:
|
||||
- `find_matching_capacities` MUST include the `## Summary` table.
|
||||
- `find_matching_capacities` MUST include a results table for the **first non-empty category** in this order: Top → Good → Partial → Low.
|
||||
- If all categories are empty, it MUST still emit a valid Markdown table (a single dummy row is acceptable).
|
||||
- `filter_search_results` and `get_results_by_category` MUST NOT repeat the summary counts table.
|
||||
- `filter_search_results` MUST output a flat results table (not split by category) and MUST include a `Category` column **separate** from the numeric `Score`.
|
||||
- `filter_search_results` MUST always return the results as a valid Markdown table (even for exactly one match, and also when there are zero matches).
|
||||
Reference in New Issue
Block a user