@intentius/chant-lexicon-k8s 0.42.1 → 0.44.2

package/src/lint/post-synth/post-synth.test.ts

@@ -31,6 +31,8 @@ import { wk8403 } from "./wk8403";
 import { argo002 } from "./argo002";
 import { argo003 } from "./argo003";
 import { argo005 } from "./argo005";
+import { flux002 } from "./flux002";
+import { flux003 } from "./flux003";
 
 function makeCtx(yaml: string): PostSynthContext {
   return {
@@ -1659,3 +1661,133 @@ describe("ARGO005: Application source path exists", () => {
     expect(argo005.check(ctx).length).toBe(0);
   });
 });
+
+// ── FLUX002: Kustomization sourceRef references a declared source ─────────────
+
+function fluxKustomization(name: string, spec: Record<string, unknown>) {
+  return {
+    apiVersion: "kustomize.toolkit.fluxcd.io/v1",
+    kind: "Kustomization",
+    metadata: { name, namespace: "flux-system" },
+    spec: { interval: "10m", path: "./k8s", prune: true, wait: true, ...spec },
+  };
+}
+function fluxGitRepository(name: string) {
+  return {
+    apiVersion: "source.toolkit.fluxcd.io/v1",
+    kind: "GitRepository",
+    metadata: { name, namespace: "flux-system" },
+    spec: { interval: "5m", url: `https://example.com/${name}`, ref: { branch: "main" } },
+  };
+}
+const gitSourceRef = (name: string) => ({ sourceRef: { kind: "GitRepository", name } });
+
+describe("FLUX002: Kustomization sourceRef references a declared source", () => {
+  test("metadata", () => {
+    expect(flux002.id).toBe("FLUX002");
+  });
+
+  test("flags a Kustomization referencing an undeclared GitRepository", () => {
+    const ctx = manifestsCtx(fluxKustomization("hello", gitSourceRef("home-chant")));
+    const diags = flux002.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].checkId).toBe("FLUX002");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("home-chant");
+  });
+
+  test("passes when the GitRepository is declared in the same build", () => {
+    const ctx = manifestsCtx(
+      fluxGitRepository("home-chant"),
+      fluxKustomization("hello", gitSourceRef("home-chant")),
+    );
+    expect(flux002.check(ctx).length).toBe(0);
+  });
+
+  test("does NOT flag the bootstrap-created flux-system source", () => {
+    const ctx = manifestsCtx(fluxKustomization("mealie", gitSourceRef("flux-system")));
+    expect(flux002.check(ctx).length).toBe(0);
+  });
+
+  test("matches on source kind — a GitRepository does not satisfy an OCIRepository ref", () => {
+    const ctx = manifestsCtx(
+      fluxGitRepository("fountain"),
+      fluxKustomization("fountain", { sourceRef: { kind: "OCIRepository", name: "fountain" } }),
+    );
+    const diags = flux002.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].message).toContain("OCIRepository");
+  });
+
+  test("flags a Kustomization with no sourceRef at all", () => {
+    const ctx = manifestsCtx(fluxKustomization("hello", {}));
+    const diags = flux002.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].message).toContain("no spec.sourceRef.name");
+  });
+
+  test("skips kustomize.config.k8s.io Kustomizations (not Flux CRs)", () => {
+    const ctx = manifestsCtx({
+      apiVersion: "kustomize.config.k8s.io/v1beta1",
+      kind: "Kustomization",
+      metadata: { name: "overlay" },
+      spec: {},
+    });
+    expect(flux002.check(ctx).length).toBe(0);
+  });
+});
+
+// ── FLUX003: Kustomization dependsOn names declared Kustomizations ────────────
+
+describe("FLUX003: Kustomization dependsOn names declared Kustomizations", () => {
+  test("metadata", () => {
+    expect(flux003.id).toBe("FLUX003");
+  });
+
+  test("flags a dependsOn entry nothing in the build declares", () => {
+    const ctx = manifestsCtx(
+      fluxKustomization("hello", { ...gitSourceRef("flux-system"), dependsOn: [{ name: "cert-manger" }] }),
+    );
+    const diags = flux003.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].checkId).toBe("FLUX003");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("cert-manger");
+  });
+
+  test("passes when every dependency is declared", () => {
+    const ctx = manifestsCtx(
+      fluxKustomization("cert-manager", gitSourceRef("flux-system")),
+      fluxKustomization("traefik", gitSourceRef("flux-system")),
+      fluxKustomization("hello", {
+        ...gitSourceRef("flux-system"),
+        dependsOn: [{ name: "cert-manager" }, { name: "traefik" }],
+      }),
+    );
+    expect(flux003.check(ctx).length).toBe(0);
+  });
+
+  test("flags a self-referencing dependsOn entry", () => {
+    const ctx = manifestsCtx(
+      fluxKustomization("hello", { ...gitSourceRef("flux-system"), dependsOn: [{ name: "hello" }] }),
+    );
+    const diags = flux003.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].message).toContain("itself");
+  });
+
+  test("reports every broken edge, not just the first", () => {
+    const ctx = manifestsCtx(
+      fluxKustomization("hello", {
+        ...gitSourceRef("flux-system"),
+        dependsOn: [{ name: "nope-a" }, { name: "nope-b" }],
+      }),
+    );
+    expect(flux003.check(ctx).length).toBe(2);
+  });
+
+  test("skips a Kustomization without dependsOn", () => {
+    const ctx = manifestsCtx(fluxKustomization("hello", gitSourceRef("flux-system")));
+    expect(flux003.check(ctx).length).toBe(0);
+  });
+});

