OLS-2882 Align spec structure and fix health issues

[xrajesh]

Summary

• Restructure .ai/spec/README.md with Structure table, Cross-Reference table, and standard Conventions section
• Absorb what/README.md and how/README.md into the main spec README and remove them
• Create ARCHITECTURE.md with Mermaid diagrams (system context, component architecture, data flow)
• Add ## Specs pointer to AGENTS.md
• Fix spec health issues: remove stale CloseButton.tsx/Modal.tsx refs, add missing pageContext.ts/validation.ts/CSS files to module map, remove completed tickets from Planned Changes

Test plan

• Verify all spec file links resolve correctly
• Verify Mermaid diagrams render in GitHub markdown preview
• Confirm no behavioral spec content was changed (only structural alignment)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Restructured and expanded project specification documentation with a new comprehensive architecture guide.
  • Added a spec health report tracking documentation status.
  • Updated roadmap for planned attachments features (ACM objects, policy violations, cluster info) and tools features (extensibility, MCP support, tool transparency).

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign kyoto for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request restructures and expands the project's specification and architecture documentation. The main spec README is reorganized with clearer structure tables, explicit what/how sections with cross-references, and updated conventions. A new health report tracks specification-to-implementation alignment gaps. Architecture documentation is added to project-structure specs and a comprehensive ARCHITECTURE.md is introduced. Behavioral specs receive updated planned changes tied to ACM and HITL features. Contributor guidance is enhanced across AGENTS.md and new architecture docs.

Changes

Specification and Architecture Documentation

Layer / File(s)	Summary
Specification Framework Restructuring .ai/spec/README.md	Main specification index reorganized with dedicated "Structure" section distinguishing what/ (behavioral rules) and how/ (architecture), explicit catalogs of spec files in each section, cross-reference matrix linking behavioral topics to architecture specs, and revised conventions covering rule numbering, planned-change markers, constraint placement, and criteria for creating vs extending spec files.
Specification Coverage and Health Report .ai/spec/health-report.md	New health report documenting specification-to-implementation alignment: records stale issues (outdated component references in how/project-structure.md, completed tickets still in planned changes), missing items (undocumented pageContext and validation modules, CSS assets not in spec, unit test coverage gaps), confirms comprehensive coverage of hooks, components, assets, console extensions, Redux artifacts, and streaming event types.
Architecture and Module Documentation .ai/spec/how/project-structure.md	Architecture documentation updated with new modules (src/pageContext.ts for URL/model-key resolution, src/validation.ts for alert rule ID hashing), expanded CSS asset listings (general-page, mcp-app, popover), and detailed unit test coverage documentation for pageContext and validation topics.
Behavioral Specification Planned Changes .ai/spec/what/attachments.md, .ai/spec/what/tools.md	Attachments spec planned changes replace local YAML upload task with ACM-focused features (ApplicationSet attachment, policy violation attachment, cluster info options). Tools spec planned changes replace completed HITL task with extensibility, MCP App support, and tool invocation info display items.
Architecture and Contributor Guidance ARCHITECTURE.md, AGENTS.md	New comprehensive ARCHITECTURE.md documents end-to-end plugin architecture: system context, component diagrams, SSE query lifecycle with throttled Redux updates, human-in-the-loop tool approval flow, MCP iframe postMessage JSON-RPC integration, Immutable.js state slices, proxied API surface, extension points, technology stack, and key architectural decisions. AGENTS.md updated with "Specs" section directing contributors to .ai/spec/ and .ai/spec/README.md.

🎯 2 (Simple) | ⏱️ ~10 minutes

🐰 A rabbit hops through specs with care,
Organizing docs here and there—
Health reports, architecture bright,
Cross-references set things right. ✨📚

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main objective: restructuring the spec organization and resolving documentation health issues identified in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.ai/spec/how/project-structure.md (1)

66-80: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix duplicate heading and mislabeled CSS section.

Line 74 repeats the same heading text, and Lines 70-72 list src/components/*.css under a src/assets/ heading. This makes the module map ambiguous and can trigger markdown lint noise.

Suggested doc fix

-### `src/assets/` -- Static assets
+### `src/components/` -- Component CSS assets

 | Path | Purpose |
 |---|---|
 | `src/components/general-page.css` | Styles for the GeneralPage chat interface |
 | `src/components/mcp-app.css` | Styles for MCP App card and iframe container |
 | `src/components/popover.css` | Styles for the Popover modal and floating button |

 ### `src/assets/` -- Static assets

As per coding guidelines: “All specifications live in .ai/spec/. Start with .ai/spec/README.md for project overview, reading order, and structure guide.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.ai/spec/how/project-structure.md around lines 66 - 80, The markdown has a
duplicated "src/assets/" heading and the components CSS entries are
miscategorized; change the first heading (the one above the CSS table) from
"src/assets/" to "src/components/" (or remove the duplicate and rename
accordingly), leave the second "src/assets/" section for logo/user asset rows
only, and ensure the `src/components/*.css` entries (GeneralPage, mcp-app,
popover) appear under the corrected "src/components/" heading so the module map
and linting are consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In @.ai/spec/how/project-structure.md:
- Around line 66-80: The markdown has a duplicated "src/assets/" heading and the
components CSS entries are miscategorized; change the first heading (the one
above the CSS table) from "src/assets/" to "src/components/" (or remove the
duplicate and rename accordingly), leave the second "src/assets/" section for
logo/user asset rows only, and ensure the `src/components/*.css` entries
(GeneralPage, mcp-app, popover) appear under the corrected "src/components/"
heading so the module map and linting are consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8c057fc8-6a26-4007-9886-59e5044dd735

📥 Commits

Reviewing files that changed from the base of the PR and between 136c5b9 and 25579e5.

📒 Files selected for processing (9)

• .ai/spec/README.md
• .ai/spec/health-report.md
• .ai/spec/how/README.md
• .ai/spec/how/project-structure.md
• .ai/spec/what/README.md
• .ai/spec/what/attachments.md
• .ai/spec/what/tools.md
• AGENTS.md
• ARCHITECTURE.md

💤 Files with no reviewable changes (4)

• .ai/spec/how/README.md
• .ai/spec/what/tools.md
• .ai/spec/what/attachments.md
• .ai/spec/what/README.md

[kyoto]

Seems like this file should not be part of the PR, but these details could be included in the commit message / PR description instead.