docs(ai-integrations): retool AIResource OpenSpec onto url:oci:// source-location

[johnmcollier]

Summary

• Retool the AIResource OpenSpec change to use upstream backstage.io/source-location with url:oci://… instead of RHDH spec.location
• Keep format-only OCI validation (zero registry I/O); explicitly defer OCI UrlReader / catalog location type oci
• Update proposal, design, tasks, and behavioral specs for RHIDP-15739 review

Test plan

• Review OpenSpec proposal/design/tasks against RHIDP-15739 AC
• Confirm specs no longer require spec.location and validate url:oci://… source-location
• Confirm non-goals still exclude UrlReader / registry fetch

Made with Cursor

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 10:42 PM UTC · Ended 11:21 PM UTC
Commit: bbaec9a · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.35%. Comparing base (e168046) to head (acdcad0).
⚠️ Report is 12 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3938      +/-   ##
==========================================
- Coverage   57.35%   57.35%   -0.01%     
==========================================
  Files        2384     2383       -1     
  Lines       95616    95612       -4     
  Branches    26712    26712              
==========================================
- Hits        54839    54835       -4     
- Misses      39205    39212       +7     
+ Partials     1572     1565       -7     

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.54% <ø> (ø)		Carriedforward from bbaec9a
ai-integrations	69.06% <ø> (-0.21%)	⬇️
app-defaults	69.79% <ø> (ø)		Carriedforward from bbaec9a
augment	46.67% <ø> (ø)		Carriedforward from bbaec9a
boost	75.89% <ø> (ø)		Carriedforward from bbaec9a
bulk-import	72.63% <ø> (ø)		Carriedforward from bbaec9a
cost-management	13.55% <ø> (ø)		Carriedforward from bbaec9a
dcm	60.72% <ø> (ø)		Carriedforward from bbaec9a
extensions	56.28% <ø> (ø)		Carriedforward from bbaec9a
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from bbaec9a
global-header	62.19% <ø> (ø)		Carriedforward from bbaec9a
homepage	47.67% <ø> (ø)		Carriedforward from bbaec9a
install-dynamic-plugins	56.77% <ø> (ø)		Carriedforward from bbaec9a
intelligent-assistant	74.05% <ø> (ø)		Carriedforward from bbaec9a
konflux	91.98% <ø> (ø)		Carriedforward from bbaec9a
lightspeed	69.02% <ø> (ø)		Carriedforward from bbaec9a
mcp-integrations	83.40% <ø> (ø)		Carriedforward from bbaec9a
orchestrator	62.65% <ø> (ø)		Carriedforward from bbaec9a
quickstart	65.18% <ø> (ø)		Carriedforward from bbaec9a
sandbox	79.56% <ø> (ø)		Carriedforward from bbaec9a
scorecard	82.66% <ø> (ø)		Carriedforward from bbaec9a
theme	83.85% <ø> (ø)		Carriedforward from bbaec9a
translations	5.12% <ø> (ø)		Carriedforward from bbaec9a
x2a	79.31% <ø> (ø)		Carriedforward from bbaec9a

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e168046...acdcad0. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 14 rules

✅ Cross-repo context

  Not relevant to this PR: redhat-developer/rhdh

  Not relevant to this PR: redhat-developer/rhdh-chart

  Not relevant to this PR: redhat-developer/rhdh-operator

  Not relevant to this PR: redhat-developer/rhdh-local

1. OCI validation contract mismatch 🐞 Bug ≡ Correctness

Description

