kubernetes_template_rendering 0.2.5 → 0.6.0.prerelease.tstarck.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd614cd6cfbb3820cce568dea5609c10e3b76a468345673a69214f0faf1a54a5
-  data.tar.gz: f9978c3776825effd13efeec919a3a25128f2cecdb0ed28545d69433de2f47a4
+  metadata.gz: 1306190d836dbde84a594aee2b814d7db1238f0863f4fd8a9c0ccea2979a46b3
+  data.tar.gz: dbae4fa4255214b4029227ad9e3bc48f73de0ba248f03cba7d584bfbdebc0dd1
 SHA512:
-  metadata.gz: dca99566a866d75db291d679f5b4f700e23e254b2a869d93868345cf74c70c5a929f9d26195f20bf3f8b4693ded530fa46868578c87c9549a7db41b71cdd046d
-  data.tar.gz: 9db31d09d52f310b8f1794218732d98a5ab5dd603028d4030d53f87da00a4be2bdb393ece991cf22a1374856f13add18ed4e3adb578302e590d40f021b14a3a5
+  metadata.gz: 85fbba190072912153255c4e06af9c3562613318d6c7cc0f14bf4e9d7f574015d2741bf17a85d3080d4f89c3cfdaf818d7d86e7c07c84d8294f764a370938864
+  data.tar.gz: ff0c9c764b719631f4fa250d0fb948203d2b1d57016de81aee53ae2c5febabf9e2f2266ce6d703a8c01f356993d77d143f2edd9f2d13d12e492829eee3c31fed

data/CHANGELOG.md

