Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .git-blame-ignore-revs
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
# Retrofit annotation commit (opsx-annotate, 2026-05-24)
1e2173556948495a03fa0596628fefccc479c2cd
87ee9f510ab9200862ee029315e04660fc2b6468
30 changes: 30 additions & 0 deletions lib/Mcp/ScholiqToolProvider.php
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,8 @@ public function __construct(
* Returns the app ID that namespaces every tool id.
*
* @return string "scholiq"
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-1
*/
public function getAppId(): string
{
Expand All @@ -169,6 +171,8 @@ public function getAppId(): string
* Per-object authorisation runs in invokeTool().
*
* @return array<int, array<string, mixed>>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-1
*/
public function getTools(): array
{
Expand All @@ -186,6 +190,8 @@ public function getTools(): array
* @param array<string, mixed> $arguments Tool arguments from the LLM call.
*
* @return array<string, mixed>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-2
*/
public function invokeTool(string $toolId, array $arguments): array
{
Expand Down Expand Up @@ -215,6 +221,8 @@ public function invokeTool(string $toolId, array $arguments): array
* @param array<string, mixed> $args Tool arguments.
*
* @return array<string, mixed>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-3
*/
private function handleListCourses(array $args): array
{
Expand Down Expand Up @@ -279,6 +287,8 @@ private function handleListCourses(array $args): array
* @param array<string, mixed> $args Tool arguments.
*
* @return array{error?: array<string, mixed>, limit?: int, status?: string|null}
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-3
*/
private function validateListCoursesArgs(array $args): array
{
Expand Down Expand Up @@ -333,6 +343,8 @@ private function validateListCoursesArgs(array $args): array
* @param array<string, mixed> $args Tool arguments.
*
* @return array<string, mixed>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-4
*/
private function handleGetCourseDetails(array $args): array
{
Expand Down Expand Up @@ -410,6 +422,8 @@ private function handleGetCourseDetails(array $args): array
* @param string $courseUuid The parent course UUID.
*
* @return array<int, array<string, mixed>>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-4
*/
private function loadCourseModules(string $courseUuid): array
{
Expand Down Expand Up @@ -453,6 +467,8 @@ static function (array $a, array $b): int {
* @param string $courseUuid The course UUID.
*
* @return array<string, string>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-3
*/
private function courseSource(array $course, string $courseUuid): array
{
Expand Down Expand Up @@ -485,6 +501,8 @@ private function courseSource(array $course, string $courseUuid): array
* and is NOT wrapped in catch(\Throwable).
*
* @return bool True when the caller is an authenticated user.
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-3
*/
private function requireCourseReadAccess(): bool
{
Expand Down Expand Up @@ -514,6 +532,8 @@ private function requireCourseReadAccess(): bool
* @param string $courseRef The course id/uuid/slug/code.
*
* @return array<string, mixed>|null The normalised course array, or null.
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-4
*/
private function findCourse(string $courseRef): ?array
{
Expand Down Expand Up @@ -555,6 +575,8 @@ private function findCourse(string $courseRef): ?array
* @param array<string, mixed> $course The normalised course array.
*
* @return array<string, mixed>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-3
*/
private function courseSummary(array $course): array
{
Expand All @@ -581,6 +603,8 @@ private function courseSummary(array $course): array
* @param array<string, mixed> $lesson The normalised lesson array.
*
* @return array<string, mixed>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-4
*/
private function moduleSummary(array $lesson): array
{
Expand Down Expand Up @@ -610,6 +634,8 @@ private function moduleSummary(array $lesson): array
* @param string $uuid The object UUID.
*
* @return string The deep link path, e.g. /apps/scholiq/courses/<uuid>.
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-4
*/
private function buildDeepLink(string $type, string $uuid): string
{
Expand All @@ -629,6 +655,8 @@ private function buildDeepLink(string $type, string $uuid): string
* @param mixed $item Raw item from ObjectService.
*
* @return array<string, mixed>
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-5
*/
private function toArray(mixed $item): array
{
Expand Down Expand Up @@ -661,6 +689,8 @@ private function toArray(mixed $item): array
* @param array<string, mixed> $item The normalised object array.
*
* @return string The UUID, or empty string when not found.
*
* @spec openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-5
*/
private function extractUuid(array $item): string
{
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Design — Retrofit `ai-companion-tools`

**Retrofit change. Tasks describe retroactive annotation, not new implementation work.** The code already exists at `lib/Mcp/ScholiqToolProvider.php` (shipped 2026-05-12 alongside hydra ADR-034 + ADR-035 and openregister PR #1466). This change documents the observable contract so future changes have something to extend.

## Goal

Capture the observed behaviour of the 15 methods on `ScholiqToolProvider` as 5 numbered REQs grouped into a new `ai-companion-tools` capability:

| REQ | Methods covered |
|---|---|
| REQ-001 — Provider declares an app id and a hard-coded tool catalogue | `getAppId`, `getTools` |
| REQ-002 — Dispatcher routes by tool id and rejects unknown ids without throwing | `invokeTool` |
| REQ-003 — listCourses validates args, gates on authentication, caps results, and returns privacy-safe summaries | `handleListCourses`, `validateListCoursesArgs`, `requireCourseReadAccess`, `courseSummary`, `courseSource` |
| REQ-004 — getCourseDetails resolves a course by id/uuid/slug/code, returns ordered modules, and never leaks learner PII | `handleGetCourseDetails`, `findCourse`, `loadCourseModules`, `moduleSummary`, `buildDeepLink` |
| REQ-005 — Object normalisation accepts arrays, OpenRegister entities, and JsonSerializable shapes | `toArray`, `extractUuid` |

## Why a new capability (not `--extend`)

The coverage report parked this cluster under `bucket_2a/assessment` because the matcher had to put it somewhere — but `assessment` is the Tests/Exams capability (item banks, QTI 3.0, proctoring). MCP tool provision is genuinely new territory: a per-app contract with hydra's AI chat companion via openregister's `IMcpToolProvider` abstraction. A new capability lets future work (adding more tools, tightening provider-side auth, switching to a dynamic catalogue) extend a clearly-scoped baseline rather than bloating an unrelated capability.

## Non-goals

- No code behaviour changes — annotations only.
- No "fixing" of observed-but-suspicious behaviour. The `requireCourseReadAccess()` tautological tail (`return $userId !== ''` after the empty-string check) is documented in REQ-003 Notes; tightening to a Scholiq-specific group check is a future spec.
- No Dutch translation of tool descriptions — consistent with the rest of MCP tooling at this revision.
- No tools that touch learner data — Enrolment / Attestation / Credential / per-learner tooling is deferred to a follow-up that wires proper per-student authorisation.

## Notes for archiver

- New capability spec under `openspec/specs/ai-companion-tools/spec.md` (no existing file — `--cluster` semantics).
- `retrofit: true` in frontmatter so Specter dashboards can filter the retrofit cohort.
- Annotations on `lib/Mcp/ScholiqToolProvider.php` reference `openspec/changes/retrofit-2026-05-24-ai-companion-tools/tasks.md#task-N`; after archive the tags continue resolving via the archived change directory (ADR-003 convention).
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Retrofit — ai-companion-tools

Describes the observed behaviour of 15 methods on `lib/Mcp/ScholiqToolProvider.php` as 5 new REQs under a brand-new `ai-companion-tools` capability. Code already exists (shipped 2026-05-12 alongside hydra ADR-034 + ADR-035 and openregister PR #1466) — this change retroactively specifies it so future changes have something to extend.

## Affected code units

- `lib/Mcp/ScholiqToolProvider.php::getAppId()`
- `lib/Mcp/ScholiqToolProvider.php::getTools()`
- `lib/Mcp/ScholiqToolProvider.php::invokeTool()`
- `lib/Mcp/ScholiqToolProvider.php::handleListCourses()`
- `lib/Mcp/ScholiqToolProvider.php::validateListCoursesArgs()`
- `lib/Mcp/ScholiqToolProvider.php::handleGetCourseDetails()`
- `lib/Mcp/ScholiqToolProvider.php::loadCourseModules()`
- `lib/Mcp/ScholiqToolProvider.php::courseSource()`
- `lib/Mcp/ScholiqToolProvider.php::requireCourseReadAccess()`
- `lib/Mcp/ScholiqToolProvider.php::findCourse()`
- `lib/Mcp/ScholiqToolProvider.php::courseSummary()`
- `lib/Mcp/ScholiqToolProvider.php::moduleSummary()`
- `lib/Mcp/ScholiqToolProvider.php::buildDeepLink()`
- `lib/Mcp/ScholiqToolProvider.php::toArray()`
- `lib/Mcp/ScholiqToolProvider.php::extractUuid()`

## Approach

- For each method: describe observed inputs, outputs, pre/postconditions, failure modes from the code as it ships
- Draft REQs that fold the 15 methods into 5 distinct observable behaviours (provider identity & catalogue, dispatch, list-courses tool, get-course-details tool, object normalisation)
- Notes sections surface observed-but-suspicious behaviour (e.g. `requireCourseReadAccess()` ends with a tautological `$userId !== ''` check after already returning false on empty — currently lets every authenticated user through; that is the observed behaviour and is left as-is here)
- Mint as a new capability (not `--extend`) because no MCP / AI-companion capability exists in scholiq's specs/ yet — the coverage report categorised it under bucket_2a/`assessment` only because the matcher had nowhere else to put it

Source: `openspec/coverage-report.md` generated 2026-05-24. See [retrofit playbook](../../../.github/docs/claude/retrofit.md).
Loading
Loading