This folder is organized by topic, which is a deliberate exception to the rule in
../INDEX.md that the other folders are picked by lifecycle. The layout question
(given a live object, which file in which folder receives it, and what else has to change so that
file is reachable) was spread across spec/ and design/, and following the argument meant knowing
which of the two a given piece lived in.
Lifecycle still decides whether a page binds, so each entry is labelled with the class it would have had in the old layout. Read the label before you read the page.
| Document | Class | What it holds |
|---|---|---|
new-file-placement-rules.md |
spec | where a brand-new resource's file goes: declared, the folder's one kustomize root, canonical. Go source cites it by path, and task lint-docs checks those citations |
contextual-namespace.md |
spec | kustomize graph-aware namespace inference, and the supported subset. This is the inference serializeNamespace overrides |
model.md |
built | the proposal, reversed and much smaller, and now shipped: the path template stays, and gained two optional booleans — spec.placement.useKustomize, and spec.serializeNamespace one level up because it governs every write rather than only new files. Carries the status stanza, the post-scan pass, the order the work was built in, and the four questions it deliberately left open |
The shapes and the ecosystem examples used to sit here as two subfolders. They now live at
test/fixtures/layout-corpus/, because they stopped
being illustrations: every one of them is seeded, written through the real plan-then-flush path and
diffed against a committed patch by TestLayoutCorpus. A folder that a test executes belongs beside
the other fixtures a test executes, and the move also puts it next to
test/fixtures/gitops-layouts/, the corpus it is
most often confused with. The README there says which is which.
Their prose travelled with them, so the corpus is still where a layout question is answered:
| Folder | Answers |
|---|---|
shapes/ |
the cross-product. Flat and tree, each with and without metadata.namespace in the document, plus one kustomize folder, base-and-overlays, and layered, with the same live object written into all of them. Carries the decision flow as a diagram, an empty-folder column for every shape, and the measured behavior of the deployers that consume them |
specific-examples/ |
the remainder: an Argo CD app-of-apps and a Flux two-layer repository, which are ecosystem scenarios rather than folder shapes, plus the shared GitProvider prerequisites |
What stays in this folder is the argument: the two contracts the code cites by path, and the model that produced them. What moved is the evidence.
../design/gittarget-api-wave.mdsequenced the breaking work onGitTarget, which shipped in #330. The placement work was additive and was never part of it.../design/placement-visibility-and-declared-defaults.mdholds the three questions the sibling-inference deletion left. Decided;status.placementhas since shipped and the rest is unbuilt. Its Question 2 (a CRD default forplacement.default) is reopened bymodel.md's reversal, not superseded by it.../design/support-boundary/owns what the operator may edit and what it refuses. Layout decides where a document goes; the support boundary decides whether it may be written at all.