The updated OpenSpec states OCI validation must be based on
metadata.annotations["backstage.io/source-location"] (requiring url:oci://…) and that
spec.location is not the validation input, but the shipped backend validator only inspects
entity.spec.location.{type,target} and never reads the annotation. Entities following the new spec
(annotation-only, no spec.location) will therefore bypass the OCI format validation behavior
described by the spec and produce different validation/error semantics than documented.

Code

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-entity-schema/spec.md[R35-78]

+### Requirement: No RHDH `spec.location` field
+
+RHDH SHALL NOT require or validate a `spec.location` struct for AIResource asset location. Git/HTTPS and OCI content references use `backstage.io/source-location` only.
+
+#### Scenario: Entity without `spec.location` accepted
+
+- **WHEN** an AIResource entity omits `spec.location` and provides a valid `backstage.io/source-location`
+- **THEN** the entity passes RHDH extension validation for location concerns
+
+#### Scenario: `spec.location` is not the OCI validation input
+
+- **WHEN** an AIResource entity includes a legacy `spec.location` field
+- **THEN** RHDH OCI format validation does not treat `spec.location.target` as the source of truth (validation is based on `backstage.io/source-location`)
+
+---
+
+### Requirement: OCI source-location URI scheme
+
+When an AIResource entity declares `backstage.io/source-location` whose location-ref target uses the `oci://` scheme, the annotation SHALL use the Backstage location-ref form `url:oci://…`, and the target SHALL be a well-formed OCI reference.
+
+#### Scenario: Valid OCI source-location accepted
+
+- **WHEN** an AIResource entity declares `backstage.io/source-location: url:oci://quay.io/myorg/my-skills:latest`
+- **THEN** the entity passes OCI format validation
+
+#### Scenario: Valid OCI digest source-location accepted
+
+- **WHEN** an AIResource entity declares `backstage.io/source-location: url:oci://quay.io/myorg/my-skills@sha256:<digest>`
+- **THEN** the entity passes OCI format validation
+
+#### Scenario: OCI target without `oci://` scheme rejected

-When `spec.location.type` is `oci`, the `spec.location.target` value SHALL begin with the `oci://` scheme prefix.
+- **WHEN** an AIResource entity declares `backstage.io/source-location: url:quay.io/myorg/my-skills:latest` intending an OCI asset
+- **THEN** the catalog does not treat it as a valid OCI source-location (no `oci://` target scheme)

-#### Scenario: Valid OCI target accepted
+#### Scenario: Bare `oci://` annotation without `url:` prefix rejected

-- **WHEN** an AIResource entity declares `spec.location.type: oci` and `spec.location.target: oci://quay.io/myorg/my-skills:latest`
-- **THEN** the entity passes validation
+- **WHEN** an AIResource entity declares `backstage.io/source-location: oci://quay.io/myorg/my-skills:latest`
+- **THEN** the catalog rejects it with an actionable error stating that the location-ref form `url:oci://…` is required

-#### Scenario: OCI target without prefix rejected
+#### Scenario: Malformed OCI target rejected

-- **WHEN** an AIResource entity declares `spec.location.type: oci` and `spec.location.target: quay.io/myorg/my-skills:latest`
-- **THEN** the catalog rejects it with an error stating that the `oci://` prefix is required and shows the expected format
+- **WHEN** an AIResource entity declares `backstage.io/source-location: url:oci://` or another malformed OCI reference
+- **THEN** the catalog rejects it with an error describing the expected `oci://registry/repository[:tag|@digest]` format

Relevance

⭐⭐⭐ High

Team previously hardened OCI validation on spec.location; spec/impl mismatch likely requires
retooling validator to source-location.

PR-#3764
PR-#3860

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The OpenSpec requires OCI validation based on backstage.io/source-location and says
spec.location is not the input, but the current backend validation reads only
entity.spec.location and validates spec.location.target when spec.location.type is oci. The
provided examples/README also still use spec.location, confirming the implementation hasn’t been
retooled yet.

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-entity-schema/spec.md[35-84]
workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-catalog-ingestion/spec.md[35-53]
workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/src/collectOciErrors.ts[25-70]
workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/src/AIResourceExtensionsProcessor.ts[43-95]
workspaces/ai-integrations/examples/ai-resource-oci.yaml[11-23]
PR-#3764

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
OpenSpec now defines OCI content location and validation using the `backstage.io/source-location` annotation in location-ref form (`url:oci://…`) and explicitly deprecates `spec.location` for AIResource asset location. However, the current catalog backend module still validates OCI only when `spec.location.type === 'oci'` and validates `spec.location.target` — it does not parse or validate `backstage.io/source-location` at all.

This makes the spec misleading and allows entities that follow the new contract (annotation-only) to skip OCI validation entirely.

## Issue Context
- OpenSpec docs were retooled to upstream `backstage.io/source-location`.
- The existing implementation in `catalog-backend-module-ai-resource-extensions` is still on the legacy `spec.location` model.

## Fix Focus Areas
Choose **one** of these approaches and apply consistently across code + examples + docs:

**A) Implement the new contract** (recommended):
- Parse `metadata.annotations['backstage.io/source-location']` as a Backstage location-ref.
- Enforce `url:` prefix and validate the parsed target is a well-formed `oci://registry/repository[:tag|@digest]` when the target scheme is `oci://`.
- Keep legacy `spec.location` either ignored (per spec) or explicitly deprecated with a clear error/warning.

