ankn
a5f8fb49ab
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.
129 lines
6.0 KiB
Markdown
129 lines
6.0 KiB
Markdown
# Tasks: Improve Task Details, Role Inference, Guided Requirements Capture, and Search Reliability
|
|
|
|
> Change: `improve-task-details-role-inference-and-guided-flow`
|
|
>
|
|
> Notes:
|
|
> - All code/doc/spec content stays in English.
|
|
> - Tool count is **not** limited.
|
|
> - Confirmation is **hard-gated** by default; can be auto-skipped via config.
|
|
|
|
## Status
|
|
|
|
- ✅ **Implemented** (core behavior + UX contracts shipped).
|
|
- 📝 Some follow-up items remain for additional hardening/coverage (diagnostics/logging and a few missing tests), but they do not block the change being considered implemented.
|
|
|
|
## 1. Proposal Alignment & Baseline
|
|
|
|
- [x] 1.1 Re-scan current tools in `src/teamlandkarte_mcp/mcp_server.py` and confirm required changes vs. current behavior.
|
|
- [ ] 1.2 Confirm existing `SearchCache` semantics (`ttl_minutes`, `max_size`) and how eviction is handled.
|
|
- [x] 1.3 Add/update a short architectural note: numeric scores remain visible, categories are primary.
|
|
|
|
## 2. Configuration: hard confirmation gate (+ optional auto-skip)
|
|
|
|
- [x] 2.1 Extend matching config model in `src/teamlandkarte_mcp/config.py`:
|
|
- add `require_confirmation: bool = True` under `[matching]`.
|
|
- [x] 2.2 Update TOML loading/validation to accept `[matching].require_confirmation`.
|
|
- [x] 2.3 Update `database.toml.example` to document `require_confirmation` (default `true`).
|
|
- [ ] 2.4 Add tests for config parsing (default true, explicit false).
|
|
|
|
## 3. Session State: pending + confirmed requirements
|
|
|
|
- [x] 3.1 Extend `SessionState` in `src/teamlandkarte_mcp/mcp_server.py`:
|
|
- pending requirements object
|
|
- confirmed requirements object (or a confirmed flag/version)
|
|
- guided capture state (see section 6)
|
|
- [x] 3.2 Implement internal helper(s):
|
|
- `_set_pending_requirements(req: Requirements)`
|
|
- `_require_confirmed_requirements_or_throw()` (implemented as `_require_confirmed_or_auto`)
|
|
- [x] 3.3 Implement tool: `confirm_requirements(confirm: bool = True)`.
|
|
- [x] 3.4 Update `extract_requirements`, `collect_structured_requirement_data`, `update_requirements`:
|
|
- always write **pending** requirements
|
|
- never implicitly run matching
|
|
- include next-step guidance to call `confirm_requirements()`
|
|
- [x] 3.5 Update `find_matching_capacities` (and DB-backed matching tools) to **hard-enforce** confirmation when `matching.require_confirmation = true`.
|
|
- [x] 3.6 Auto-skip behavior:
|
|
- when `matching.require_confirmation = false`, treat pending requirements as confirmed (no refusal).
|
|
- [x] 3.7 Add unit tests for confirmation gate behavior.
|
|
|
|
## 4. Tool: `infer_roles` (ranked roles, no score column)
|
|
|
|
- [x] 4.1 Add tool `infer_roles(task_id: Optional[str] = None, task_description: Optional[str] = None, limit: int = 5)`.
|
|
- [x] 4.2 Enforce input rules:
|
|
- exactly one of `task_id` or `task_description` must be provided.
|
|
- [x] 4.3 If `task_id` provided:
|
|
- fetch task from DB, use its description.
|
|
- [x] 4.4 Use `TaskAnalyzer.extract_ranked_roles(description, limit=...)`.
|
|
- [x] 4.5 Output a markdown table with columns:
|
|
- `Rank | Role | Rationale`
|
|
- [ ] 4.6 Add tests for both modes (DB id mocked + free-text).
|
|
|
|
## 5. Tool output refactors
|
|
|
|
### 5.1 `get_task_details`
|
|
|
|
- [x] 5.1.1 Replace current multi-section output with:
|
|
- a single markdown table: `Task ID | Title | Created (date only) | Start | End | Competences | Inferred Role`
|
|
- below: task description
|
|
- [x] 5.1.2 Created date formatting: date-only (YYYY-MM-DD).
|
|
- [x] 5.1.3 Competences formatting: comma-separated, no numbering.
|
|
- [x] 5.1.4 Inferred role:
|
|
- derive from role inference (reuse same analyzer call used by `infer_roles`)
|
|
- show `(none)` if empty
|
|
- [ ] 5.1.5 Add/update tests asserting output format.
|
|
|
|
### 5.2 `validate_task_requirements`
|
|
|
|
- [x] 5.2.1 Replace current multi-table output with a **single** comparison table.
|
|
- [x] 5.2.2 Add a short textual summary below the table.
|
|
- [ ] 5.2.3 Add/update tests asserting table shape + summary presence.
|
|
|
|
## 6. Guided capture: step-specific tools
|
|
|
|
- [x] 6.1 Define guided capture state model (internal only).
|
|
- [x] 6.2 Implement tool `start_guided_capture()`.
|
|
- [x] 6.3 Implement tool `guided_set_description(description: str)`.
|
|
- [x] 6.4 Implement tool `guided_set_role(role_name: str)`.
|
|
- [x] 6.5 Implement tool `guided_set_time_range(date_start: Optional[str] = None, date_end: Optional[str] = None)`.
|
|
- [x] 6.6 Implement tool `guided_set_competences(competences: list[str])`.
|
|
- [ ] 6.7 Add tests covering the step transitions and open-ended ranges.
|
|
|
|
## 7. Competence matching regression (AWS/cloud)
|
|
|
|
- [x] 7.1 Reproduce reported case with a focused test (added deterministic similarity fallback to avoid collapse).
|
|
- [x] 7.2 Inspect `TaskAnalyzer` heuristic competence extraction and normalization.
|
|
- [x] 7.3 Inspect matching/scoring pipeline.
|
|
- [x] 7.4 Fix competence similarity computation so obvious matches ("AWS" vs "AWS") do not collapse.
|
|
- [ ] 7.5 Add regression test(s) to prevent reintroduction.
|
|
|
|
## 8. Search cache reliability
|
|
|
|
- [ ] 8.1 Add debug-level logging (stderr-safe) around:
|
|
- `SearchCache.store_search` creation
|
|
- `SearchCache.get` misses (include age/ttl if available)
|
|
- eviction events (max_size)
|
|
- [ ] 8.2 Verify `max_size` eviction behavior in `SearchCache` implementation.
|
|
- [ ] 8.3 Add tests:
|
|
- store -> filter -> paginate within TTL
|
|
- behavior under forced max-size eviction
|
|
- [ ] 8.4 (Optional) Add a diagnostic tool returning `server_instance_id` to confirm process continuity during client tests.
|
|
- [x] 8.5 Update troubleshooting docs with:
|
|
- ID copy hygiene (avoid extra backticks/whitespace)
|
|
- max_size eviction symptom/fix
|
|
|
|
## 9. Documentation updates
|
|
|
|
- [x] 9.1 Update `README.md`.
|
|
- [x] 9.2 Update `docs/troubleshooting.md`.
|
|
- [x] 9.3 Update OpenSpec design/architecture docs under:
|
|
- `openspec/changes/add-capacity-matching-mcp-server/` (historical baseline)
|
|
|
|
## 10. QA / Validation
|
|
|
|
- [x] 10.1 Run full test suite.
|
|
- [ ] 10.2 Manually validate in Cherry Studio (guide):
|
|
- guided capture step tools
|
|
- confirmation gating (on/off via config)
|
|
- infer_roles output
|
|
- get_task_details formatting
|
|
- search cache persistence across multi-step tools
|