package/src/lint/rules/flux-source-ref-pin.ts

@@ -0,0 +1,52 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { findResourceLiterals, getNestedObject, getNestedString, getProp, lineCol } from "./argo-ast";
+import * as ts from "typescript";
+
+/**
+ * FLUX001: GitRepository must pin spec.ref
+ *
+ * A Flux `GitRepository` with no `spec.ref` falls back to the `master` branch,
+ * which on most repos no longer exists — the source stalls with a checkout
+ * error, and every Kustomization downstream of it stalls too. Real estates pin
+ * a branch (or tag) on every source; `FluxGitSource` always emits one. Flag
+ * hand-written `GitRepository` literals whose spec carries a `url` but no
+ * `ref`.
+ *
+ * Bad:  new GitRepository({ spec: { url: "https://github.com/acme/infra" } })
+ * Good: new GitRepository({ spec: { url: "https://github.com/acme/infra", ref: { branch: "main" } } })
+ */
+
+export const fluxSourceRefPinRule: LintRule = {
+  id: "FLUX001",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "Flux GitRepository must pin spec.ref (branch, tag, semver, or commit) — the unset default is the master branch",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    for (const { literal } of findResourceLiterals(sourceFile, new Set(["GitRepository"]))) {
+      const spec = getNestedObject(literal, ["spec"]);
+      // No spec object literal to inspect — leave it to other tooling.
+      if (!spec) continue;
+      if (getProp(spec, "ref") !== undefined) continue;
+
+      const anchor: ts.Node = spec;
+      const { line, column } = lineCol(sourceFile, anchor);
+      const name = getNestedString(literal, ["metadata", "name"]) ?? "(unnamed)";
+
+      diagnostics.push({
+        file: sourceFile.fileName,
+        line,
+        column,
+        ruleId: "FLUX001",
+        severity: "warning",
+        message: `GitRepository "${name}" has no spec.ref — Flux falls back to the master branch. Pin a branch, tag, semver range, or commit.`,
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/rules.test.ts

@@ -4,6 +4,7 @@ import { latestImageTagRule } from "./latest-image-tag";
 import { missingResourceLimitsRule } from "./missing-resource-limits";
 import { argoAutomatedPruneRule } from "./argo-automated-prune";
 import { argoAppSetSingleProjectRule } from "./argo-appset-single-project";
+import { fluxSourceRefPinRule } from "./flux-source-ref-pin";
 import * as ts from "typescript";
 
 function createContext(code: string) {
@@ -368,3 +369,53 @@ describe("ARGO004: ApplicationSet single AppProject", () => {
     expect(diags[0].message).toContain("placeholder");
   });
 });
+
+describe("FLUX001: GitRepository must pin spec.ref", () => {
+  test("rule metadata", () => {
+    expect(fluxSourceRefPinRule.id).toBe("FLUX001");
+    expect(fluxSourceRefPinRule.severity).toBe("warning");
+    expect(fluxSourceRefPinRule.category).toBe("correctness");
+  });
+
+  test("flags a GitRepository with a url but no ref", () => {
+    const ctx = createContext(`
+      new GitRepository({
+        metadata: { name: "home-chant" },
+        spec: { interval: "5m", url: "https://github.com/jhgaylor/home-chant" },
+      });
+    `);
+    const diags = fluxSourceRefPinRule.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].ruleId).toBe("FLUX001");
+    expect(diags[0].message).toContain("home-chant");
+    expect(diags[0].message).toContain("master");
+  });
+
+  test("does NOT flag a branch pin", () => {
+    const ctx = createContext(`
+      new GitRepository({
+        metadata: { name: "home-chant" },
+        spec: { url: "https://github.com/jhgaylor/home-chant", ref: { branch: "main" } },
+      });
+    `);
+    expect(fluxSourceRefPinRule.check(ctx).length).toBe(0);
+  });
+
+  test("does NOT flag a tag pin", () => {
+    const ctx = createContext(`
+      new GitRepository({
+        metadata: { name: "infra" },
+        spec: { url: "https://example.com/infra", ref: { tag: "v1.2.3" } },
+      });
+    `);
+    expect(fluxSourceRefPinRule.check(ctx).length).toBe(0);
+  });
+
+  test("skips a GitRepository with no inspectable spec literal", () => {
+    const ctx = createContext(`
+      const spec = buildSpec();
+      new GitRepository({ metadata: { name: "dynamic" }, spec });
+    `);
+    expect(fluxSourceRefPinRule.check(ctx).length).toBe(0);
+  });
+});

package/src/plugin.test.ts

@@ -39,6 +39,8 @@ describe("k8sPlugin", () => {
     const ids = checks.map((c) => c.id);
     expect(ids).toContain("WK8101");
     expect(ids).toContain("ARGO002");
+    expect(ids).toContain("FLUX002");
+    expect(ids).toContain("FLUX003");
   });
 
   test("intrinsics() returns empty array", () => {

package/src/plugin.ts

@@ -21,6 +21,7 @@ import { latestImageTagRule } from "./lint/rules/latest-image-tag";
 import { missingResourceLimitsRule } from "./lint/rules/missing-resource-limits";
 import { argoAutomatedPruneRule } from "./lint/rules/argo-automated-prune";
 import { argoAppSetSingleProjectRule } from "./lint/rules/argo-appset-single-project";
+import { fluxSourceRefPinRule } from "./lint/rules/flux-source-ref-pin";
 import { k8sCompletions } from "./lsp/completions";
 import { k8sHover } from "./lsp/hover";
 import { K8sParser } from "./import/parser";
@@ -28,6 +29,8 @@ import { K8sGenerator } from "./import/generator";
 import { k8sDeepNormalizationHooks } from "./deep-observe-hooks";
 import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
 import { k8sConfigSchema } from "./config-schema";
+import type { K8sChantConfig } from "./config";
+import { renderKustomizeRoots } from "./kustomize/root";
 
 export const k8sPlugin: LexiconPlugin = {
   name: "k8s",
@@ -62,6 +65,7 @@ export const k8sPlugin: LexiconPlugin = {
       missingResourceLimitsRule,
       argoAutomatedPruneRule,
       argoAppSetSingleProjectRule,
+      fluxSourceRefPinRule,
     ];
   },
 
@@ -69,6 +73,18 @@ export const k8sPlugin: LexiconPlugin = {
     return postSynthCheckList;
   },
 
+  // #1548 piece 3 — kustomization dirs declared as build roots. Each entry in
+  // `k8s.kustomize.roots` renders at build time (same injectable runner as
+  // the kustomize-apply capability: `kustomize build`, `kubectl kustomize`
+  // fallback) and the documents join the build as verbatim manifest entities:
+  // serialized with ownership stamping, checked post-synth, observed by
+  // `lifecycle diff --live`. See ./kustomize/root.ts.
+  async buildRoots(ctx) {
+    const roots = (ctx.config as { k8s?: K8sChantConfig }).k8s?.kustomize?.roots ?? [];
+    if (roots.length === 0) return { entities: new Map() };
+    return renderKustomizeRoots({ projectRoot: ctx.projectRoot, roots });
+  },
+
   // K8s YAML has no template interpolation functions like CloudFormation's
   // Fn::Sub or GitLab's !reference. Cross-resource references are handled by
   // the AttrRef system in the serializer (resolves to metadata.name).
@@ -624,6 +640,37 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
           },
         ],
       },