**B) If this PR is spec-only (future work)**:
- Remove/soften normative language (e.g., “SHALL NOT validate `spec.location`”) and clearly mark the `source-location` behavior as deferred until the backend module is updated.

Concrete code/doc touchpoints to update:
- workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/src/collectOciErrors.ts[25-72]
- workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/src/AIResourceExtensionsProcessor.ts[43-98]
- workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/src/module.ts[16-42]
- workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/README.md[29-103]
- workspaces/ai-integrations/examples/ai-resource-oci.yaml[1-23]
- workspaces/ai-integrations/examples/ai-resource-git.yaml[1-24]
- workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-catalog-ingestion/spec.md[35-53]
- workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-entity-schema/spec.md[35-100]

## Notes
Add/update unit tests to cover:
- valid `backstage.io/source-location: url:oci://…`
- malformed targets (`url:oci://`, empty segments, whitespace)
- bare `oci://…` without `url:`
- legacy `spec.location` behavior (ignored or explicitly handled)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Tasks/examples out of sync 🐞 Bug ⚙ Maintainability

Description

The change task list marks the example migrations as completed and references an
AIResourceOciProcessor, but the repository examples and plugin README still use the legacy
spec.location model and the backend module actually registers AIResourceExtensionsProcessor.
This makes the change’s tasks and guidance internally inconsistent and likely to mislead
implementers/reviewers about what has already been updated.

Code

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/tasks.md[R47-52]

## 6. Documentation & Examples

-- [ ] 6.1 Add an example git-backed AIResource `catalog-info.yaml`
-- [ ] 6.2 Add an example OCI-backed AIResource `catalog-info.yaml`
-- [ ] 6.3 Document schema fields and registration guidance in the workspace
-- [ ] 6.4 Document the OCI validation-only behavior and its air-gap rationale
+- [x] 6.1 Update the example git-backed AIResource `catalog-info.yaml` (source-location only; no `spec.location`)
+- [x] 6.2 Update the example OCI-backed AIResource `catalog-info.yaml` to use `backstage.io/source-location: url:oci://…`
+- [ ] 6.3 Document schema fields and registration guidance in the workspace (including why `url:` prefix is required)
+- [ ] 6.4 Document the OCI validation-only behavior, air-gap rationale, and that an OCI UrlReader is deferred

Relevance

⭐⭐⭐ High

Repo history shows reviewers accept fixing misleading OpenSpec tasks/docs; examples/README alignment
is routinely requested.

PR-#3692
PR-#3859

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The tasks file asserts example migrations are complete and references AIResourceOciProcessor, but
the actual example YAML and plugin README still instruct spec.location.* usage, and the backend
module registers AIResourceExtensionsProcessor (not AIResourceOciProcessor).

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/tasks.md[47-52]
workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/tasks.md[17-21]
workspaces/ai-integrations/examples/ai-resource-oci.yaml[1-23]
workspaces/ai-integrations/examples/ai-resource-git.yaml[10-24]
workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/src/module.ts[16-42]
workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/README.md[29-34]
workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/README.md[61-103]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`tasks.md` claims the example entity YAMLs were updated to the new `backstage.io/source-location` (`url:oci://…`) model and no longer use `spec.location`, but the actual examples and plugin README still use `spec.location`. In addition, tasks/docs refer to an `AIResourceOciProcessor` while the current backend module registers `AIResourceExtensionsProcessor`.

This creates unreliable tracking and conflicting instructions inside the repo.

## Issue Context
This PR’s OpenSpec is retooled to an upstream-aligned contract, but adjacent repo documentation/examples weren’t updated (or the tasks were marked complete prematurely).

## Fix Focus Areas
- workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/tasks.md[15-52]
- workspaces/ai-integrations/examples/ai-resource-git.yaml[1-24]
- workspaces/ai-integrations/examples/ai-resource-oci.yaml[1-23]
- workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/README.md[61-103]
- workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/src/module.ts[16-42]

