docs(boost): RHIDP-15302 migration design document (from #4042)

[mareklibra]

Summary

Parent: #4042 (narrowed to RHIDP-15302)
Split sibling (out of scope here): #4220 (RHIDP-15346/15347)

Create the RHIDP-15302 migration design document: current → upstream/downstream mapping for the seven AI-asset categories, field-level transformation rules, consumer-facing impact, and backward compatibility.

Mapping tables were already reconciled in #4188 / #4189. This issue writes the design document from that SoT — it does not re-litigate Decision 1 or MCP Option 3.

Labels: workspace/boost, documentation, ready-to-code
RHIDP Story: RHIDP-15302 (partial — design doc only)
Feature: RHDHPLAN-1507 — Epic RHIDP-15258

---

Goal

Ship a design doc that platform engineers can review and that an RHDH architect can later sign off on (#4042 tasks 8.5–8.6 — human follow-up, not this issue).

Suggested path (use unless repo convention says otherwise):

workspaces/boost/specifications/ai-asset-upstream-migration-design.md

Also update cross-links from:

• migration-readiness/spec.md
• ai-catalog-entity-model/tasks.md group 8 (mark 8.1–8.4 progress if appropriate)

---

Binding context (do not re-open)

Topic	Decision
Current kinds / categories	Decision 1 — seven categories only
MCP	Kind already aligned: API + mcp-server (backstage#34016); document field/module/fallback gaps only — no kind: McpServer
Model server	Candidate API + ai-model-server: upstream backstage#34476 + downstream #4211
Agents	Not RFC #32062; track RHIDP-15865 / #4164 (AiResource + spec.type: agent)
Skills / rules	Toward shipped AiResource
Skill-bundle	No upstream kind yet — Low confidence
vector-store / ai-tool	Out of scope (Augment leftovers)

Gate / decisions: comment on #4042

Primary OpenSpec sources after #4189:

• upstream-schema-alignment/proposal.md
• upstream-schema-alignment/design.md
• annotation-specification/spec.md
• migration-readiness/spec.md

---

Document outline (required sections)

1. Status / purpose — readiness design only; actual migration is future work
2. Current-state SoT — Decision 1 table (seven categories)
3. Mapping table — current kind + spec.type + annotation → target + confidence + notes (cite docs(#4188): reconcile current→upstream AI-asset mapping tables #4189)
4. Transformation rules — per category, field-level (not only kind)
5. Consumer-facing changes — catalog UI filters, entity refs, API queries
6. Backward compatibility — e.g. keep rhdh.io/ai-asset-category for one major version; deprecation approach
7. Out of scope — vector-store / ai-tool; CLI (Upstream Schema Alignment — Annotation Spec & Migration-Readiness CLI (RHIDP-15346/15347; split from #4042) #4220); live migration
8. Sign-off placeholder — empty section for reviewer / role / date / status (to be filled in Upstream Schema Alignment — Annotation Spec, Migration Design & Tooling (issue 4 of 29) #4042 tasks 8.5–8.6; do not invent an approval)

---

Tasks (RHIDP-15302 — 8.1–8.4 only)

• 8.1 Create migration design document with mapping table: current → target for all seven categories
• 8.2 Document transformation rules per category (field-level; MCP = remotes/module/fallback, not kind rename)
• 8.3 Identify consumer-facing changes: catalog UI filters, entity refs, API queries
• 8.4 Document backward compatibility strategy
• Cross-link from OpenSpec migration-readiness / tasks to the new doc
• Cite feat(#4209): add ai-model-server API spec type extension #4211 + #34476 (model-server) and RHIDP-15865 / feat(#4128): add AiResource agent typed schema #4164 (agents) in the relevant rows

---

Out of scope

• 8.5 Obtain sign-off — human on #4042 after this PR merges
• 8.6 Document completed sign-off — same
• RHIDP-15346 annotation publish / RHIDP-15347 CLI → #4220
• Re-writing mapping tables already fixed in docs(#4188): reconcile current→upstream AI-asset mapping tables #4189 (only consume them)
• Implementing catalog migration or a catalog processor

---

Acceptance criteria

• Design doc exists under workspaces/boost/specifications/ (or agreed path) with all required sections
• Seven categories covered; consistent with post-docs(#4188): reconcile current→upstream AI-asset mapping tables #4189 OpenSpec
• No API → McpServer kind-rename guidance
• vector-store / ai-tool explicitly out of scope
• Sign-off section present but unsigned (placeholder only)
• PR closes this issue and references #4042

---

Suggested PR title

docs(#NNNN): RHIDP-15302 migration design document

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 9:37 AM UTC · Completed 9:41 AM UTC

Commit: 50cec85 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Documentation

All source material is available — PR #4189 (mapping tables) is merged, and the OpenSpec files provide the source of truth. The workspaces/boost/specifications/ directory already exists.

References to cite (not blockers):

• PR feat(#4209): add ai-model-server API spec type extension #4211 (ai-model-server downstream) — open, cite in model-server row
• PR feat(#4128): add AiResource agent typed schema #4164 (AiResource agent schema) — open, cite in agent row
• backstage#34476 (upstream model-server) — open, cite with Medium/Low confidence

Proposed test case:

# Validation checks:
- File exists at workspaces/boost/specifications/ai-asset-upstream-migration-design.md
- All 8 required sections present
- Mapping table covers exactly 7 categories
- MCP row: kind: API → kind: API (no rename to McpServer)
- vector-store / ai-tool appear only in Out of Scope
- Sign-off section is an unsigned placeholder
- Cross-links added to migration-readiness/spec.md and tasks.md

---

Labels: The issue explicitly requests these labels and they match the content: documentation task in the boost workspace, ready for implementation with all prerequisites met.

---

Next steps:

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

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 9:42 AM UTC · Completed 9:50 AM UTC

Commit: 50e1563 · View workflow run →