docs(agents): state the base/overlay rule by scope, not as immutability - #3026
Merged
Conversation
"Base files are immutable" is contradicted by the repository itself:
k8s/bases/ changes in ~148 of the last 300 commits, and 92% of those
commits touch a base and no overlay at all. The operative content was
the trailing qualifier -- do not edit a base *from an overlay* -- but an
absolute bolded headline overwhelmed it, so the rule either blocked
legitimate all-cluster changes or was discarded wholesale on contact
with the log.
Restate it as the decision it actually is: the layer follows the scope
of the change. Also remove the degraded restatement ("bases immutable",
qualifier dropped) that had been appended to a secrets-compromise
bullet, where nobody looks for layering guidance; Flux ordering and the
manifest-structure pointer are already stated canonically elsewhere.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
Author
@coderabbitai review |
Contributor
|
|
Contributor
|
Warning Review limit reached
Next review available in: 19 seconds You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
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. Comment |
Contributor
Author
CodeRabbit (lane 1) could not serve this head: free OSS review limit reached, next review in ~39 minutes. Advancing to Codex per lane priority rather than parking a finished change on a provider quota. @codex review |
Contributor
✅
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5658989e34
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The 'every cluster and provider' test misfires on this repo's layout: the local Docker overlay opts IN to apps and heavier infrastructure, so much of k8s/bases/ has a single consumer today by design (bases/apps/ is consumed by hetzner alone). Under that test an agent would patch a shared app's canonical config into the one provider using it, leaving the base stale for whoever opts in next. Scope by consumer of the resource instead. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
devantler
added a commit
to devantler-tech/platform-template
that referenced
this pull request
Aug 8, 2026
Mirrors devantler-tech/platform#3026. A base with one consumer today still holds the canonical configuration; the 'every cluster' test would push it into that overlay and leave the base stale. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
Author
Readiness — how this was exercised. A prose rule has no runtime surface to execute, so it was evaluated the way its user (an agent deciding where a change belongs) would apply it: run the rule against real changes and check it returns the right layer.
Cross-checked that nothing was orphaned: Flux dependency order and the manifest-structure pointer are still stated canonically (Conventions, and the CI green, |
Contributor
Author
Codex finding at the previous head is fixed and its thread resolved; restarting the review loop at CodeRabbit per lane priority, now that its OSS limit has reset. @coderabbitai review |
Contributor
🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo '--- PR metadata ---'
gh pr view 3026 --repo devantler-tech/platform --json number,title,baseRefName,headRefName,headRefOid,mergeStateStatus,changedFiles --jq '{number,title,baseRefName,headRefName,headRefOid,mergeStateStatus,changedFiles}'
echo '--- Changed files ---'
git diff --name-status "$(git merge-base HEAD origin/HEAD)" HEAD 2>/dev/null || git diff --name-status HEAD~1 HEAD
echo '--- Current diff ---'
git diff --find-renames "$(git merge-base HEAD origin/HEAD)" HEAD 2>/dev/null || git diff --find-renames HEAD~1 HEAD
echo '--- Documentation files with base/overlay terminology ---'
rg -n -i -C 4 'base files|base.*overlay|overlay.*base|every cluster|one (cluster|provider)|scope of (the )?change|manifest.structure|flux.*depend' -g '*.md' .Length of output: 30318
I found no actionable issues. The revised rule correctly selects the base or overlay from the intended consumer scope. It also preserves the per-overlay safety constraint and removes the degraded duplicate text.
|
Contributor
Author
Previous attempt was refused with @coderabbitai review |
Contributor
|
Your plan includes PR reviews subject to rate limits. Reviews are available now. |
devantler
added a commit
to devantler-tech/platform-template
that referenced
this pull request
Aug 8, 2026
…ty (#130) * docs(agents): state the base/overlay rule by scope, not as immutability Mirrors devantler-tech/platform#3026. The same rule is stated twice here and contradicts itself in both places: "Base files are **immutable** from overlays" carries the qualifier, then the very next clause drops it ("never by editing k8s/bases/ directly"), and the Maintenance copy keeps only the absolute ("bases immutable"). In the upstream platform repo the directory this declares immutable changes in ~half of all commits, 92% of them touching a base and no overlay at all. State the decision it actually is -- the layer follows the scope of the change -- and replace the misfiled duplicate with a pointer, so there is one canonical statement that cannot drift again. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(agents): scope base changes by consumer, not by every cluster Mirrors devantler-tech/platform#3026. A base with one consumer today still holds the canonical configuration; the 'every cluster' test would push it into that overlay and leave the base stale. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Contributor
Author
CodeRabbit refused this head twice — @codex review |
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Contributor
Author
Readiness — all three conditions hold at
The evidence for that judgement is first-hand and recent: on platform#3025 a reviewer flagged a The identical change merged in platform-template#130 at No issue linkage, deliberately — this propagates a maintainer ruling from review rather than closing a tracked defect, so |
Contributor
Author
CodeRabbit completed at this head without a gate-satisfying artifact: zero review objects, newest summary still carrying a rate-limit marker, and the head's CodeRabbit status back to @codex review |
|
Codex Review: Didn't find any major issues. 🚀 Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The convention
**Base files are immutable**is a common source of agent confusion, and the reason is that it is not true.k8s/bases/changes in roughly half of all commits — and 92% of those commits change a base and no overlay at all. Editing a base is the ordinary way work happens here.That produces two failures, in opposite directions. An agent that believes the rule will not make a legitimate change that should reach every cluster, so it either stalls or duplicates the change as several per-overlay patches — causing the drift bases exist to prevent. An agent that checks the log sees the rule is contradicted and discards the whole bullet, losing the part that is real: do not reach back and mutate a shared base to get a one-overlay effect.
The genuine rule was always there, as an unbolded trailing clause ("from a provider or cluster overlay"). It just lost to the headline.
What
States the rule as the decision it actually is — the layer follows the scope of the change: the base when it must reach every cluster and provider, an overlay patch when it must reach one. Keeps the real constraint, with the reason attached, and adds a one-question test.
Also removes a second, degraded copy of the rule that had been appended to a secrets-compromise bullet with its qualifier dropped entirely. Flux ordering and the pointer to the manifest-structure sections are already stated canonically elsewhere, so nothing is lost — and one canonical statement is what stops this drifting again.
No enforcement change: whether a base edit was meant to reach everyone is a judgement CI cannot make, so prose accuracy is the whole control surface here.