+      {
+        file: "chant-k8s-flux.md",
+        name: "chant-k8s-flux",
+        description: "Flux CD composites — FluxGitSource + FluxAppFor, the one-source-many-apps shape, dependsOn ordering, the FLUX rules, and the flux-reconcile deploy step",
+        triggers: [
+          { type: "context", value: "flux" },
+          { type: "context", value: "fluxcd" },
+          { type: "context", value: "flux cd" },
+          { type: "context", value: "gitops" },
+          { type: "context", value: "gitrepository" },
+          { type: "context", value: "kustomization" },
+          { type: "context", value: "source-controller" },
+          { type: "context", value: "kustomize-controller" },
+          { type: "context", value: "reconcile" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "Source + Kustomization from a build target",
+            description: "Reconcile a Chant build target with Flux",
+            input: "Deploy my app through Flux",
+            output: "import { FluxGitSource, FluxAppFor } from \"@intentius/chant-lexicon-k8s\";\n\nexport const source = FluxGitSource(\"infra\", {\n  url: \"https://github.com/acme/infra\",\n  branch: \"main\",\n});\n\nexport const app = FluxAppFor(\"app\", {\n  source,\n  path: \"./dist/apps/app\",\n  dependsOn: [\"platform\"],\n});",
+          },
+          {
+            title: "One source, many apps",
+            description: "The multi-app repo shape — one GitRepository shared by every Kustomization",
+            input: "Reconcile platform, api, and web from one repo with ordering",
+            output: "import { FluxGitSource, FluxAppFor } from \"@intentius/chant-lexicon-k8s\";\n\nconst source = FluxGitSource(\"infra\", { url: \"https://github.com/acme/infra\" });\n\nexport const platform = FluxAppFor(\"platform\", { source, path: \"./dist/platform\" });\nexport const api = FluxAppFor(\"api\", { source, path: \"./dist/apps/api\", dependsOn: [\"platform\"] });\nexport const web = FluxAppFor(\"web\", { source, path: \"./dist/apps/web\", dependsOn: [\"platform\", \"api\"] });",
+          },
+        ],
+      },
     ]),
 
   async describeResources(options) {

package/src/serializer.ts

@@ -14,6 +14,7 @@ import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { emitYAML } from "@intentius/chant/yaml";
 import { isDefaultLabels, isDefaultAnnotations, type DefaultLabels, type DefaultAnnotations } from "./default-labels";
+import { isRenderedManifestEntity } from "./kustomize/rendered-entity";
 
 const require = createRequire(import.meta.url);
 
@@ -219,10 +220,10 @@ function toYAMLValue(value: unknown, entityNames: Map<Declarable, string>): unkn
 export const k8sSerializer: Serializer = {
   name: "k8s",
   rulePrefix: "WK8",
-  // The Argo CD checks are a distinct product surface this lexicon covers, and
-  // their ids are published — renaming them would break every `chant-disable
-  // ARGO001` already written (#1349).
-  extraRulePrefixes: ["ARGO"],
+  // The Argo CD and Flux checks are distinct product surfaces this lexicon
+  // covers, and their ids are published — renaming them would break every
+  // `chant-disable ARGO001` already written (#1349).
+  extraRulePrefixes: ["ARGO", "FLUX"],
 
   serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[], context?: SerializeContext): string {
     // Build reverse map: entity → name
@@ -255,6 +256,35 @@ export const k8sSerializer: Serializer = {
       if (isPropertyDeclarable(entity)) continue;
       if (isDefaultLabels(entity) || isDefaultAnnotations(entity)) continue;
 
+      // A kustomize build root's document (#1548 piece 3) is render-final:
+      // the overlay decided every field, so the props ARE the manifest and
+      // the spec-inference heuristics below (built for typed declarables)
+      // must not reshape it — a doc whose top-level fields aren't `spec`
+      // (webhooks, rules on a CRD instance) would otherwise be re-nested.
+      // It still gets the exact default-label/annotation merge every
+      // discovered resource gets, which is what stamps ownership on it.
+      if (isRenderedManifestEntity(entity)) {
+        const manifest = { ...entity.props };
+        const metadata = { ...((manifest.metadata as Record<string, unknown> | undefined) ?? {}) };
+        if (Object.keys(defaultLabelEntries).length > 0) {
+          metadata.labels = { ...defaultLabelEntries, ...((metadata.labels ?? {}) as Record<string, unknown>) };
+        }
+        if (Object.keys(defaultAnnotationEntries).length > 0) {
+          metadata.annotations = {
+            ...defaultAnnotationEntries,
+            ...((metadata.annotations ?? {}) as Record<string, unknown>),
+          };
+        }
+        manifest.metadata = metadata;
+        const yamlDoc = emitK8sManifest(manifest);
+        if (manifest.kind === "Namespace") {
+          namespaceDocs.push(yamlDoc);
+        } else {
+          otherDocs.push(yamlDoc);
+        }
+        continue;
+      }
+
       const entityType = (entity as unknown as Record<string, unknown>).entityType as string;
       const gvk = resolveGVK(entityType);
       if (!gvk) continue;

package/src/skills/chant-k8s-flux.md

@@ -0,0 +1,162 @@
+---
+skill: chant-k8s-flux
+description: Flux CD composites for GitOps reconciliation — FluxGitSource + FluxAppFor, the one-source-many-apps shape, dependsOn ordering, the FLUX rules, and the flux-reconcile deploy step
+user-invocable: true
+---
+
+# Flux CD Composites
+
+Chant authors typed infrastructure into manifests. Flux continuously reconciles those manifests into a cluster from git. These composites are the opt-in bridge — the k8s lexicon itself stays runtime-agnostic and only emits YAML; nothing here is implied unless you reach for it.
+
+## The split
+
+| Layer | Owns | In Chant |
+|---|---|---|
+| **Chant** | Authoring typed infra → manifests, committed to git | the lexicons |
+| **Flux** | Continuously reconciling those manifests (source-controller fetches, kustomize-controller applies) | `FluxGitSource` / `FluxAppFor` |
+| **Chant again** | Reading convergence back | `flux-reconcile` deploy step, `chant components status --live` |
+
+Flux never learns Chant exists — it fetches a git path and applies what it finds there. Chant's job ends at emitting the manifests and the Flux CRs that point at them.
+
+## Prerequisites
+
+The Flux controllers must be installed in the target cluster before applying any Flux CRs:
+
+```bash
+kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v2.9.1/install.yaml
+kubectl -n flux-system wait deploy --all --for=condition=Available --timeout=180s
+```
+
+(Or `flux install` / `flux bootstrap` with the Flux CLI. `flux bootstrap` also creates a `flux-system` `GitRepository` — FLUX002 knows about it, see below.)
+
+## When to use which
+
+| Composite | Use case |
+|---|---|
+| `FluxGitSource` | Declare the git repo the source-controller fetches — **once per repo** |
+| `FluxAppFor` | One `Kustomization` reconciling one path out of a declared source — once per app |
+
+---
+
+## FluxGitSource — declare the repo once
+
+```typescript
+import { FluxGitSource } from "@intentius/chant-lexicon-k8s";
+
+export const source = FluxGitSource("home-chant", {
+  url: "https://github.com/jhgaylor/home-chant",
+  branch: "main",
+});
+```
+
+`FluxGitSource(name, options)` returns `{ gitRepository }` — a single `K8s::Flux::GitRepository` in `flux-system`. Options:
+
+- **`url`** (required) — the repo the source-controller fetches.
+- **`branch`** — defaults to `"main"`. **`tag`** pins a tag instead and wins over `branch`.
+- **`interval`** — fetch interval, default `"5m"`.
+- **`secretRef`** — name of the Secret holding git credentials, for private repos.
+- **`fluxNamespace`** — where the CR lives, default `"flux-system"`.
+
+> **FLUX001** — a hand-written `GitRepository` whose spec has a `url` but no `ref` is flagged: an unset `spec.ref` falls back to the `master` branch, which on most repos no longer exists, so the source stalls with a checkout error and every Kustomization downstream stalls too. `FluxGitSource` always emits a `ref` (branch or tag), so composite output is FLUX001-clean by construction.
+
+## FluxAppFor — one Kustomization per app
+
+```typescript
+import { FluxAppFor } from "@intentius/chant-lexicon-k8s";
+
+export const hello = FluxAppFor("hello-chant", {
+  source,                          // the FluxGitSource result above
+  path: "./apps/hello-chant/k8s",
+  targetNamespace: "default",
+  dependsOn: ["cert-manager", "traefik"],
+});
+```
+
+`FluxAppFor(target, options)` returns `{ kustomization }` — a single `K8s::Flux::Kustomization`. Defaults are taken from real Flux estates, not the docs:
+
+- **`interval`** — `"10m"` (the source polls at 5m; reconcile less often than you fetch).
+- **`prune: true`** — resources that disappear from the source are deleted.
+- **`wait: true`** — the Kustomization reports Ready only when the reconciled resources are ready.
+- **`targetNamespace`** — optional; sets `spec.targetNamespace` (kustomize-controller stamps it on every reconciled resource).
+- **`timeout`**, **`suspend`**, **`serviceAccountName`** — pass-throughs for the matching spec fields.
+
+### The source option
+
+`source` accepts three shapes:
+
+```typescript
+FluxAppFor("app", { source,                         path: "./apps/app" });  // FluxGitSource result
+FluxAppFor("app", { source: "flux-system",           path: "./apps/app" });  // name of an existing GitRepository
+FluxAppFor("app", { source: { kind: "OCIRepository", name: "images" }, path: "./apps/app" });  // explicit ref
+```
+
+The first is the normal case. The second targets a source declared elsewhere — typically the bootstrap-created `flux-system` repo. The third covers `OCIRepository` / `Bucket` sources.
+
+> **FLUX002** — every `Kustomization.spec.sourceRef` must name a source the build declares (`GitRepository`, `OCIRepository`, or `Bucket`), or the kustomize-controller waits forever on an artifact that never arrives. The bootstrap-created `flux-system` `GitRepository` is exempt — it always exists on a bootstrapped cluster, the Flux analogue of ARGO002's built-in `default` project.
+
+### One source, many apps
+
+The common estate shape is **one `GitRepository` shared by many `Kustomization`s** — a multi-app repo with one Kustomization per path. A `GitRepository` per app is the mistake the composite split makes hard: declare the source once, hand its result to every `FluxAppFor`.
+
+```typescript
+const source = FluxGitSource("infra", { url: "https://github.com/acme/infra" });
+
+export const platform = FluxAppFor("platform", { source, path: "./dist/platform" });
+export const api      = FluxAppFor("api",      { source, path: "./dist/apps/api", dependsOn: ["platform"] });
+export const web      = FluxAppFor("web",      { source, path: "./dist/apps/web", dependsOn: ["platform", "api"] });
+```
+
+### dependsOn — ordering as a validated name list
+
+`dependsOn` is a plain string list rendered to `spec.dependsOn`; the Kustomization stays pending until every named Kustomization is Ready. In raw YAML those names have no referential integrity — a typo, or an entry left behind after a rename, stalls the app silently.
+
+> **FLUX003** — every `dependsOn` entry is joined against the Kustomizations the build actually declares. An entry naming nothing is a warning (not an error — estates legitimately split infra and apps across repos, so `cert-manager` may be declared by a build this one never sees). A self-referencing entry is always flagged: Flux can never satisfy it.
+
+---
+
+## Deploying — the flux-reconcile step
+
+Applying `dist/flux.yaml` with `kubectl` works. For the component model, `fluxReconcile` is the typed deploy leaf (the sibling of `argo-app`):
+
+```typescript
+import { phase, type Component } from "@intentius/chant/components/component";
+import { fluxReconcile } from "@intentius/chant-lexicon-k8s/components";
+
+export const bootstrap: Component = {
+  name: "flux-bootstrap",
+  archetype: "service",
+  dependsOn: [],
+  deploy: [
+    phase("Reconcile", [
+      fluxReconcile({
+        manifest: "dist/flux.yaml",
+        stack: "my-estate",
+        noRollback: "server-side apply keeps no previous object state; the declared source is the restore path",
+      }),
+    ]),
+  ],
+};
+```
+
+What it does:
+
+1. **Applies** the Flux CRs through the same server-side apply `kubectl-apply` uses — ownership stamping, marker-scoped prune, stack labels all identical.
+2. **Waits for Ready, sources first.** A Kustomization cannot become Ready before its GitRepository has an artifact, so gating on `source.toolkit.fluxcd.io` kinds first surfaces a wedged clone as the source's error rather than a reconciler timeout downstream. The generic `waitForReady` handles the rest of the toolkit (kstatus-conformant), with fail-fast on wedge reasons like `BuildFailed` or `UpgradeFailed` from the readiness registry.
+3. **Refuses non-Flux manifests.** If the manifest applies no Flux CR at all, the step errors — a plain manifest belongs on `kubectl-apply`, and two things applying the same resources is the failure mode worth engineering against.
+
+It is a `needs-opt-out` capability (COMP003): every step needs `noRollback: "<reason>"`, a component `rollback` phase, or a sibling safety step — same posture as `kubectl-apply`, and for the same reason.
+
+## Reading convergence back
+
+The build stamps `app.kubernetes.io/managed-by: chant` and (with `ownership` configured) `chant.intentius.io/stack: <stack>` labels on every resource. Flux applies the manifests, but the labels travel with them — so `chant components status --live` attributes the running workloads to the stack through the k8s lexicon's label-selector read, regardless of who did the applying. Flux prunes by its own labels; chant observes by its own labels; neither needs the other's.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Kustomization stuck, no artifact | Source stalled — unset `spec.ref` fell back to `master` | Pin a branch/tag (FLUX001); `FluxGitSource` does this by default |
+| Kustomization waits forever | `sourceRef` names an undeclared source | Declare it with `FluxGitSource`, or point at the bootstrap `flux-system` repo (FLUX002) |
+| App pending, dependencies "not ready" | `dependsOn` names a Kustomization that doesn't exist (typo/rename) | Fix the name (FLUX003), or confirm the other repo declares it |
+| App pending forever, no error | `dependsOn` self-reference | Remove the self-edge (FLUX003 flags it) |
+| Resources deleted unexpectedly | `prune: true` (the default) and the path stopped emitting them | Intended GitOps behavior; pass `prune: false` to opt out |
+| `flux-reconcile` step errors immediately | Manifest contains no Flux CR | Use `kubectl-apply` for plain manifests |

package/src/testdata/kustomize-root/base/deployment.yaml

@@ -0,0 +1,17 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: web
+  template:
+    metadata:
+      labels:
+        app: web
+    spec:
+      containers:
+        - name: web
+          image: nginx:1.27

package/src/testdata/kustomize-root/base/kustomization.yaml

@@ -0,0 +1,3 @@
+resources:
+  - deployment.yaml
+  - service.yaml

package/src/testdata/kustomize-root/base/service.yaml

@@ -0,0 +1,9 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: web
+spec:
+  selector:
+    app: web
+  ports:
+    - port: 80

package/src/testdata/kustomize-root/overlays/prod/kustomization.yaml

@@ -0,0 +1,6 @@
+resources:
+  - ../../base
+namePrefix: prod-
+replicas:
+  - name: web
+    count: 3

package/src/validate.ts

@@ -42,5 +42,9 @@ export async function validate(opts?: { basePath?: string }): Promise<ValidateRe
     lexiconJsonFilename: "lexicon-k8s.json",
     requiredNames: REQUIRED_NAMES,
     basePath,
+    // chant #1475 — the k8s baseline was re-baselined together with the k3s
+    // CRD work (#1605), so a release must now verify the API it ships is the
+    // reviewed one. Runs only under CHANT_RELEASE_GATE=1.
+    checkSurfaceSnapshot: true,
   });
 }