Upstream Schema Alignment — Annotation Spec & Migration-Readiness CLI (RHIDP-15346/15347; split from #4042)

[mareklibra]

Summary

Split from #4042 per gate decision.

This issue owns RHDHPLAN-1513 work only:

Story	Deliverable
RHIDP-15346	Annotation specification document (publish mapping + annotation docs)
RHIDP-15347	@red-hat-developer-hub/backstage-plugin-boost-migration-readiness CLI scaffold

RHIDP-15302 (migration design + RHDH sign-off) stays on #4042 (RHDHPLAN-1507).

Deferral: If RHDHPLAN-1513 is deferred from 2.1, this entire issue defers with it. Do not block #4042 / RHIDP-15302 on this work.

Labels: workspace/boost, feature (add ready-to-code when unblocked)
Dependencies: Mapping reconciliation #4188 / #4189 — done; soft: #4040 annotation constants for CLI reuse
RHIDP Stories: RHIDP-15346, RHIDP-15347
Feature: RHDHPLAN-1513 — Epic RHIDP-15334

---

Prerequisites (done)

• Gate decisions: comment on #4042
• Current → upstream mapping tables reconciled in OpenSpec (#4189)
• Binding rules: Decision 1 = current SoT; MCP already kind-aligned (API + mcp-server); seven categories only; vector-store / ai-tool out of scope

Related downstream context (cite in docs/CLI where useful):

• Model server: #4211 + upstream backstage#34476
• Agents: RHIDP-15865 / #4164

---

Part A — Annotation specification (RHIDP-15346)

Publish the formal annotation + mapping spec for platform engineers (OpenSpec scenarios already updated by #4189; this story writes/publishes the customer-facing / specifications/ doc).

Specs / OpenSpec

• annotation-specification/spec.md
• upstream-schema-alignment/tasks.md group 1

Tasks

• 1.1 Document all rhdh.io/ai-asset-category values (seven only)
• 1.2 Document rhdh.io/ai-asset-version format and normalization rules
• 1.3 Document rhdh.io/ai-asset-source format (include known connectors beyond kagenti/llamastack/oci — e.g. mcp-registry, rhoai)
• 1.4 Document entity kind + spec.type mapping table (Decision 1 current state)
• 1.5 Document MCP mapping to RFC #32062 / backstage#34016 — kind already aligned; field/module/fallback only (not kind: McpServer)
• 1.6 Document model / model-server mapping vs RFC #33060 / #34476 / #4211
• 1.7 Assign confidence levels per mapping (post-docs(#4188): reconcile current→upstream AI-asset mapping tables #4189 table)
• 1.8 Document fields requiring transformation per entity type
• 1.9 Add explicit "Future Work" section (actual migration deferred)
• 1.10 Header with draft status + last-updated date
• 1.11 Cross-reference Decision 1 as SoT; catalog-entities only as supplementary (no vector-store/ai-tool rows)
• 1.12 Publish under workspaces/boost/specifications/

---

Part B — Migration-readiness CLI (RHIDP-15347)

Read-only CLI using the reconciled mapping. Do not revive API → McpServer kind-rename examples.

Specs / OpenSpec

• migration-readiness-tooling/spec.md
• upstream-schema-alignment/tasks.md groups 2–5

Before coding — specify CLI contract (gate §3)

• Catalog auth model (token / cookie / service account — not only --catalog-url)
• --filter semantics
• Full JSON report schema (entityRef, warnings[], rfcIds, alreadyAligned, partial-annotation flags)
• Package role + bin for plugins/boost-migration-readiness/
• Mapping source: hardcoded table vs import from #4040 SDK
• Rules for partial annotations, unrecognized category, kind/type mismatch, confidence
• Mock catalog API contract for integration tests

Implementation tasks

• 2.1–2.12 CLI package, catalog client, filter by rhdh.io/ai-asset-category, mapping logic, JSON + text formatters, missing/partial handling, args, assessment footer
• 3.1–3.10 Tests
• 4.1–4.8 Package README / usage / confidence / future-work messaging
• 5.1–5.5 Cross-refs (RHDHPLAN-1507 / Upstream Schema Alignment — Annotation Spec, Migration Design & Tooling (issue 4 of 29) #4042 RHIDP-15302, RFCs, related stories)

---

Optional follow-ups (gate §2 — can be separate PR)

• Resolve version fallback: 0.0.0-unknown vs "unknown"
• Align connector OpenSpecs (mcp-registry-connector, rhoai-connector) if needed
• Expand ai-asset-source connector-name vocabulary in annotation-scheme
• Demote competing catalog-entities cross-refs for readiness SoT

---

Out of scope

• RHIDP-15302 migration design + sign-off → #4042
• Actual catalog entity migration / processor
• vector-store / ai-tool categories

---

Acceptance criteria

• Published annotation/mapping spec matches post-docs(#4188): reconcile current→upstream AI-asset mapping tables #4189 OpenSpec (seven categories; MCP kind-aligned)
• CLI reports correct current → target / transforms / confidence; no kind: McpServer rename
• Read-only; footer states assessment-only / migration future work
• Linked from narrowed Upstream Schema Alignment — Annotation Spec, Migration Design & Tooling (issue 4 of 29) #4042; does not claim RHIDP-15302

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 9:19 AM UTC · Completed 9:23 AM UTC

Commit: 50cec85 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Feature

Dependency status

• docs(#4188): reconcile current→upstream AI-asset mapping tables #4189 (mapping table reconciliation) — merged ✅
• Entity-Provider SDK — Types, Interfaces, Annotation Validation (issue 2 of 29) #4040 (annotation constants SDK) — open, but listed as a soft dependency. The CLI can hardcode the mapping table initially and adopt SDK imports later.
• feat(#4209): add ai-model-server API spec type extension #4211 / feat(#4128): add AiResource agent typed schema #4164 — open PRs for related downstream context (model-server, agents). Not blocking, but useful references for the spec doc (tasks 1.5, 1.6).

Implementation notes

• The OpenSpec files referenced in the issue body (annotation-specification/spec.md, migration-readiness-tooling/spec.md, upstream-schema-alignment/tasks.md) contain detailed requirements — start there.
• Part B includes a "before coding" gate (§3) requiring the CLI contract to be specified first (auth model, filter semantics, JSON report schema). This should be addressed before implementation begins.
• The issue is self-contained from Upstream Schema Alignment — Annotation Spec, Migration Design & Tooling (issue 4 of 29) #4042 — it explicitly does not own RHIDP-15302 (migration design + sign-off).

Proposed test case

CLI integration tests:
- Mock catalog API with entities across all 7 valid ai-asset-category values
- Include entities with: missing annotations, partial annotations,
  unrecognized categories, kind/type mismatches
- Assert JSON report contains: entityRef, warnings[], rfcIds,
  alreadyAligned, confidence per entity
- Assert no kind:McpServer rename suggestions appear
- Assert footer states "assessment-only / migration is future work"
- Test --filter restricts output to matching entities only

Spec validation:
- All 7 categories documented, no vector-store/ai-tool rows
- MCP mapping references field/module/fallback only, not kind: McpServer
- Confidence levels assigned per mapping row

---

Labels: The issue body requests workspace/boost and feature labels. The issue is well-specified with prerequisites resolved, so ready-to-code is appropriate per the issue author's own criteria.

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance