fix: enforce maxConcurrentPRs as an open-PR cap, not per-cycle

AGENTS.md

@@ -186,7 +186,7 @@ Setting `ZelyoConfig.spec.mode: protect` only flips the remediation engine's str
 Only then does the full loop fire:
 
 1. Correlator emits an incident
-2. `RemediationPolicy` controller filters open incidents by `spec.severityFilter` and caps PR submissions per reconcile cycle via `spec.maxConcurrentPRs`
+2. `RemediationPolicy` controller filters open incidents by `spec.severityFilter` and caps the number of open PRs via `spec.maxConcurrentPRs` — already-open Zelyo PRs on the target repo count against the budget, so new PRs only open when existing ones merge or close
 3. Remediation engine asks the LLM for a structured JSON fix plan and scores the risk
 4. GitHub engine creates a branch, commits the fix, and opens a PR (skipped globally when `ZelyoConfig.spec.mode: audit`, which leaves the engine in `dry-run`)
 5. Human team reviews and merges the PR

README.md

@@ -76,7 +76,7 @@ graph LR
 | Mode                          | Behavior                                                                                |
 | ----------------------------- | --------------------------------------------------------------------------------------- |
 | **Audit** *(default)* | Detects, correlates, and alerts. The remediation engine runs in `dry-run` — fix plans are logged but no PRs are opened. |