@@ -4,6 +4,30 @@ Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 Note: this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - Unreleased
+### Added
+- Added `--reconcile` flag: a bounded, marker-based sweep that replaces the destructive per-entry `rm -rf` of `--prune`. It touches a marker before rendering, then after rendering deletes only files older than the marker under each scope root (`<region>/<cluster_type>/<color>/`) and removes empty directories, correctly cleaning up directories of deleted/renamed entries. `spp/` subtrees are fenced out of the base sweep, paths resolving outside their scope prefix raise a hard error, and `--reconcile` combined with `--prune` is rejected.
+- Made `--reconcile` `--spp`-aware: without `--spp` only the `SPP-PLACEHOLDER` subtree is swept; with `--spp NAME` the sweep covers `SPP-PLACEHOLDER` (always re-rendered, as the expansion source) plus each requested per-SPP subtree (substituting `SPP-PLACEHOLDER` into the sweep root), leaving unrequested SPP siblings intact. Rejected `--reconcile` combined with `--only`, which would delete un-rendered siblings under the shared base root. See ADR-0002.
+- Added a `--reconcile` SPP layout guard: SPP entries (name contains `SPP-PLACEHOLDER`) must render under `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER/`, and non-SPP entries must not render under any `spp/` segment. A `directory:` override that still resolves to the canonical SPP prefix is allowed; anything else hard-errors before rendering. The guard runs only under `--reconcile`. See ADR-0002.
+
+## [0.5.0] - 2026-06-26
+### Added
+- Added `--spp NAME` (repeatable) flag that expands rendered output of `SPP-PLACEHOLDER` entries into per-Staging-Partial-Platform sibling directories, substituting `SPP-PLACEHOLDER` and its `PLACEHOLDER` suffix in both paths and contents. Composes with the SPP-derived base path introduced in 0.4.0 (sibling per-SPP trees are created next to the literal `SPP-PLACEHOLDER` segment). Replaces the post-render `invocaops_docker/tools/spp-transform/spp-transform.rb` step inside the gem.
+- Added `--only NAME` (repeatable) flag that filters rendering to specific top-level `definitions.yaml` entries by exact key match. Composes with `--cluster_type`/`--region`/`--color`/`--spp` (all filters are AND'd). Raises with a list of valid keys if any `--only` value matches no entry across the rendered template directories.
+
+## [0.4.0] - 2026-06-25
+### Added
+- Added a `subdirectory:` option to `definitions.yaml`. It is mutually exclusive with `directory:` and sets the output path to the base path `%{plain_region}/%{type}/%{color}/<subdirectory>`. When neither `directory:` nor `subdirectory:` is given, output is rendered to the base path `%{plain_region}/%{type}/%{color}` (previously a missing `directory:` raised an error).
+- Emit a deprecation warning on any use of `directory:` in `definitions.yaml`, suggesting to remove it (to render into the standard `%{plain_region}/%{type}/%{color}` layout) or switch to `subdirectory:`. `directory:` is the only way to produce a non-standard path, which is unsafe for the planned `--reconcile` stale-resource deletion. See ADR-0001.
+- SPP definitions (those whose name contains the `SPP-PLACEHOLDER` token) now render under a derived base path `%{plain_region}/%{type}/%{color}/spp/SPP-PLACEHOLDER`, with `subdirectory:` composing on top. This keeps each SPP instance's output distinct and bounded under the `region/type/color` tree for `--reconcile`, and preserves the literal `SPP-PLACEHOLDER` token for downstream per-instance substitution. The `directory:` deprecation warning now points SPP definitions at the SPP base layout. See ADR-0001.
+
+## [0.3.0] - 2026-06-24
+### Fixed
+- Ruby 4.0 compatibility: declare `ostruct` as a dependency (it is `require`d directly but was removed from Ruby's default gems in 4.0.0) and bump `activesupport` to `7.2.3.1` so its `logger` dependency is resolved (`logger` was likewise dropped from default gems).
+
+### Removed
+- No longer emit the `# Variable overrides used:` comment in rendered files. Because overrides such as `deploySha` change on every build, this comment caused large, content-free diffs across every rendered file. `--variable-override` still applies the overrides to the rendered output; only the comment is removed.
+
 ## [0.2.5] - 2025-05-08
 ### Fixed
 - Updated `rexml` dependency to avoid security issues

data/README.md

@@ -7,12 +7,14 @@ configuration for various deployment environments.
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
-```
+
+```bash
 bundle add kubernetes_template_rendering
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
-```
+
+```bash
 gem install kubernetes_template_rendering
 ```
 
@@ -23,20 +25,66 @@ To use this gem you can either install it, and use the `render_kubernetes_templa
 `gem exec` to execute the command without first installing the gem.
 
 ### Example Usage
+
 ```bash
 gem exec -g kubernetes_template_rendering render_templates \
     --jsonnet-library-path deployment/vendor \
-    --rendered_directory path/to/resources \
+    --rendered-directory path/to/resources \
     deployment/templates
 ```
 
 ### Options
 
 To see a full list of options and how to use them, run the following command:
+
 ```bash
 gem exec -g kubernetes_template_rendering render_templates --help
 ```
 
+### Cleaning up stale output: `--prune` vs `--reconcile`
+
+Both flags remove output left over from templates/entries that no longer render, but they differ in how:
+
+- `--prune` deletes each entry's output directory with `rm -rf` **before** rendering. It never removes the directories of fully deleted/renamed entries and can clobber sibling directories when one entry renders at a prefix root above another.
+- `--reconcile` performs a safer, bounded sweep: it touches a marker, renders, then deletes only files older than the marker under each scope root `<region>/<cluster_type>/<color>/` (honoring `--cluster_type` / `--region` / `--color`), and finally removes any now-empty directories. This cleans up directories of deleted/renamed entries without clobbering freshly-rendered siblings, and two identical reconcile runs produce the same result.
+
+Notes:
+
+- `--reconcile` and `--prune` are mutually exclusive (passing both exits with an error). `--reconcile` and `--only` are likewise mutually exclusive, since a filtered render would leave un-rendered siblings looking stale under the shared base root.
+- `spp/` subtrees are fenced out of the base sweep. Without `--spp`, only the `SPP-PLACEHOLDER` subtree is swept. With `--spp NAME`, reconcile sweeps `SPP-PLACEHOLDER` (always re-rendered, as the expansion source) plus each requested per-SPP subtree, leaving unrequested SPP siblings intact. Deleted-SPP cleanup for unrequested siblings remains a manual `git rm` in the teardown runbook. See ADR-0002.
+- If any rendered entry resolves to a path outside its scope prefix (a full-path or relative `..` escape), reconcile hard-errors before deleting anything.
+- Reconcile enforces the SPP layout: every SPP entry (name contains `SPP-PLACEHOLDER`) must render under `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER/`, and no non-SPP entry may render under an `spp/` segment. A `directory:` override that still resolves to that prefix is allowed; anything else hard-errors before rendering. (This guard runs only under `--reconcile`.) See ADR-0002.
+
+### Filtering to specific entries
+
+Pass `--only NAME` (repeatable) to render only the `definitions.yaml` entries whose top-level key exactly matches `NAME`. Composes with `--cluster_type`/`--region`/`--color`/`--spp` — all filters are AND'd.
+
+```bash
+gem exec -g kubernetes_template_rendering render_templates \
+    --rendered-directory path/to/resources \
+    --cluster_type staging \
+    --only staging.test \
+    deployment/templates
+```
+
+Useful when one `--cluster_type` matches multiple sibling entries (e.g. `staging` and `staging.test` both match `--cluster_type staging` after the suffix-strip rule) and you want to render only one of them. Repeated `--only` values are deduped.
+
+If an `--only` value matches no entry across any template directory, the gem raises with the list of valid keys so the caller can self-correct.
+
+### Staging Partial Platforms
+
+Pass `--spp NAME` (repeatable) to expand any entry whose `definitions.yaml` name contains `SPP-PLACEHOLDER` into a per-SPP sibling output. Substitutes `SPP-PLACEHOLDER` with `NAME` and the `PLACEHOLDER` suffix with the suffix of `NAME` (everything after the last `-`), in both file paths and contents. Source mtimes are preserved.
+
+```bash
+gem exec -g kubernetes_template_rendering render_templates \
+    --rendered-directory path/to/resources \
+    --spp staging-qa02a \
+    --spp staging-qa08a \
+    deployment/templates
+```
+
+This is purely additive — the placeholder-bearing output tree is still produced, and per-SPP trees are written alongside it. Repeated `--spp` values are deduped.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -45,4 +93,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/invoca/kubernetes_template_rendering.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/invoca/kubernetes_template_rendering>.

data/docs/adrs/0001-strict-rendering-paths-for-stale-resource-deletion.md

@@ -0,0 +1,98 @@
+# Strict, derived output paths so stale rendered resources can be safely reconciled
+
+* Status: accepted
+* Deciders: Tristan Starck, Kubernetes platform reviewers (via PR #17)
+* Date: 2026-06-25
+
+Technical Story: OCTO-849 — add a `subdirectory` option to `definitions.yaml` / [PR #17](https://github.com/Invoca/kubernetes_template_rendering/pull/17)
+
+## Context and Problem Statement
+
+The renderer writes Kubernetes manifests into a `rendered_directory`. We want it to remove *stale* resources — those that are no longer rendered — so the rendered tree always matches the current templates. The current `--prune` flag does this bluntly: it `rm_rf`s an output directory before re-rendering. That is destructive (it deletes everything, then re-creates whatever is still rendered) and is only as safe as the output path is correct — a wrong or tree-escaping path means deleting the wrong files.
+
+We are moving to a `--reconcile` flag instead: after rendering the desired set of resources, reconcile compares the rendered output tree against that desired set and deletes only the entries that are no longer rendered. Reconciliation is only safe and correct if the renderer knows exactly which paths it owns and can enumerate the complete desired set within a bounded tree.
+
+Today the output location of each resource set is a freeform `directory:` pattern in `definitions.yaml` that can point anywhere, including escaping the rendered tree via `..` (e.g. `../some-cluster/...`). When output paths are arbitrary, the set of directories the renderer owns is not well-defined, so reconcile cannot safely decide what is stale. How do we make rendering deterministic enough to reconcile reliably — deleting resources that are no longer rendered, and nothing else?
+
+## Decision Drivers
+
+* **Safe reconciliation of stale resources** — the core motivation: `--reconcile` must delete only resources the renderer owns and no longer renders.
+* **Deterministic, bounded output paths** — output must be predictable and rooted inside the rendered tree, never escaping it, so the owned set is enumerable.
+* **Lower boilerplate** — the `%{plain_region}/%{type}/%{color}` prefix is repeated in nearly every definition.
+* **Backward compatibility** — existing `definitions.yaml` files that use `directory:` must keep working.
+* **Hard to misuse** — the common case should require the least configuration and offer the fewest footguns.
+
+## Considered Options
+
+* **Option 1 — Strict, derived paths.** Output is always `%{plain_region}/%{type}/%{color}[/<subdirectory>]`. Introduce a `subdirectory:` field, make the prefix the default, and deprecate/restrict the freeform `directory:` field.
+* **Option 2 — Keep freeform `directory:` only.** Status quo; document conventions but enforce nothing.
+* **Option 3 — Freeform `directory:` plus a rendered-path manifest.** Keep arbitrary layouts but emit an out-of-band manifest of rendered paths that `--reconcile` consults.
+
+## Decision Outcome
+
+Chosen option: **Option 1 — strict, derived output paths.**
+
+Rendered output paths MUST be derived from `plain_region`, the kubernetes cluster type (`type`), and `color`. The output directory of a resource set is resolved from the mutually-exclusive `directory:` and `subdirectory:` fields:
+
+| Config present | Resulting output-directory pattern |
+|---|---|
+| `directory` only | the `directory` value, verbatim (legacy / escape hatch) |
+| `subdirectory` only | `%{plain_region}/%{type}/%{color}/<subdirectory>` |
+| `subdirectory` only, SPP definition | `%{plain_region}/%{type}/%{color}/spp/SPP-PLACEHOLDER/<subdirectory>` |
+| neither, SPP definition | `%{plain_region}/%{type}/%{color}/spp/SPP-PLACEHOLDER` |
+| neither | `%{plain_region}/%{type}/%{color}` (base path) |
+| both | error (`ArgumentError`) |
+
+`subdirectory:` is a plain literal final segment appended to the base path — no `%{...}` interpolation is performed on the value itself. The resolved pattern still flows through the existing per-region/color `format(...)` step, so e.g. `subdirectory: my-app` with region `us-east-1`, cluster type `prod`, and color `orange` renders into `us-east-1/prod/orange/my-app`. When neither field is given, output goes to the base path (previously a missing `directory:` raised an error).
+
+Definitions whose name contains the `SPP-PLACEHOLDER` token (the same token from
+which the `staging` cluster type is derived) render under an additional
+`spp/SPP-PLACEHOLDER` segment: their base path is
+`%{plain_region}/%{type}/%{color}/spp/SPP-PLACEHOLDER`, and `subdirectory:` composes
+on top of it. The `spp/SPP-PLACEHOLDER` segment is literal (not substituted by
+`format`), so the token survives into the rendered tree for downstream per-instance
+substitution while remaining bounded under the `region/type/color` tree. The
+warn-only-then-reject rollout for non-conforming `directory:` applies equally to SPP
+definitions.
+
+Because the base-path and `subdirectory` outputs are deterministic and rooted under the `region/type/color` tree, the renderer owns a predictable, enumerable set of directories. That is the property that lets `--reconcile` compute the desired set, diff it against what is on disk, and delete only the stale entries — safely and without escaping the tree.
+
+Additionally, the freeform `directory:` field is **deprecated**. It remains supported for backward compatibility, but it is the only way to produce a non-conforming (or tree-escaping) path, so new definitions should use `subdirectory:` or the base-path default. As a first step, the renderer now **warns on any use of `directory:`**, suggesting authors remove it (to render into the standard `%{plain_region}/%{type}/%{color}` layout) or switch to `subdirectory:`. A subsequent follow-up will upgrade this to hard validation/removal so that legacy usage cannot break reconcile safety. **(Rejection not yet enforced — currently warn-only.)**
+
+### Positive Consequences
+
+* `--reconcile` can safely delete stale resources because the renderer's output directories are deterministic and bounded.
+* Less boilerplate — the common `region/type/color` prefix is supplied automatically.
+* The misconfiguration surface shrinks over time as `directory:` usage is retired.
+
+### Negative Consequences
+
+* **Behavior change:** a missing `directory:` no longer raises; it now renders to the base path. The previous "missing `directory:`" error is gone.
+* Use of `directory:` is currently only a warning, not an error, so until the follow-up hard validation lands the reconcile-safety guarantee is not yet airtight.
+* Deprecating `directory:` requires migrating existing definitions over time.
+
+## Pros and Cons of the Options
+
+### Option 1 — Strict, derived paths (chosen)
+
+* Good, because deterministic, bounded paths make `--reconcile` / stale-resource deletion safe.
+* Good, because it removes the repeated `region/type/color` prefix boilerplate.
+* Good, because it is backward compatible — `directory:` still works while we steer toward strict paths.
+* Bad, because the full guarantee is deferred until `directory:` is validated/retired.
+
+### Option 2 — Keep freeform `directory:` only
+
+* Good, because no migration is required and layouts stay maximally flexible.
+* Bad, because output ownership is undefined, so reconcile cannot safely decide what is stale.
+* Bad, because patterns can escape the rendered tree via `..`.
+
+### Option 3 — Freeform `directory:` plus a rendered-path manifest
+
+* Good, because it decouples reconcile from path layout and could track arbitrary layouts.
+* Bad, because it adds a stateful artifact to generate, store, and trust.
+* Bad, because it is more moving parts than simply enforcing a deterministic layout.
+
+## Links
+
+* Implemented by [PR #17](https://github.com/Invoca/kubernetes_template_rendering/pull/17) (OCTO-849) — `subdirectory:` field, base-path default, `ResourceSet` directory resolution.
+* Supersedes the implementation spec previously at `docs/superpowers/specs/2026-06-25-subdirectory-option-design.md` (removed; its content is folded into this ADR).

data/docs/adrs/0002-spp-aware-reconcile-scopes-and-only-guard.md

@@ -0,0 +1,114 @@
+# SPP-aware reconcile scopes, layout guard, and a --reconcile/--only guard
+
+* Status: accepted
+* Deciders: Tristan Starck, Kubernetes platform reviewers
+* Date: 2026-06-29 (revised 2026-07-06)
+
+Technical Story: OCTO-842 — add a `reconcile` flag to kubernetes_template_rendering / depends on [PR #14](https://github.com/Invoca/kubernetes_template_rendering/pull/14) (`--spp` + `PlaceholderExpander`)
+
+## Revision History
+
+* **2026-06-29** — original decision: SPP-aware sweep scopes (placeholder substitution) and the `--reconcile`/`--only` hard-error guard.
+* **2026-07-06** — revised the `--spp` sweep scope to *also* sweep `SPP-PLACEHOLDER` (see "`--spp` reconcile scope derivation" below), and folded in the SPP layout guard previously drafted as ADR-0003.
+
+## Context and Problem Statement
+
+[ADR-0001](0001-strict-rendering-paths-for-stale-resource-deletion.md) established `--reconcile`: after rendering the desired resources, sweep each owned root and delete files older than a marker captured before rendering, then remove empty directories. The base case sweeps `<region>/<cluster_type>/<color>/` with an `spp/` fence so the shared base sweep never touches Staging Partial Platform (SPP) subtrees.
+
+SPP definitions render under `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER/...`. The literal `SPP-PLACEHOLDER` token is preserved so it can be expanded per-instance downstream. PR #14 introduces the `--spp NAME` flag and `PlaceholderExpander`, which expands the `SPP-PLACEHOLDER` output into one concrete subtree per requested SPP (e.g. `spp/staging-qa02a/`). Crucially, `SPP-PLACEHOLDER` is *always* re-rendered on every run — it is the source `PlaceholderExpander` copies from — so its freshly rendered files are always newer than the reconcile marker.
+
+Three questions follow for reconcile:
+
+1. When a deploy targets specific SPPs (`--spp staging-qa02a`), which subtrees may reconcile sweep? It must delete stale files inside the *requested* SPP and inside `SPP-PLACEHOLDER` (both re-rendered this run), and must never touch unrequested SPP siblings (their deleted-SPP cleanup stays a manual `git rm` per the teardown runbook).
+2. How should `--reconcile` interact with PR #14's `--only` (render a subset of `definitions.yaml` entries)?
+3. How do we guarantee SPP resources actually land at the canonical `spp/SPP-PLACEHOLDER/` layout the sweep scoping depends on?
+
+## Decision Drivers
+
+* **Bounded, targeted sweeps** — `--spp` must scope reconcile to exactly the subtrees rendered this run.
+* **No accidental cross-SPP deletion** — unrequested SPP siblings must be fenced out of the sweep.
+* **Sweep the leftovers we own** — `SPP-PLACEHOLDER` is re-rendered every run, so its stale files (from deleted/renamed templates) must be collected, not left to accumulate.
+* **No silent data loss from partial renders** — a flag that renders a subset must not let reconcile delete the un-rendered (and therefore stale-looking) siblings.
+* **Enforce the layout the sweep assumes** — SPP resources must be where the fence-and-substitute scoping expects them.
+* **Minimal coupling to PR #14** — OCTO-842 owns reconcile scoping; expansion is PR #14's. Avoid duplicating `PlaceholderExpander` and keep the merge trivial.
+
+## Considered Options
+
+### Flag interaction: `--reconcile` + `--only`
+
+* **Option A — Hard error.** Reject `--reconcile --only` the same way `--reconcile --prune` is rejected.
+* **Option B — Narrow the sweep to only the rendered entries' roots.** Sweep just the roots of the `--only` entries.
+* **Option C — Allow it as-is.** Run the normal base sweep alongside a subset render.
+
+### `--spp` reconcile scope derivation
+
+* **Option 1 — Sweep `SPP-PLACEHOLDER` plus one root per requested target.** For each SPP scope whose root contains `SPP-PLACEHOLDER`, sweep the placeholder root itself *and* emit one sweep root per requested target (`spp/staging-qa02a`, …); with no `--spp`, sweep `spp/SPP-PLACEHOLDER` as-is.
+* **Option 1a (original, superseded) — Substitute only, excluding `SPP-PLACEHOLDER`.** Under `--spp`, sweep *only* the requested targets and leave `SPP-PLACEHOLDER` untouched.
+* **Option 2 — Always sweep the whole `spp/` tree** and rely on mtimes alone.
+
+### SPP layout enforcement (folded from ADR-0003)
+
+* **When:** (A) only under `--reconcile`, or (B) always.
+* **What:** (1) both directions — SPP entries must be under `spp/SPP-PLACEHOLDER/`, non-SPP entries must not be under any `spp/` segment; or (2) forward only.
+* **`directory:` escape hatch:** (X) allow if it still resolves to the canonical prefix; or (Y) reject outright for SPP entries.
+
+## Decision Outcome
+
+**Flag interaction: Option A (hard error).** `--reconcile --only` exits with a mutually-exclusive error. `--only` renders a subset, but reconcile sweeps the shared `<region>/<cluster_type>/<color>` base root; the un-rendered siblings would be older than the marker and get deleted. Option C is unsafe (silent deletion of valid resources). Option B is plausible but adds per-entry scoping complexity for a workflow no one has asked for; SPP targeting is already served by `--spp`. We can revisit Option B if a real need appears.
+
+**`--spp` scope derivation: Option 1 (sweep `SPP-PLACEHOLDER` plus requested targets).** `collect_reconcile_scopes` splits each entry's sweep root into base roots (non-SPP, swept with an `spp/` fence) and SPP roots. For an SPP root, `spp_reconcile_roots`:
+
+* with no `--spp`, returns the `spp/SPP-PLACEHOLDER` root unchanged (only the placeholder subtree is swept; expanded instances are left alone);
+* with `--spp X [Y…]`, returns the `spp/SPP-PLACEHOLDER` root **and** one root per requested target (`spp/X`, `spp/Y`), replacing the `SPP-PLACEHOLDER` segment for each target.
+
+The original decision (Option 1a) excluded `SPP-PLACEHOLDER` under `--spp`. That was revised on 2026-07-06: because the pipeline re-renders `SPP-PLACEHOLDER` on every run before expanding it, its fresh files are always newer than the marker, so sweeping it is marker-safe and *necessary* — otherwise stale output from deleted/renamed templates accumulates in `SPP-PLACEHOLDER` indefinitely when a team only ever deploys with `--spp`. Unrequested SPP siblings are *not* re-rendered this run, so they remain excluded (sweeping them would delete valid current files). Each derived root is re-validated to stay within `rendered_directory`. Substitution reuses the existing `ResourceSet::SPP_PLACEHOLDER` constant, so reconcile does **not** depend on PR #14's `PlaceholderExpander`; the two constants are equal once #14 lands.
+
+**SPP layout enforcement: only under `--reconcile` (A), both directions (1), validate shape (X).** The fence-and-substitute scoping above is only sound if SPP resources live at the canonical `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER/` layout. Nothing guaranteed this: SPP-ness is decided by the entry name containing `SPP-PLACEHOLDER`, and the deprecated `directory:` escape hatch can render anywhere while only printing a warning. So under `--reconcile`, `validate_spp_layout!` (run in `collect_reconcile_scopes`, before the marker and any writes) enforces:
+
+* **SPP entry** — `output_directory` must equal the canonical `spp_base_root` (`<rendered>/<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER`) or sit beneath it (`start_with?(base + File::SEPARATOR)`; the separator guards against `SPP-PLACEHOLDER-2`-style prefix collisions).
+* **Non-SPP entry** — `output_directory` must not contain any `spp` path segment (reusing `within_spp_subtree?`).
+
+A `directory:` override that still resolves to the canonical prefix is allowed; anything else raises `Reconciler::SppLayoutError` before rendering. Comparing against the fully-formatted canonical prefix (rather than counting path segments) stays correct even if a region value contains a slash. Because expansion derives its per-target subtrees from the already-validated `SPP-PLACEHOLDER` root, validating the pre-expansion path is sufficient — `--reconcile --spp` needs no extra check. Enforcing only under `--reconcile` (Option A) keeps plain renders, which never sweep, unaffected.
+
+### Flag / layout interaction summary
+
+| Flags | Reconcile sweep |
+| --- | --- |
+| `--reconcile` (no `--spp`) | base roots (with `spp/` fence) + `spp/SPP-PLACEHOLDER/` |
+| `--reconcile --spp X [Y…]` | base roots (fenced) + `spp/SPP-PLACEHOLDER/` + one root per requested `spp/X/`, `spp/Y/`; unrequested SPPs excluded |
+| `--reconcile --prune` | hard error |
+| `--reconcile --only …` | hard error |
+| SPP entry rendering outside `spp/SPP-PLACEHOLDER/` (under `--reconcile`) | `SppLayoutError` before any writes |
+| non-SPP entry rendering under any `spp/` segment (under `--reconcile`) | `SppLayoutError` before any writes |
+
+### Positive Consequences
+
+* `--spp` deploys reconcile the targeted SPP subtree(s) **and** `SPP-PLACEHOLDER`, so stale template output no longer accumulates in the placeholder tree; unrequested SPPs are never swept.
+* Reconcile is decoupled from expansion: it sweeps based on on-disk state and mtimes regardless of how files were produced, so it needs no `PlaceholderExpander` dependency.
+* The fence-and-substitute scoping rests on an enforced layout invariant rather than a convention.
+* The two destructive-combination footguns (`--prune`, `--only`) fail fast with clear messages.
+
+### Negative Consequences
+
+* `--reconcile --only` is unavailable; subset-targeted reconcile must go through `--spp`.
+* Deleted-SPP cleanup for *unrequested* siblings, and placeholder-flip cleanup, remain manual `git rm` (no GC mode, no `--prune-old-spps`), as scoped in the ticket.
+* A `directory:`-based SPP layout that reviewers previously tolerated now hard-errors under `--reconcile` and must move onto the canonical prefix.
+
+## Implementation Notes
+
+* `lib/kubernetes_template_rendering/cli.rb` — adds `--spp` / `--only` parsing (repeatable, de-duplicated), threads `spps:` into the renderer, and adds the `--reconcile --only` guard.
+* `lib/kubernetes_template_rendering/cli_arguments.rb` — adds `:spps`, `:only`.
+* `lib/kubernetes_template_rendering/resource_set.rb` — accepts `spps:`; `reconcile_scopes` carries `spp:` and the canonical `spp_base_root:` per scope.
+* `lib/kubernetes_template_rendering/reconciler.rb` — adds `Reconciler::SppLayoutError`.
+* `lib/kubernetes_template_rendering/template_directory_renderer.rb` — `collect_reconcile_scopes` calls `spp_reconcile_roots` (SPP-PLACEHOLDER + requested targets) and `validate_spp_layout!` (after the existing scope-escape pass).
+
+### Merge ordering with PR #14
+
+PR #14 landed on `main` first and OCTO-842 was merged on top of it. The `--spp` / `--only` flag plumbing, `CLIArguments` fields, and renderer signature were intentionally mirrored from PR #14, so the merge de-duplicated cleanly (identical hunks). Two pieces are owned by PR #14 rather than this change: the `--only` *filtering* of rendered entries (this ADR only adds the `--reconcile` + `--only` guard) and `PlaceholderExpander` (this change reuses the existing `ResourceSet::SPP_PLACEHOLDER` constant for sweep-root substitution and depends on the expander only at runtime). Since `--spp` expansion now runs during render (`PlaceholderExpander` preserves source mtimes), a `--spp` reconcile is a true end-to-end flow: expanded per-SPP files land after the marker and survive, while stale files in `SPP-PLACEHOLDER` and the requested SPP subtree are swept.
+
+## Links
+
+* Refines [ADR-0001](0001-strict-rendering-paths-for-stale-resource-deletion.md)
+* Supersedes the standalone ADR-0003 draft (SPP layout guard), now folded into this record.
+* Depends on [PR #14](https://github.com/Invoca/kubernetes_template_rendering/pull/14)
+* Supersedes the implementation spec previously at `docs/superpowers/specs/2026-07-06-reconcile-spp-layout-guard-design.md` (removed; its content is folded into this ADR).

data/lib/kubernetes_template_rendering/cli.rb

@@ -32,7 +32,16 @@ module KubernetesTemplateRendering
           op.on("--region=REGION",                             "set the specific region to render")                                   { args.region = _1 }
           op.on("--color=COLOR",                               "set the specific color to render")                                    { args.color = _1 }
           op.on("--[no-]prune",                                "enable/disable pruning of untouched resources")                       { args.prune = _1 }
+          op.on("--[no-]reconcile",                            "bounded post-render sweep of stale resources")                        { args.reconcile = _1 }
           op.on("--source-repo=SOURCE_REPO",                   "set the source repo for the rendered templates")                      { args.source_repo = _1 }
+          op.on("--spp=NAME", "Staging Partial Platform target name to expand SPP-PLACEHOLDER output for (repeatable)") do |name|
+            args.spps ||= []
+            args.spps << name
+          end
+          op.on("--only=NAME", "render only the definitions.yaml entry with this exact top-level key (repeatable)") do |name|
+            args.only ||= []
+            args.only << name
+          end
 
           op.on("--variable-override=KEY:VALUE", "override a variable value set within definitions.yaml", Array) do |overrides|
             args.variable_overrides ||= {} # Initialize as a Hash
@@ -50,12 +59,27 @@ module KubernetesTemplateRendering
 
         parser.parse!(options)
         args.template_directory = options.first
+        args.spps = (args.spps || []).uniq
+        args.only = (args.only || []).uniq
 
         unless args.valid?
           STDERR.puts(parser)
           exit(1)
         end
 
+        if args.reconcile? && args.prune?
+          STDERR.puts("--reconcile and --prune are mutually exclusive")
+          exit(1)
+        end
+
+        # --only renders a subset of entries, but reconcile sweeps the shared <region>/<type>/<color>
+        # base root; the un-rendered siblings would look stale and be deleted. SPP targeting uses --spp
+        # (which scopes reconcile to per-SPP subtrees), so --only + --reconcile is rejected outright.
+        if args.reconcile? && args.only.any?
+          STDERR.puts("--reconcile and --only are mutually exclusive")
+          exit(1)
+        end
+
         [renderer_from_args(args), args]
       end
 
@@ -69,7 +93,9 @@ module KubernetesTemplateRendering
           region: args.region,
           color: args.color,
           variable_overrides: args.variable_overrides,
-          source_repo: args.source_repo
+          source_repo: args.source_repo,
+          spps: args.spps,
+          only: args.only
         )
       end
 

data/lib/kubernetes_template_rendering/cli_arguments.rb

@@ -13,7 +13,10 @@ module KubernetesTemplateRendering
       :color,
       :variable_overrides,
       :prune,
-      :source_repo
+      :source_repo,
+      :reconcile,
+      :spps,
+      :only
     ) do
       def valid?
         rendered_directory && template_directory
@@ -31,6 +34,10 @@ module KubernetesTemplateRendering
         !!prune
       end
 
+      def reconcile?
+        !!reconcile
+      end
+
       def render_files?
         true
       end

data/lib/kubernetes_template_rendering/placeholder_expander.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+
+module KubernetesTemplateRendering
+  # Expands a rendered placeholder-bearing output tree into a per-target sibling tree by
+  # substituting the placeholder token in both file paths and file contents. Mirrors the
+  # semantics of invocaops_docker/tools/spp-transform/spp-transform.rb.
+  class PlaceholderExpander
+    class << self
+      def expand!(source_directory:, target_name:, placeholder_token:)
+        placeholder_suffix = placeholder_token.rpartition('-').last
+        target_suffix = target_name.rpartition('-').last
+
+        source_root = Pathname.new(source_directory)
+        dest_root = Pathname.new(source_directory.gsub(placeholder_token, target_name))
+
+        Pathname.glob(source_root + "**" + "*").each do |source_path|
+          next unless source_path.file?
+
+          relative = source_path.relative_path_from(source_root).to_s
+          relative_substituted = relative.gsub(placeholder_token, target_name)
+          dest_path = dest_root + relative_substituted
+          FileUtils.mkdir_p(dest_path.dirname)
+
+          mtime = source_path.mtime
+          contents = File.read(source_path)
+          contents = contents.gsub(placeholder_token, target_name)
+          contents = contents.gsub(placeholder_suffix, target_suffix)
+          File.write(dest_path, contents)
+          File.utime(mtime, mtime, dest_path)
+        end
+      end
+    end
+  end
+end

data/lib/kubernetes_template_rendering/reconciler.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "find"
+require "tempfile"
+require_relative "color"
+
+module KubernetesTemplateRendering
+  # Bounded, marker-based reconcile sweep replacing the destructive per-entry `rm -rf` prune.
+  #
+  # Lifecycle (driven by TemplateDirectoryRenderer):
+  #   1. Construct (touches a marker file; its mtime is the cutoff) BEFORE any rendering/forking.
+  #   2. Render writes files (mtime > marker); PlaceholderExpander copies preserve a just-rendered
+  #      source mtime (also > marker).
+  #   3. After all rendering, `sweep!` each scope root: delete files strictly older than the marker
+  #      (leftovers from deleted/renamed entries), then remove now-empty directories.
+  #
+  # `spp/` subtrees are fenced out of the base sweep; per the ticket, deleted-SPP cleanup is a
+  # manual `git rm`, never an automatic sweep.
+  class Reconciler
+    class OutOfScopeError < StandardError; end
+    class SppLayoutError < StandardError; end
+
+    attr_reader :marker_mtime
+
+    def initialize(rendered_directory)
+      FileUtils.mkdir_p(rendered_directory)
+      @marker = Tempfile.new(".reconcile-marker", rendered_directory)
+      @marker.close
+      @marker_mtime = File.mtime(@marker.path)
+    end
+
+    def sweep!(root:, fences: [])
+      return unless File.directory?(root)
+
+      real_root = File.realpath(root)
+      fence_set = fences.select { |fence| File.exist?(fence) }.map { |fence| File.realpath(fence) }
+
+      delete_stale_files(root, real_root, fence_set)
+      remove_empty_dirs(root, fence_set)
+    end
+
+    def finish!
+      @marker.unlink
+    end
+
+    private
+
+    # Two-phase for all-or-nothing safety: validate the whole tree while collecting,
+    # then delete only after the walk succeeds. A scope error mid-walk deletes nothing.
+    def delete_stale_files(root, real_root, fence_set)
+      collect_stale_files(root, real_root, fence_set).each do |path|
+        puts "Reconcile: removing stale file #{Color.magenta(path)}"
+        File.delete(path)
+      end
+    end
+
+    def collect_stale_files(root, real_root, fence_set)
+      stale_paths = []
+
+      Find.find(root) do |path|
+        if File.directory?(path)
+          # Skip fenced subtrees (e.g. spp/) entirely; validate every other directory.
+          if fenced?(path, fence_set)
+            Find.prune
+          else
+            ensure_in_scope!(path, root, real_root)
+          end
+          next
+        end
+
+        next unless File.file?(path)
+
+        ensure_in_scope!(path, root, real_root)
+        stale_paths << path if stale?(path)
+      end
+
+      stale_paths
+    end
+
+    def stale?(path)
+      File.mtime(path) < @marker_mtime
+    end
+
+    def remove_empty_dirs(root, fence_set)
+      Dir.glob(File.join(root, "**", "*/"))
+         .reject { |dir| fenced?(dir, fence_set) }
+         .sort
+         .reverse # deepest paths first so parents empty out after their children
+         .each do |dir|
+        next unless File.directory?(dir)
+
+        if Dir.empty?(dir)
+          puts "Reconcile: removing empty directory #{Color.magenta(dir)}"
+          Dir.rmdir(dir)
+        end
+      end
+    end
+
+    def ensure_in_scope!(path, root, real_root)
+      real = File.realpath(path)
+      return if real == real_root || real.start_with?(real_root + File::SEPARATOR)
+
+      raise OutOfScopeError, "reconcile: #{path} resolves outside sweep root #{root}"
+    end
+
+    def fenced?(path, fence_set)
+      return false if fence_set.empty?
+
+      resolved = File.realpath(path)
+      fence_set.any? { |fence| resolved == fence || resolved.start_with?(fence + File::SEPARATOR) }
+    end
+  end
+end

data/lib/kubernetes_template_rendering/resource_set.rb

@@ -2,10 +2,14 @@
 
 require_relative "resource"
 require_relative "deploy_grouped_resource"
+require_relative "placeholder_expander"
 
 # This class points to the resources in a given template_directory for a given kubernetes_cluster_type like 'ops' or 'prod' or 'ci'.
 # `config` contains the definitions found in `definitions_path`.
-#   The most important config is "directory" which is a pattern like "%{region}/%{type}/%{color}/staging-ops".
+#   The output directory is resolved from the mutually-exclusive "directory" and "subdirectory" config:
+#     "directory"    is a full pattern like "%{plain_region}/%{type}/%{color}/staging-ops".
+#     "subdirectory" is a literal final segment appended to the base path -> "%{plain_region}/%{type}/%{color}/<subdirectory>".
+#     when neither is given, output goes to the base path "%{plain_region}/%{type}/%{color}".
 #   The config "regions", "colors" are the sets of regions and colors to render for.
 # It renders into `rendered_directory`.
 module KubernetesTemplateRendering
@@ -13,14 +17,16 @@ module KubernetesTemplateRendering
     attr_reader :variables, :output_directory, :deploy_group_config, :omitted_resources,
                 :template_directory, :target_output_directory, :regions, :colors,
                 :definitions_path, :kubernetes_cluster_type, :variable_overrides,
-                :source_repo
+                :source_repo, :spps
 
-    def initialize(config:, template_directory:, rendered_directory:, definitions_path:, kubernetes_cluster_type:, variable_overrides: {}, source_repo: nil)
+    def initialize(config:, template_directory:, rendered_directory:, definitions_path:, kubernetes_cluster_type:,
+                   spp: false, spps: [], variable_overrides: {}, source_repo: nil)
+      @spp                     = spp
       @variables               = config["variables"] || {}
       @deploy_group_config     = config["deploy_groups"]
       @omitted_resources       = config["omitted_resources"]
       @template_directory      = template_directory
-      @target_output_directory = config["directory"] or raise ArgumentError, "missing 'directory:' in #{config.inspect}"
+      @target_output_directory = resolve_target_output_directory(config["directory"], config["subdirectory"])
       @regions                 = config["regions"] || []
       @colors                  = config["colors"] || []
       @rendered_directory      = rendered_directory
@@ -29,6 +35,7 @@ module KubernetesTemplateRendering
       @variable_overrides      = variable_overrides
       @source_repo             = source_repo
       @resources               = {}
+      @spps                    = Array(spps)
 
       if @kubernetes_cluster_type != "kube-platform"
         @target_output_directory.include?("%{plain_region}") or raise "#{@template_directory}: target_output_directory #{@target_output_directory} needs %{plain_region}"
@@ -65,6 +72,28 @@ module KubernetesTemplateRendering
       end
     end
 
+    # Bounded reconcile scope roots for this entry, one per region × color.
+    #
+    # The sweep root is the parent directory of the entry's rendered `output_directory`, derived
+    # from the actual `directory:` pattern rather than assuming a fixed layout. For a
+    # `.../<service>` pattern that parent is the `<region>/<cluster_type>/<color>` base; for a
+    # `<region>/<service>` pattern it is `<region>`. The parent is shared with sibling entries, so
+    # leftovers from a deleted/renamed entry under it are swept. The renderer validates each
+    # `base_root` stays within `rendered_directory` (out-of-prefix, full or relative, is a hard error).
+    #
+    # Each scope also carries `spp:` (whether this entry is an SPP definition) and `spp_base_root:`
+    # (the canonical `<region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER` prefix for that region ×
+    # color) so the renderer can enforce the SPP layout guard before rendering.
+    def reconcile_scopes
+      @regions.flat_map do |plain_region|
+        @colors.map do |c|
+          output_directory = File.join(@rendered_directory, format(@target_output_directory, plain_region: plain_region, color: c, type: @kubernetes_cluster_type))
+          spp_base_root    = File.join(@rendered_directory, format(SPP_BASE_OUTPUT_DIRECTORY, plain_region: plain_region, color: c, type: @kubernetes_cluster_type))
+          { base_root: File.dirname(output_directory), output_directory: output_directory, spp: @spp, spp_base_root: spp_base_root }
+        end
+      end
+    end
+
     def render_create_directory(args, output_directory)
       prune_directory(output_directory) if args.prune?
       create_directory(output_directory)
@@ -80,11 +109,53 @@ module KubernetesTemplateRendering
       resources(output_directory).each do |resource|
         resource.render(args)
       end
+      expand_placeholders(args, output_directory)
       puts
     end
 
     private
 
+    # The output-directory pattern is resolved from the mutually-exclusive
+    # `directory:` and `subdirectory:` config fields:
+    #   directory only    -> the directory pattern, verbatim
+    #   subdirectory only -> "%{plain_region}/%{type}/%{color}/<subdirectory>"
+    #   neither           -> base path; "%{plain_region}/%{type}/%{color}", or the SPP base
+    #                        "%{plain_region}/%{type}/%{color}/spp/SPP-PLACEHOLDER" for SPP definitions
+    #   both              -> ArgumentError
+    SPP_PLACEHOLDER = "SPP-PLACEHOLDER"
+    BASE_OUTPUT_DIRECTORY = File.join("%{plain_region}", "%{type}", "%{color}")
+    # SPP definitions render under an extra spp/SPP-PLACEHOLDER segment so each SPP
+    # instance has a distinct, bounded path and the literal token survives for
+    # downstream per-instance substitution.
+    SPP_BASE_OUTPUT_DIRECTORY = File.join(BASE_OUTPUT_DIRECTORY, "spp", SPP_PLACEHOLDER)
+
+    def resolve_target_output_directory(directory, subdirectory)
+      if directory && subdirectory
+        raise ArgumentError, "specify only one of 'directory:' or 'subdirectory:' in #{({ 'directory' => directory, 'subdirectory' => subdirectory }).inspect}"
+      elsif directory
+        warn_directory_deprecated(directory)
+        directory
+      elsif subdirectory
+        File.join(base_output_directory, subdirectory)
+      else
+        base_output_directory
+      end
+    end
+
+    # SPP definitions render under SPP_BASE_OUTPUT_DIRECTORY; everything else uses the standard base.
+    def base_output_directory
+      @spp ? SPP_BASE_OUTPUT_DIRECTORY : BASE_OUTPUT_DIRECTORY
+    end
+
+    # `directory:` is a deprecated legacy escape hatch. It is the only way to produce a
+    # path that is not derived from the standard "%{plain_region}/%{type}/%{color}" layout,
+    # which is unsafe for --reconcile stale-resource deletion (see ADR-0001). Warn on any use.
+    def warn_directory_deprecated(directory)
+      puts Color.brown("WARNING: #{@template_directory}: `directory:` is deprecated. " \
+                       "Remove it to render into the standard #{base_output_directory} layout, " \
+                       "or use `subdirectory:` instead. (got `directory: #{directory}`)")
+    end
+
     CLOUD_REGION_TO_PROVIDER_AND_DATACENTER = {
       # Note: The names below should match RegionDiscovery from process_settings-production.
       # https://github.com/Invoca/process_settings-production/blob/main/settings/region_discovery/production_regions.yml
@@ -182,6 +253,27 @@ module KubernetesTemplateRendering
       end
     end
 
+    # Two orthogonal gates:
+    #   @spps.empty?  - caller didn't pass --spp NAME; nothing to fan out to
+    #   !@spp         - entry name is not SPP-shaped, so output_directory does not contain
+    #                   SPP_PLACEHOLDER; gsub-based expansion would be a no-op that hits
+    #                   --prune as a data-loss footgun (per_spp_dir collides with source).
+    def expand_placeholders(args, output_directory)
+      return if @spps.empty?
+      return unless @spp
+
+      @spps.each do |spp_name|
+        per_spp_dir = output_directory.gsub(SPP_PLACEHOLDER, spp_name)
+        prune_directory(per_spp_dir) if args.prune?
+        puts "Expanding #{SPP_PLACEHOLDER} to #{Color.magenta(spp_name)}"
+        PlaceholderExpander.expand!(
+          source_directory: output_directory,
+          target_name: spp_name,
+          placeholder_token: SPP_PLACEHOLDER
+        )
+      end
+    end
+
     def resources(output_directory)
       @resources[output_directory] ||= standard_resources(output_directory) + grouped_resources(output_directory)
     end

data/lib/kubernetes_template_rendering/template.rb

@@ -25,11 +25,11 @@ module KubernetesTemplateRendering
 
     def with_auto_generated_yaml_comment(yaml_string)
       comment = <<~EOS
-      # WARNING: DO NO EDIT THIS FILE!
+      # WARNING: DO NOT EDIT THIS FILE!
       # Any changes made here will be lost.
       # This file is autogenerated from #{full_template_path}
       EOS
-      comment + variable_override_comment + yaml_string
+      comment + yaml_string
     end
 
     def full_template_path
@@ -40,14 +40,6 @@ module KubernetesTemplateRendering
       end
     end
 
-    def variable_override_comment
-      if variable_overrides&.any?
-        <<~EOS
-        # Variable overrides used: #{variable_overrides.to_json}
-        EOS
-      end || ""
-    end
-
     class << self
       # @param [String] template_path: file path to template file that needs to be rendered.
       # @param [Hash]: variables that will be used in the template file to generate distict files.

data/lib/kubernetes_template_rendering/template_directory_renderer.rb

@@ -3,8 +3,10 @@
 require 'active_support'
 require 'active_support/core_ext' # for deep_merge
 require 'invoca/utils'
+require 'pathname'
 require 'yaml'
 require_relative 'resource_set'
+require_relative 'reconciler'
 require 'set'
 
 # This class points to a collection of template directories to render, and a rendered_directory to render into.
@@ -12,10 +14,13 @@ require 'set'
 module KubernetesTemplateRendering
   class TemplateDirectoryRenderer
     DEFINITIONS_FILENAME = "definitions.yaml"
+    SPP_FENCE_DIRNAME = "spp"
 
-    attr_reader :directories, :omitted_names, :rendered_directory, :cluster_type, :region, :color, :variable_overrides, :source_repo
+    attr_reader :directories, :omitted_names, :rendered_directory, :cluster_type, :region, :color,
+                :variable_overrides, :source_repo, :spps, :only
 
-    def initialize(directories:, rendered_directory:, omitted_names: [], cluster_type: nil, region: nil, color: nil, variable_overrides: nil, source_repo: nil)
+    def initialize(directories:, rendered_directory:, omitted_names: [], cluster_type: nil, region: nil, color: nil,
+                   variable_overrides: nil, source_repo: nil, spps: [], only: [])
       @directories        = directories_with_definitions(Array(directories))
       @omitted_names      = Array(omitted_names)
       @rendered_directory = rendered_directory
@@ -24,9 +29,16 @@ module KubernetesTemplateRendering
       @color              = color
       @variable_overrides = variable_overrides || {}
       @source_repo        = source_repo
+      @spps               = Array(spps)
+      @only               = Array(only)
     end
 
     def render(args)
+      if args.reconcile?
+        sweep_scopes = collect_reconcile_scopes # validates out-of-prefix before any writes
+        reconciler   = Reconciler.new(@rendered_directory) # marker captured before rendering/forking
+      end
+
       child_pids = []
       failed_processes = [] # [[pid, status]]
 
@@ -58,10 +70,103 @@ module KubernetesTemplateRendering
           raise "Child process completed with non-zero status: #{failed_processes.inspect}"
         end
       end
+
+      reconcile_sweep(reconciler, sweep_scopes) if args.reconcile?
     end
 
     private
 
+    # Collects sweep roots across all rendered resource sets and validates that each stays within
+    # rendered_directory (out-of-prefix, full or relative `..`, is a hard error).
+    #
+    # Returns two categories:
+    #   base_roots — non-SPP entries' shared parent (e.g. <region>/<cluster_type>/<color>/);
+    #                swept with an spp/ fence so sibling SPP directories are never touched.
+    #   spp_roots  — the specific SPP directory/directories that were rendered (e.g. spp/<spp-name>/);
+    #                swept without a fence since we are already inside exactly one SPP directory.
+    #                Without --spp, only the SPP-PLACEHOLDER root is swept. With --spp, the sweep
+    #                covers SPP-PLACEHOLDER (always re-rendered) plus each requested target; unrequested
+    #                siblings are left intact (their deleted-SPP cleanup stays a manual git rm).
+    def collect_reconcile_scopes
+      scopes = resource_sets.values.flatten.flat_map(&:reconcile_scopes)
+      scopes.each do |scope|
+        validate_within_scope!(scope[:base_root], @rendered_directory)
+        validate_spp_layout!(scope)
+      end
+
+      base_roots = []
+      spp_roots  = []
+      scopes.each do |scope|
+        if within_spp_subtree?(scope[:base_root])
+          spp_roots.concat(spp_reconcile_roots(scope))
+        else
+          base_roots << scope[:base_root]
+        end
+      end
+      spp_roots.each { |r| validate_within_scope!(r, @rendered_directory) }
+      { base_roots: base_roots.uniq, spp_roots: spp_roots.uniq }
+    end
+
+    # Raises unless `path` resolves within `scope_root` (full-path or relative `..` escape).
+    # Lexical check (expand_path, not realpath) so it validates planned roots before they exist;
+    # Reconciler applies a separate realpath-based guard against symlink escapes during the sweep.
+    def validate_within_scope!(path, scope_root)
+      resolved = File.expand_path(path)
+      root = File.expand_path(scope_root)
+      unless resolved == root || resolved.start_with?(root + File::SEPARATOR)
+        raise Reconciler::OutOfScopeError, "reconcile: path #{resolved} resolves outside scope prefix #{root}"
+      end
+    end
+
+    # Under --reconcile, SPP entries must render beneath the canonical
+    # <region>/<cluster_type>/<color>/spp/SPP-PLACEHOLDER/ prefix, and non-SPP entries must never
+    # render beneath any spp/ segment. A directory:-overridden path that still resolves to the
+    # canonical SPP prefix is allowed; anything else is a hard error before any writes.
+    def validate_spp_layout!(scope)
+      output = File.expand_path(scope[:output_directory])
+      if scope[:spp]
+        base = File.expand_path(scope[:spp_base_root])
+        unless output == base || output.start_with?(base + File::SEPARATOR)
+          raise Reconciler::SppLayoutError,
+                "reconcile: SPP entry renders to #{output}, outside the required SPP prefix #{base}"
+        end
+      elsif within_spp_subtree?(scope[:output_directory])
+        raise Reconciler::SppLayoutError,
+              "reconcile: non-SPP entry renders under an spp/ segment (#{output}); only SPP entries may render beneath spp/"
+      end
+    end
+
+    # Expands an SPP sweep root into the concrete roots to sweep for this run.
+    # Without --spp, the placeholder root (spp/SPP-PLACEHOLDER) is swept as-is. With --spp, the sweep
+    # covers the placeholder root *and* each requested target (spp/staging-qa02a, ...): SPP-PLACEHOLDER
+    # is always re-rendered (it is the expansion source) and each target is freshly expanded from it,
+    # so both are marker-safe. Unrequested SPP siblings are not re-rendered this run and stay excluded.
+    def spp_reconcile_roots(scope)
+      root = spp_sweep_root(scope)
+      return [root] if @spps.empty?
+      return [root] unless root.include?(ResourceSet::SPP_PLACEHOLDER)
+
+      [root] + @spps.map { |spp_name| root.gsub(ResourceSet::SPP_PLACEHOLDER, spp_name) }
+    end
+
+    def within_spp_subtree?(root)
+      Pathname.new(root).relative_path_from(Pathname.new(@rendered_directory)).each_filename.include?(SPP_FENCE_DIRNAME)
+    end
+
+    # When the directory pattern has no service subdirectory (e.g. `.../spp/SPP-PLACEHOLDER`),
+    # base_root lands at the `spp/` level itself — sweeping that would touch all SPP siblings.
+    # Use output_directory (= `spp/<spp-name>`) in that case instead.
+    def spp_sweep_root(scope)
+      File.basename(scope[:base_root]) == SPP_FENCE_DIRNAME ? scope[:output_directory] : scope[:base_root]
+    end
+
+    def reconcile_sweep(reconciler, scopes)
+      scopes[:base_roots].each { |r| reconciler.sweep!(root: r, fences: [File.join(r, SPP_FENCE_DIRNAME)]) }
+      scopes[:spp_roots].each  { |r| reconciler.sweep!(root: r) }
+    ensure
+      reconciler.finish!
+    end
+
     def read_definitions(path)
       File.read(path)
     end
@@ -106,26 +211,48 @@ module KubernetesTemplateRendering
     end
 
     def resource_sets
-      @resource_sets ||= @directories.each_with_object({}) do |dir, hash|
-        definitions_path = definitions_path_for_dir(dir)
-        config = load_config(definitions_path)
-
-        config.map do |name, config|
-          next if omitted_names.include?(name)
-
-          kubernetes_cluster_type = name.sub('SPP-PLACEHOLDER', 'staging').sub(/\..*/, '') # prod.gcp => prod
-
-          hash[name] ||= []
-          hash[name] << ResourceSet.new(
-            config: config,
-            template_directory: dir,
-            rendered_directory: @rendered_directory,
-            kubernetes_cluster_type: kubernetes_cluster_type,
-            definitions_path: definitions_path,
-            variable_overrides: @variable_overrides,
-            source_repo: @source_repo
-          )
+      @resource_sets ||= begin
+        matched_only = Set.new
+        all_keys = Set.new
+        sets = @directories.each_with_object({}) do |dir, hash|
+          definitions_path = definitions_path_for_dir(dir)
+          config = load_config(definitions_path)
+
+          config.each_key { |name| all_keys << name }
+
+          config.map do |name, config|
+            next if omitted_names.include?(name)
+            next if @only.any? && !@only.include?(name)
+            matched_only << name if @only.include?(name)
+
+            kubernetes_cluster_type = name.sub(ResourceSet::SPP_PLACEHOLDER, 'staging').sub(/\..*/, '') # prod.gcp => prod
+            spp = name.include?(ResourceSet::SPP_PLACEHOLDER)
+
+            hash[name] ||= []
+            hash[name] << ResourceSet.new(
+              config: config,
+              template_directory: dir,
+              rendered_directory: @rendered_directory,
+              kubernetes_cluster_type: kubernetes_cluster_type,
+              spp: spp,
+              spps: @spps,
+              definitions_path: definitions_path,
+              variable_overrides: @variable_overrides,
+              source_repo: @source_repo
+            )
+          end
         end
+
+        if @only.any?
+          unmatched = @only - matched_only.to_a
+          if unmatched.any?
+            raise ArgumentError,
+                  "--only values not found in any definitions.yaml entry: #{unmatched.inspect}. " \
+                  "Valid keys: #{all_keys.to_a.sort.inspect}"
+          end
+        end
+
+        sets
       end
     end
 
@@ -173,7 +300,7 @@ module KubernetesTemplateRendering
       end
 
       expand_config(config).each_with_object({}) do |(name, data), hash|
-        if !cluster_type || cluster_type == name.sub('SPP-PLACEHOLDER', 'staging').sub(/\..*/, '') # prod.gcp => prod
+        if !cluster_type || cluster_type == name.sub(ResourceSet::SPP_PLACEHOLDER, 'staging').sub(/\..*/, '') # prod.gcp => prod
           cluster_type_config = OpenStruct.new(data)
 
           cluster_type_config.regions   = cluster_type_config.regions & [region] if region

data/lib/kubernetes_template_rendering/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KubernetesTemplateRendering
-  VERSION = "0.2.5"
+  VERSION = "0.6.0.prerelease.tstarck.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kubernetes_template_rendering
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.6.0.prerelease.tstarck.1
 platform: ruby
 authors:
 - Octothorpe
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-08 00:00:00.000000000 Z
+date: 2026-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Tool for rendering ERB and Jsonnet templates
 email:
 - octothorpe@invoca.com
@@ -71,6 +85,8 @@ files:
 - docs/CHANGELOG.md
 - docs/README.md
 - docs/adrs/0000-template.md
+- docs/adrs/0001-strict-rendering-paths-for-stale-resource-deletion.md
+- docs/adrs/0002-spp-aware-reconcile-scopes-and-only-guard.md
 - exe/render_templates
 - lib/kubernetes_template_rendering.rb
 - lib/kubernetes_template_rendering/cli.rb
@@ -79,6 +95,8 @@ files:
 - lib/kubernetes_template_rendering/deploy_grouped_resource.rb
 - lib/kubernetes_template_rendering/erb_template.rb
 - lib/kubernetes_template_rendering/jsonnet_template.rb
+- lib/kubernetes_template_rendering/placeholder_expander.rb
+- lib/kubernetes_template_rendering/reconciler.rb
 - lib/kubernetes_template_rendering/resource.rb
 - lib/kubernetes_template_rendering/resource_set.rb
 - lib/kubernetes_template_rendering/template.rb