## Expected outcome
Pick one consistent state and apply it everywhere:
1) If examples truly should be migrated now: update both example YAMLs and README to match the new annotation-based model and remove `spec.location` usage; update processor naming references.
2) If migration is deferred: change the tasks back to unchecked and update prose to clearly state the work is pending; avoid stating that examples are already migrated.

Also reconcile naming: either rename references from `AIResourceOciProcessor` to the actual processor (`AIResourceExtensionsProcessor`) or introduce the class that the docs/tasks refer to.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[rhdh-qodo-merge]

PR Summary by Qodo

docs(ai-integrations): align AIResource OCI refs to source-location url:oci://

📝 Documentation 🕐 20-40 Minutes

AI Description

• Retools AIResource OpenSpec to use backstage.io/source-location (no spec.location).
• Standardizes OCI references on location-ref form url:oci://… with format-only validation.
• Updates proposal/design/specs/tasks to explicitly defer OCI UrlReader and registry discovery.

Diagram

graph TD
U["User"] --> L["Register catalog location"] --> Y["AIResource catalog-info.yaml"] --> P["Catalog ingestion"] --> A["Read annotation: backstage.io/source-location"] --> K["Check target scheme"]
K --> G["git/https: pass-through"] --> I[("Catalog index")]
K --> O["oci: url:oci://…"] --> C["OCI format-only validation"] --> I

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Dual-accept `spec.location` and `backstage.io/source-location` during migration

• ➕ Smoother transition for existing entity YAML and automation still emitting spec.location
• ➕ Reduces immediate breakage risk while docs/specs catch up across repos
• ➖ Extends divergence from upstream and prolongs cleanup
• ➖ Creates ambiguity about the source of truth and validation surface

2. Treat bare `oci://…` as acceptable source-location (no `url:` prefix)

• ➕ Less surprising to users who expect URI-like values in annotations
• ➕ Shorter examples and simpler authoring
• ➖ Breaks Backstage location-ref parsing expectations (parses as type oci with malformed target form)
• ➖ Makes future UrlReader integration harder and less standard

3. Introduce catalog location type `oci` now (registry-backed entity discovery)

• ➕ Enables discovering/refreshing entities directly from registries
• ➕ Could unify registration + content resolution around OCI
• ➖ Requires registry I/O, auth, caching, and air-gap story up front
• ➖ Significantly larger scope than format validation and upstream alignment

Recommendation: Keep the PR’s approach: standardize on upstream backstage.io/source-location with location-ref url:oci://… and explicitly defer any OCI UrlReader / registry discovery. This minimizes divergence from upstream, preserves air-gap safety (no registry I/O), and keeps the door open for a future UrlReader that can resolve oci: targets while staying compatible with Backstage parsing.

Files changed (7) +212 / -123

Documentation (7) +212 / -123

.openspec.yamlAnnotate retooling and update OpenSpec metadata +4/-0

Annotate retooling and update OpenSpec metadata

• Updates the change metadata with an updated date and notes explaining the retooling to upstream 'backstage.io/source-location' and removal of 'spec.location'.

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/.openspec.yaml

design.mdRetool design to upstream source-location + 'url:oci://…' +66/-34

Retool design to upstream source-location + 'url:oci://…'

• Reframes the design around upstream 'AiResource' behavior: no 'spec.location', and content references live in 'backstage.io/source-location'. Clarifies the 'url:oci://…' location-ref requirement, keeps OCI ingestion air-gap safe (format-only validation), and explicitly defers OCI UrlReader and catalog location type 'oci'.

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/design.md

proposal.mdUpdate proposal to remove 'spec.location' and standardize OCI refs +17/-12

Update proposal to remove 'spec.location' and standardize OCI refs

• Updates the proposal’s “What Changes”, capabilities, and non-goals to make 'backstage.io/source-location' the canonical asset location and to represent OCI as 'url:oci://…'. Makes the deferred scope explicit (no OCI UrlReader, no registry-based entity discovery).

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/proposal.md

spec.mdRewrite ingestion requirements around standard locations + OCI annotation validation +36/-31

Rewrite ingestion requirements around standard locations + OCI annotation validation

• Reorients ingestion requirements so entity YAML is always registered via standard catalog locations, while content location is expressed via 'backstage.io/source-location'. Defines OCI validation behavior against 'url:oci://…' (including rejecting bare 'oci://…') and reinforces zero registry/network I/O constraints.

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-catalog-ingestion/spec.md

