docs(agents): state the base/overlay rule by scope, not as immutability

[devantler]

🤖 Generated by the Agentic Engineer

Why

This template is the starter every new platform is created from, so a confusing convention here propagates to each one. It states the base/overlay rule twice, and contradicts itself both times: Base files are **immutable** from overlays carries the qualifier that makes the rule true, then the next clause drops it (never by editing k8s/bases/ directly), and the Maintenance copy keeps only the absolute (bases immutable).

The absolute is not true. In the upstream platform repo, k8s/bases/ changes in about half of all commits — and 92% of those change a base and no overlay at all. Editing a base is the ordinary way work happens. An agent that believes the absolute will not make a legitimate change meant to reach every cluster; one that checks it discards the rule entirely, losing the part that is real.

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 genuine constraint with its reason attached.

Replaces the misfiled second copy (appended to a protected-files clause) with a pointer to the canonical statement, so the two cannot drift apart again.

Pairs with devantler-tech/platform#3026.

[devantler]

🤖 Generated by the Agentic Engineer

Readiness — how this was exercised.

Same evaluation as the paired devantler-tech/platform#3026: the rule was applied to real changes to check it returns the correct layer, rather than merely reading well.

The evidence is drawn from the upstream platform repo this template seeds — k8s/bases/ changes in ~half of all commits, 92% of them touching a base and no overlay — because the template itself has no comparable manifest history of its own. The consumer-scoped wording is what survives that test; an "every cluster" test does not, since a base legitimately has one consumer until another overlay adopts it.

Verified nothing was orphaned by removing the misfiled duplicate: manifest layering and Flux dependency order are both stated under Kustomization flow, which the replacement text now points to.

CI green, mergeStateStatus: CLEAN. Awaiting a current-head review before promotion.

[devantler]

🤖 Generated by the Agentic Engineer

@coderabbitai review

[coderabbitai]

@devantler I will review the current pull request head.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated AGENTS.md to distinguish shared canonical configuration from per-consumer differences in Kustomize bases and overlays. Removed duplicated guidance about immutable bases and Flux ordering from maintenance validation. Retained references to the Kustomization flow section and protected files.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description check	✅ Passed	The description clearly explains the documentation changes and their purpose.
Title check	✅ Passed	The title clearly summarizes the main change to define the base and overlay rule by scope.

---

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

[devantler]

🤖 Generated by the Agentic Engineer

Readiness — all three conditions hold at c28a4b04f3.

1. Programmatically tested — 16/16 checks green, mergeStateStatus: CLEAN, no unresolved threads, no non-thread findings.
2. Reviewed — CodeRabbit green at this exact head: substantive auto-generated summary at 22:13:09Z naming c28a4b04f35ec38efa7c3f075001a95e44d36339, "No actionable comments were generated in the recent review", no rate-limit or service marker, corroborated by the head's CodeRabbit status reading Review completed.
3. Tried and evaluated as a user — this is a pure documentation change to an instruction file, so it has no exercisable runtime surface; per the readiness rule I am stating that explicitly rather than implying I ran something. I evaluated it as its actual reader — an agent applying the rule to a manifest change.

That evaluation is first-hand rather than hypothetical. The rule this replaces produced a live wrong call yesterday: on platform#3025 a reviewer flagged a k8s/bases/ edit as violating "bases are immutable", and the maintainer refuted it — using the base was correct, because the change had to hit every overlay. The old wording admitted no such case, so anyone following it literally would have moved a shared default into one overlay and left the base stale for the next adopter. The new wording answers that question directly: edit the base when the change should hold for every consumer of the resource, patch only for a genuine per-consumer difference, and note that "every consumer" is not "every cluster".

No issue linkage, deliberately. This propagates a maintainer ruling made in review rather than closing a tracked defect, and there is no acceptance criteria set it could satisfy — so Fixes would close something it does not complete. Branch history carries no closing keyword either, so the squash commit cannot close an issue by accident.

[devantler]

🤖 Generated by the Agentic Engineer

CodeRabbit ran at this head (status Review completed, substantive walkthrough, no findings, no rate-limit marker) but posted zero review objects and its summary names no commit, so nothing binds that result to this head. Recording it as a completed no-gate outcome rather than treating an unbindable pass as a green, and advancing to Codex.

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: dd13531c54

ℹ️ 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".