OLS-3018 Add kill switch spec for AgenticOLSConfig CR

[thoraxe]

Summary

• Adds .ai/spec/what/system-config.md specifying the new AgenticOLSConfig cluster-scoped singleton with spec.suspended kill switch
• Introduces EmergencyStopped terminal phase for proposals terminated by the kill switch
• Specifies console banner and CLI oc agentic suspend/resume commands
• Updates existing specs (crd-api, proposal-lifecycle, sandbox-execution, reconciler) to integrate the new condition type and phase

Details

This is a spec-only change — no code changes. The spec defines behavioral rules for:

• AgenticOLSConfig CRD (cluster-scoped singleton, spec.suspended bool)
• Emergency termination of in-flight proposals (sandbox pod cleanup, RBAC cleanup, EmergencyStopped condition)
• Reconciler integration via early-return guard and AgenticOLSConfig watch
• Console danger banner when system is suspended
• CLI status reporting and suspend/resume commands

Test plan

• Review spec consistency across all modified files
• Verify EmergencyStopped is correctly added to DerivePhase precedence in proposal-lifecycle.md
• Verify cross-references between system-config.md and other specs are correct

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added an emergency system kill switch to suspend all operations and terminate in-flight proposals.
  • Added console and CLI support for managing the kill switch with suspend/resume commands and status visibility.

• Documentation

  • Added system configuration specification for the kill-switch behavior and integration across the platform.

[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 xrajesh 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 documentation-only PR introduces a cluster-scoped AgenticOLSConfig CRD with an emergency suspension kill switch. The PR adds a comprehensive specification document, updates existing architecture and API specifications with new EmergencyStopped condition and phase semantics, specifies reconciler watch and termination logic, and documents console/CLI visibility requirements.

Changes

Kill Switch System Configuration and Implementation Spec

Layer / File(s)	Summary
Kill Switch Behavioral Specification .ai/spec/what/system-config.md	New document defines AgenticOLSConfig singleton contract, spec.suspended emergency semantics (immediate step blocking, best-effort proposal termination with EmergencyStopped condition), reconciler watch/re-queue/guard ordering, termination step sequencing, console danger banner and distinct proposal rendering, CLI status/suspend/resume commands with confirmation prompt, implementation equivalence constraints, and future batch-sweep alternative.
AgenticOLSConfig CRD and Proposal API Updates .ai/spec/what/crd-api.md	Updated behavioral rules to treat AgenticOLSConfig as cluster-scoped resource, extended Proposal.status.conditions to include new EmergencyStopped condition type, added EmergencyStopped to ProposalPhase terminal display values, specified AgenticOLSConfig CRD with singleton naming via metadata.name=cluster and spec.suspended kill-switch boolean, documented configuration surface, and added OLS-3018 planned change tracking.
Proposal Phase Derivation with EmergencyStopped .ai/spec/what/proposal-lifecycle.md, .ai/spec/what/sandbox-execution.md	proposal-lifecycle.md introduces EmergencyStopped as highest-precedence terminal phase in DerivePhase (checked before Escalated or Denied), defines phase precedence rules and included it in terminal-phase set and valid condition types; sandbox-execution.md expands sandbox release rule to include EmergencyStopped in termination sequence.
Reconciler Watch and Suspension Guard Architecture .ai/spec/how/reconciler.md	Updated "Data flow: reconcile loop" to document SetupWithManager watching AgenticOLSConfig and enqueuing all non-terminal Proposal resources on config changes, added suspension guard that checks spec.suspended=true, releases sandboxes, cleans RBAC, sets EmergencyStopped condition, patches status and returns early; added note clarifying suspension guard effect on re-queued proposals.
Documentation Index and Tracking .ai/spec/README.md, .ai/spec/what/README.md	README.md adds Quick Start entry linking to system-config.md and updates Project Context Jira tracking with Kill Switch [OLS-3018](https://redhat.atlassian.net/browse/OLS-3018); what/README.md adds system-config.md to Spec Index table with kill-switch and visibility scope description.

---

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 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 pull request title clearly and specifically describes the main change: introducing a kill switch specification for the AgenticOLSConfig custom resource (OLS-3018), which aligns with the core objective of 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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[thoraxe]

Updated with deployment model and image publishing sections:

• Deployment Model (rules 1-3): Documents that the agentic controller is deployed via the lightspeed-operator OLM bundle, is inert without its CRs, and deploys its own console plugin
• Image Publishing (rules 4-5): Requires Konflux pipeline for the agentic controller image
• Updated affected repositories to include lightspeed-operator
• Renumbered all rules for continuous numbering (1-27)

Companion PR: openshift/lightspeed-operator#1667

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

.ai/spec/what/system-config.md (1)

78-78: ⚡ Quick win

Clarify "Approach A" terminology.

The constraint references "Approach A (reconciler re-queue)" and "Approach B" in line 82, but the document never explicitly labels the reconciler-based termination as "Approach A" in the behavioral rules. Consider adding a brief parenthetical in rule 17 or adding an explicit label when first describing the reconciler watch pattern to improve cross-reference clarity.

🤖 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/what/system-config.md at line 78, The doc uses "Approach A
(reconciler re-queue)" and "Approach B" but never explicitly labels the
reconciler-based termination as "Approach A" in the behavioral rules; update the
text to add a short parenthetical label when the reconciler watch pattern is
first described (e.g., in rule 17 or where the reconciler watch behavior for
AgenticOLSConfig is introduced) so cross-references to "Approach A" and
"Approach B" are unambiguous.

🤖 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.

Nitpick comments:
In @.ai/spec/what/system-config.md:
- Line 78: The doc uses "Approach A (reconciler re-queue)" and "Approach B" but
never explicitly labels the reconciler-based termination as "Approach A" in the
behavioral rules; update the text to add a short parenthetical label when the
reconciler watch pattern is first described (e.g., in rule 17 or where the
reconciler watch behavior for AgenticOLSConfig is introduced) so
cross-references to "Approach A" and "Approach B" are unambiguous.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9e12938b-6378-4796-afd9-e9751c2ca1a6

📥 Commits

Reviewing files that changed from the base of the PR and between 44bd61b and fa26fea.

📒 Files selected for processing (7)

• .ai/spec/README.md
• .ai/spec/how/reconciler.md
• .ai/spec/what/README.md
• .ai/spec/what/crd-api.md
• .ai/spec/what/proposal-lifecycle.md
• .ai/spec/what/sandbox-execution.md
• .ai/spec/what/system-config.md