-| **Protect**             | Switches the remediation engine to the `gitops-pr` strategy. PRs are opened only when at least one `RemediationPolicy` CR points at a configured `GitOpsRepository`. The policy's `severityFilter` decides which incidents qualify, and `maxConcurrentPRs` caps submissions per reconcile cycle. |
+| **Protect**             | Switches the remediation engine to the `gitops-pr` strategy. PRs are opened only when at least one `RemediationPolicy` CR points at a configured `GitOpsRepository`. The policy's `severityFilter` decides which incidents qualify, and `maxConcurrentPRs` caps the number of open Zelyo PRs on the target repo. |
 
 > **Note:** `ZelyoConfig.spec.mode: protect` by itself does not produce any PRs — it only authorizes the pipeline. See [Enable GitOps Remediation](docs/quickstart.md#enable-gitops-remediation) for the full `GitOpsRepository` + `RemediationPolicy` setup.
 

api/v1alpha1/remediationpolicy_types.go

@@ -41,7 +41,11 @@ type RemediationPolicySpec struct {
 	// +optional
 	DryRun bool `json:"dryRun,omitempty"`
 
-	// maxConcurrentPRs limits the number of open PRs at any time.
+	// maxConcurrentPRs limits the number of open Zelyo-generated PRs on
+	// the target repo at any time. Already-open PRs count against the
+	// budget, so new PRs only open when existing ones merge or close.
+	// Current count is surfaced on status.openPRs. Multiple
+	// RemediationPolicies targeting the same repo share this budget.
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:default=5
 	// +optional

config/crd/bases/zelyo.ai_remediationpolicies.yaml

@@ -73,8 +73,12 @@ spec:
                 type: string
               maxConcurrentPRs:
                 default: 5
-                description: maxConcurrentPRs limits the number of open PRs at any
-                  time.
+                description: |-
+                  maxConcurrentPRs limits the number of open Zelyo-generated PRs on
+                  the target repo at any time. Already-open PRs count against the
+                  budget, so new PRs only open when existing ones merge or close.
+                  Current count is surfaced on status.openPRs. Multiple
+                  RemediationPolicies targeting the same repo share this budget.
                 format: int32
                 minimum: 1
                 type: integer

deploy/helm/zelyo-operator/crds/zelyo.ai_remediationpolicies.yaml

@@ -73,8 +73,12 @@ spec:
                 type: string
               maxConcurrentPRs:
                 default: 5
-                description: maxConcurrentPRs limits the number of open PRs at any
-                  time.
+                description: |-
+                  maxConcurrentPRs limits the number of open Zelyo-generated PRs on
+                  the target repo at any time. Already-open PRs count against the
+                  budget, so new PRs only open when existing ones merge or close.
+                  Current count is surfaced on status.openPRs. Multiple
+                  RemediationPolicies targeting the same repo share this budget.
                 format: int32
                 minimum: 1
                 type: integer

docs/gitops-onboarding.md

@@ -181,7 +181,7 @@ metadata:
 spec:
   gitOpsRepository: production-manifests   # must match a GitOpsRepository CR
   severityFilter: high                     # critical | high | medium | low
-  maxConcurrentPRs: 3                      # cap per reconcile cycle (not a global open-PR count)
+  maxConcurrentPRs: 3                      # cap on open Zelyo PRs in the target repo; surfaced on status.openPRs
   prTemplate:
     titlePrefix: "[Zelyo Operator]"
     labels: ["auto-fix", "security"]

docs/index.md

@@ -116,7 +116,7 @@ Aggregate views, cross-cluster correlation, and centralized policy management ac
 | Mode | When | Behavior |
 |---|---|---|
 | **:material-magnify: Audit Mode** (default) | `ZelyoConfig.spec.mode: audit` | Detects, diagnoses, and sends alerts. The remediation engine runs in `dry-run` — fix plans are logged but no PRs are opened. Zero cluster modifications. |
-| **:material-shield-check: Protect Mode** | `ZelyoConfig.spec.mode: protect` **and** at least one `RemediationPolicy` targeting a `GitOpsRepository` | Switches the remediation engine to the `gitops-pr` strategy. The `RemediationPolicy` controller drives PR creation — `severityFilter` gates which incidents qualify, `maxConcurrentPRs` caps submissions per reconcile cycle. |
+| **:material-shield-check: Protect Mode** | `ZelyoConfig.spec.mode: protect` **and** at least one `RemediationPolicy` targeting a `GitOpsRepository` | Switches the remediation engine to the `gitops-pr` strategy. The `RemediationPolicy` controller drives PR creation — `severityFilter` gates which incidents qualify, `maxConcurrentPRs` caps the number of open Zelyo PRs on the target repo. |
 
 !!! note
     `ZelyoConfig.spec.mode: protect` only flips the engine strategy from `dry-run` to `gitops-pr`. **No PRs are opened until you also create at least one `RemediationPolicy` that points at a `GitOpsRepository`.** See [GitOps Onboarding](gitops-onboarding.md) for the full setup.

docs/quickstart.md

@@ -325,7 +325,7 @@ All three pieces are required — skipping any one of them means no PRs:
 | --- | --- |
 | `ZelyoConfig.spec.mode: protect` | Flips the remediation engine from `dry-run` to `gitops-pr`. Without this, plans are logged but never submitted. |
 | `GitOpsRepository` | Tells Zelyo which repo, branch, and paths to write fixes into, and provides Git auth. |
-| `RemediationPolicy` | The only controller that calls `GeneratePlan` + `ApplyPlan`. `severityFilter` gates which incidents qualify; `maxConcurrentPRs` caps PR submissions per reconcile cycle (not a global limit on open PRs). |
+| `RemediationPolicy` | The only controller that calls `GeneratePlan` + `ApplyPlan`. `severityFilter` gates which incidents qualify; `maxConcurrentPRs` caps the number of open Zelyo PRs on the target repo — already-open PRs count against the budget, so new PRs only open when existing ones merge or close. The current count surfaces on `status.openPRs`. |
 
 **0. Switch `ZelyoConfig` to Protect mode** (`ZelyoConfig` is cluster-scoped — no `-n` flag):
 
@@ -373,7 +373,7 @@ spec:
     labels: ["security", "automated"]
     branchPrefix: "zelyo/fix-"
   severityFilter: high
-  maxConcurrentPRs: 3   # per reconcile cycle
+  maxConcurrentPRs: 3   # caps total open Zelyo PRs on the target repo
   dryRun: false
   autoMerge: false
 ```