diff --git a/.ai/spec/health-report.md b/.ai/spec/health-report.md new file mode 100644 index 00000000..738ece55 --- /dev/null +++ b/.ai/spec/health-report.md @@ -0,0 +1,95 @@ +# Spec health report + +Last evaluated: 2026-08-31 +Trigger: post-milestone: spec-drift alignment sweep +Layout: software (.ai/spec/) + +## Stale + +Fixed in this pass: + +- **`what/system-overview.md` rule 13** — readiness was described as the + `/readyz` endpoint returning a non-2xx status. Actual code + (`src/components/ReadinessAlert.tsx`) polls `/readiness` via + `consoleFetchJSON` and checks a JSON `{ ready: boolean }` body, re-polling + every 10s until ready. Endpoint name and mechanism corrected. + +- **`what/chat.md` rule 8 event table** — listed `reasoning` and + `skill_selected` events as "consumed with no-op handling — payload is never + rendered, logged, or passed to `console.warn`." No handler for these events + exists anywhere in `src/` (never has, per `git log -S`); they fall through to + the default `console.warn` branch in `Prompt.tsx`. Rows removed; added a note + that any unlisted event is treated as unrecognized and warned. + +- **`what/tools.md` Planned Changes** — OLS-1556 (tool display), OLS-2598 (MCP + Apps), OLS-2722 (OLS Tool UI extensibility) are all shipped and documented as + current behavior (rules 1-7, 15-27; code: `ResponseTools.tsx`, `MCPApp.tsx`, + `OlsToolUIs.tsx`, `useToolUIMapping.ts`, `ols.tool-ui` extension). Removed + from planned. + +- **`what/system-overview.md` Planned Changes** — removed OLS-2598 and + OLS-2722 (shipped, see above) and OLS-2816 / OLS-2826 (shipped: + `useOpenOLS` implements `submitImmediately` + `hidePrompt`; chat.md rules 28 + and 29 document them as current). + +- **`what/attachments.md` Planned Changes** — removed OLS-2116 (ManagedCluster + "Attach cluster info" + ManagedClusterInfo fetch shipped in `Prompt.tsx`; + rule 13 documents it) and OLS-1896 (ACM Application/ApplicationSet detection + shipped in `useLocationContext.ts`; rule 1 documents it). + +- **`how/streaming.md` module map** — attributed the `QUERY_ENDPOINT` constant + to `src/config.ts`. It is actually defined in `src/components/Prompt.tsx` + (`getApiUrl('/v1/streaming_query')`); `config.ts` only provides `getApiUrl`. + Corrected. + +- **`how/components.md` module map** — listed a `Modal.tsx` "reusable modal + wrapper" that does not exist. Replaced with the actual generic dialog, + `ConfirmationModal.tsx` (used by `ImportAction.tsx`). + +## Missing + +Fixed in this pass: + +- **`how/project-structure.md` Plugin -> OLS Service table** — the `/readiness` + endpoint (polled by `ReadinessAlert`) was absent. Added a `GET /readiness` + row. + +## Structural concerns + +None. what/ vs how/ separation is clean; no behavioral rules leaked into how/ +files and vice versa. + +## Findability issues + +None. README quick-start, cross-reference, and what//how/ index tables list +every spec file that exists (7 what/, 4 how/). The `decisions/` ADR directory +is self-describing. + +## No issues (verified current) + +- `what/plugin-api.md` — console-extensions.json matches (5 extensions: flag, + context-provider, dashboards detail, redux-reducer, action/provider); + `useOpenOLS` signature matches rule 5. +- `how/state-management.md` — 27 actions in the `ActionType` enum match the + "27 actions" claim; state shape and action table match `redux-reducers.ts`. +- `how/streaming.md` event dispatch — matches the `Prompt.tsx` event chain + (start, token, end, tool_call, approval_required, tool_result, + history_compression_start/end, error, default warn) including the + `tool_meta.ui.resourceUri` / `tool_meta.olsUi.id` extraction. +- API endpoint constants across `config.ts` consumers verified against code. +- Still-accurate PLANNED items left untouched: OLS-2743 (rebrand), OLS-2700 + (agent mode), OLS-2608 / OLS-2609 (PromQL embeds), OLS-2065 (ACM policy + violations), OLS-2284 (cluster info on Nodes/Add-ons tabs) — none of these + are present in the code. + +## Deliberately NOT changed + +- `how/components.md` module map is a curated subset of the component tree + (chat/tool/attachment focus). Utility components like `ReadinessAlert`, + `WelcomeNotice`, `CopyAction`, `OverviewDetail`, etc. are intentionally + omitted there and fully listed in `how/project-structure.md`. Not drift. +- `what/tools.md` rule 15 phrasing ("uiResourceUri and serverName in its + `tool_meta`") — `serverName` actually comes from the top-level `server_name` + field, not `tool_meta`. This is a how/ detail already documented correctly in + `streaming.md`; the behavioral intent (both must be present) holds, so the + what/ rule was left as-is to avoid leaking implementation detail. diff --git a/.ai/spec/how/components.md b/.ai/spec/how/components.md index c524314e..c6960b2c 100644 --- a/.ai/spec/how/components.md +++ b/.ai/spec/how/components.md @@ -22,7 +22,7 @@ PatternFly 6 and the PatternFly AI Chatbot library. | `AttachLogModal.tsx` | Modal | Log selection for attachment | | `AttachmentsSizeAlert.tsx` | Alert | Warning for large attachments | | `ErrorBoundary.tsx` | Utility | React error boundary | -| `Modal.tsx` | Utility | Reusable modal wrapper | +| `ConfirmationModal.tsx` | Utility | Generic confirmation dialog (used by `ImportAction`) | ## Data Flow diff --git a/.ai/spec/how/project-structure.md b/.ai/spec/how/project-structure.md index 8ef499ba..ac712d0f 100644 --- a/.ai/spec/how/project-structure.md +++ b/.ai/spec/how/project-structure.md @@ -230,6 +230,7 @@ In development, `start-console.sh` configures an additional proxy from the conso | Method | Path | Purpose | |---|---|---| | POST | `/authorized` | Authorization check | +| GET | `/readiness` | Service readiness poll (drives `ReadinessAlert`); returns JSON `{ ready: boolean }` | | POST | `/v1/streaming_query` | Submit query, receive SSE stream | | GET | `/v1/feedback/status` | Check if feedback is enabled | | POST | `/v1/feedback` | Submit user feedback | diff --git a/.ai/spec/how/streaming.md b/.ai/spec/how/streaming.md index 77024743..fb911828 100644 --- a/.ai/spec/how/streaming.md +++ b/.ai/spec/how/streaming.md @@ -8,9 +8,9 @@ All stream processing logic lives in `src/components/Prompt.tsx` within the | Path | Purpose | |---|---| -| `src/components/Prompt.tsx` | Stream initiation, SSE reading, event parsing, Redux dispatch for all event types | +| `src/components/Prompt.tsx` | Stream initiation, SSE reading, event parsing, Redux dispatch for all event types. Defines the `QUERY_ENDPOINT` constant (`getApiUrl('/v1/streaming_query')`) | | `src/redux-actions.ts` | Actions dispatched during streaming: `setConversationID`, `chatHistoryUpdateByID`, `chatHistoryUpdateTool` | -| `src/config.ts` | `QUERY_ENDPOINT` constant built from `getApiUrl()` | +| `src/config.ts` | `getApiUrl(path)` helper used to build `QUERY_ENDPOINT` | | `src/error.ts` | `getFetchErrorMessage()` for error extraction | ## Data Flow diff --git a/.ai/spec/what/attachments.md b/.ai/spec/what/attachments.md index 9200a3fc..cd3f0371 100644 --- a/.ai/spec/what/attachments.md +++ b/.ai/spec/what/attachments.md @@ -144,7 +144,5 @@ sending. | Jira Key | Summary | |---|---| -| OLS-1896 | ACM: Attach ApplicationSet objects from Applications page | | OLS-2065 | ACM: Attach policy violations | -| OLS-2116 | ACM: Attach cluster info in ACM-enabled environments | | OLS-2284 | ACM: Add "Attach cluster info" option for Nodes and Add-ons tabs | diff --git a/.ai/spec/what/chat.md b/.ai/spec/what/chat.md index 4a342d95..4fd4e5f6 100644 --- a/.ai/spec/what/chat.md +++ b/.ai/spec/what/chat.md @@ -53,10 +53,11 @@ and first-time user experience. | `tool_result` | `id`, `content`, `status`, `server_name`, `structured_content`, `tool_meta` | Update tool with execution result | | `history_compression_start` | (none) | Show compression-in-progress indicator | | `history_compression_end` | `duration_ms` | Show compression-complete indicator with duration | - | `reasoning` | `reasoning` | Chain-of-thought chunk; consumed with no-op handling — payload is never rendered, logged, or passed to `console.warn` | - | `skill_selected` | `name` | Skill matched to query; consumed with no-op handling — payload is never rendered, logged, or passed to `console.warn` | | `error` | error details | Display error alert, stop streaming | + Any event type not listed above is unrecognized and logged via + `console.warn` (see `how/streaming.md`). + 9. Token updates to the UI must be throttled to prevent excessive re-renders during streaming. Updates must use trailing-edge throttling so the final token is always rendered. diff --git a/.ai/spec/what/system-overview.md b/.ai/spec/what/system-overview.md index 8754bec3..1b244494 100644 --- a/.ai/spec/what/system-overview.md +++ b/.ai/spec/what/system-overview.md @@ -65,12 +65,13 @@ product is being rebranded to "Red Hat OpenShift Intelligent Assistant." 13. A `ReadinessAlert` component is displayed in the chat content area when the OLS service is not ready or unavailable. Readiness is determined - globally (not per-response) via the `/readyz` endpoint, polled - periodically by the plugin. The alert appears when the endpoint returns - a non-2xx status or is unreachable. It disappears when a subsequent poll - returns a 2xx response (readiness restored). Request-level errors during - streaming do not control the `ReadinessAlert`; those surface as inline - alerts on the affected response entry instead. + globally (not per-response) via the `/readiness` endpoint, which returns + a JSON body with a `ready` boolean. The plugin polls the endpoint and + shows the alert while the response is not `ready` (or the request fails + or is unreachable), re-polling every 10 seconds until readiness is + reported. Once `ready` is `true` the alert is hidden. Request-level + errors during streaming do not control the `ReadinessAlert`; those + surface as inline alerts on the affected response entry instead. ### Query Modes @@ -176,10 +177,6 @@ Environment variables (development only): | Jira Key | Summary | |---|---| | OLS-2743 | Rebranding to "Red Hat OpenShift Intelligent Assistant" | -| OLS-2598 | MCP Apps support in OLS console | | OLS-2700 | Allow users to choose agent mode (PF6 only) | -| OLS-2722 | OLS Tool UI extensibility from external plugins | | OLS-2608 | Embed PromQL QueryBrowser in OLS responses | | OLS-2609 | Embed PromQL scalar values in OLS responses | -| OLS-2816 | Option to immediately submit prompt when opening OLS programmatically | -| OLS-2826 | Hide the initial prompt when opening OLS programmatically | diff --git a/.ai/spec/what/tools.md b/.ai/spec/what/tools.md index c4a68c6c..1535dd65 100644 --- a/.ai/spec/what/tools.md +++ b/.ai/spec/what/tools.md @@ -151,8 +151,6 @@ interactive MCP App UIs and OLS-native tool visualizations. ## Planned Changes -| Jira Key | Summary | -|---|---| -| OLS-2722 | OLS Tool UI extensibility from external plugins | -| OLS-2598 | MCP Apps support in OLS console | -| OLS-1556 | Display info about tools called while generating OLS response | +None currently planned. Tool call display (OLS-1556), MCP Apps support +(OLS-2598), and OLS Tool UI extensibility (OLS-2722) have all shipped and +are documented as current behavior above.