spec.mdUpdate entity page spec to render location from source-location +10/-10

Update entity page spec to render location from source-location

• Updates the entity page contract to source the displayed asset location from 'backstage.io/source-location', not 'spec.location.target'. Clarifies UX expectations: clickable links for git/HTTPS location-refs and copyable text for OCI 'url:oci://…' references.

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-entity-page/spec.md

spec.mdDefine schema extension rules without 'spec.location' and add OCI annotation rules +49/-16

Define schema extension rules without 'spec.location' and add OCI annotation rules

• Adds explicit requirements that RHDH must not require/validate 'spec.location' for AIResource content location, and that OCI references must use 'backstage.io/source-location' in 'url:oci://…' form. Updates error-quality language to include annotation-based validation paths.

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-entity-schema/spec.md

tasks.mdRetool implementation tasks toward source-location and 'url:' prefix enforcement +30/-20

Retool implementation tasks toward source-location and 'url:' prefix enforcement

• Updates the task plan to reflect the migration away from 'spec.location' and toward validating OCI via 'backstage.io/source-location' with 'url:oci://…'. Adds explicit out-of-scope items (OCI UrlReader, registry discovery) and updates testing/documentation tasks accordingly.

workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/tasks.md

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 10:42 PM UTC · Completed 11:21 PM UTC
Commit: bbaec9a · View workflow run →

[johnmcollier]

/fs-review

[gabemontero]

just a minor, possible, addition

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 7:39 PM UTC · Completed 8:19 PM UTC
Commit: bbaec9a · View workflow run →

[johnmcollier]

/fs-fix address review comment

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:43 PM UTC · Completed 5:04 PM UTC
Commit: acdcad0 · View workflow run →

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

Review

Findings

Medium

• [internal-consistency] workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/tasks.md — Tasks 6.1 and 6.2 are marked as completed ([x]), claiming the example catalog-info.yaml files were updated to remove spec.location and use backstage.io/source-location. However, the actual example files at workspaces/ai-integrations/examples/ai-resource-git.yaml and workspaces/ai-integrations/examples/ai-resource-oci.yaml still contain spec.location structs (type: git/oci and target:). The OCI example also lacks the backstage.io/source-location annotation entirely. Either update the examples in this PR or un-mark tasks 6.1/6.2.

• [stale-doc] workspaces/ai-integrations/plugins/catalog-backend-module-catalog-backend-module-ai-resource-extensions/README.md — The plugin README extensively documents the old spec.location.type/spec.location.target model. Once implementation tasks 1.4 and 2.2 (retool OCI processor to backstage.io/source-location) are completed, this README will need updating. Consider adding an explicit task to track the README update — task 6.3 covers general docs but does not call out the plugin README specifically.

Low

• [edge-case] workspaces/ai-integrations/openspec/changes/ai-resource-catalog-entity-kind/specs/ai-resource-entity-schema/spec.md — The "Bare oci:// without url: prefix rejected" scenario describes desired rejection behavior. Design decision D3 explains that parseLocationRef yields type oci (not url) for bare oci://... values. The spec is internally consistent; implementers should note the processor must handle both the url-type case (correct url:oci://... form) and the oci-type case (bare oci://... form) to produce the specified actionable error.

• [naming-convention] design.md and proposal.md — Canonical Touchpoints list Jira IDs as plain text without clickable URLs. The sibling openspec (remove-kfmr-client-code) uses [RHIDP-NNNNN](https://redhat.atlassian.net/browse/RHIDP-NNNNN) link format and separates Plan from Jira references.

• [stale-doc] Boost workspace files (workspaces/boost/openspec/changes/ai-catalog-frontend/{design.md, specs/entity-extensions/spec.md, tasks.md}) reference spec.location.type/spec.location.target. These are in a separate workspace and accurately describe the current production code; coordinate updates when the ai-integrations workspace completes its retooling.

• [stale-doc] Source code documentation — JSDoc in AIResourceExtensionsProcessor.ts and error messages in collectOciErrors.ts reference the current spec.location model. These are accurate for the current code and will need updating alongside implementation tasks 1.4/2.2.

• [missing-authorization] No GitHub issue is linked. Jira tickets (RHIDP-15739, RHIDP-13942, RHDHPLAN-1113) referenced in the PR body and design documents provide traceable authorization.