@intentius/chant 0.45.0 → 0.46.0

package/src/cli/handlers/lifecycle.test.ts

@@ -53,7 +53,7 @@ vi.mock("../../config", async () => {
   };
 });
 
-const { runLifecycleDiff, runLifecyclePlan, runLifecycleSnapshot, runLifecycleShow, runLifecycleLog, runLifecycleUnknown } = await import("./lifecycle");
+const { runLifecycleDiff, runLifecyclePlan, runLifecycleSnapshot, runLifecycleShow, runLifecycleLog, runLifecycleTeardown, runLifecycleUnknown } = await import("./lifecycle");
 
 function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
   return {
@@ -1220,3 +1220,233 @@ describe("runLifecycleUnknown", () => {
     expect(stderr).toContain("log");
   });
 });
+
+describe("runLifecycleTeardown (#1222 — plan only)", () => {
+  let stdoutBuf: string[];
+  let stderrBuf: string[];
+
+  beforeEach(() => {
+    stdoutBuf = [];
+    stderrBuf = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({
+      config: { environments: ["dev", "prod"], ownership: { stack: "shop", env: "dev" } },
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const run = (overrides: Partial<ParsedArgs>, plugins: LexiconPlugin[]) =>
+    runLifecycleTeardown({
+      args: makeArgs({ command: "lifecycle", path: "teardown", ...overrides }),
+      plugins,
+      serializers: [],
+    });
+
+  test("requires an environment", async () => {
+    expect(await run({}, [])).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("Environment is required");
+  });
+
+  test("exits nonzero on an environment the project does not declare", async () => {
+    expect(await run({ extraPositional: "staging" }, [])).toBe(1);
+    const stderr = stderrBuf.join("\n");
+    expect(stderr).toContain('Unknown environment "staging"');
+    expect(stderr).toContain("dev, prod");
+  });
+
+  test("--yes executes the planned set and prints per-candidate outcomes", async () => {
+    const executeTeardown = vi.fn(async () => ({
+      outcomes: [{ name: "web", outcome: "deleted" as const }],
+    }));
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({
+        candidates: [{ name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "dev" } }],
+      }),
+      executeTeardown,
+    });
+    expect(await run({ extraPositional: "dev", yes: true }, [plugin])).toBe(0);
+    expect(executeTeardown).toHaveBeenCalledWith({
+      environment: "dev",
+      marker: { stack: "shop", env: "dev" },
+      candidates: [{ name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "dev" } }],
+    });
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("Outcomes:");
+    expect(out).toContain("deleted");
+    expect(out).toContain("1 deleted, 0 failed, 0 not prunable, 0 skipped");
+    expect(out).not.toContain("plan only");
+  });
+
+  test("--yes exits nonzero when a candidate stays failed after the retry pass", async () => {
+    const executeTeardown = vi.fn(async () => ({
+      outcomes: [{ name: "web", outcome: "failed" as const, detail: "conflict" }],
+    }));
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({
+        candidates: [{ name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "dev" } }],
+      }),
+      executeTeardown,
+    });
+    expect(await run({ extraPositional: "dev", yes: true }, [plugin])).toBe(1);
+    expect(executeTeardown).toHaveBeenCalledTimes(2); // pass + bounded retry
+    expect(stderrBuf.join("\n")).toContain("failed to delete after the retry pass");
+  });
+
+  test("--yes with a lexicon that only enumerates reports skipped, not deleted", async () => {
+    const plugin = createMockPlugin({
+      name: "gcp",
+      teardownOwned: async () => ({
+        candidates: [{ name: "bucket", type: "GCP::Storage::Bucket", marker: { stack: "shop", env: "dev" } }],
+      }),
+    });
+    expect(await run({ extraPositional: "dev", yes: true }, [plugin])).toBe(0);
+    expect(stdoutBuf.join("\n")).toContain("skipped");
+    expect(stderrBuf.join("\n")).toContain("no teardown execution in these lexicons yet");
+  });
+
+  test("--yes on a production-like environment demands --confirm-prod when not interactive", async () => {
+    const executeTeardown = vi.fn();
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({ candidates: [] }),
+      executeTeardown,
+    });
+    expect(await run({ extraPositional: "prod", yes: true }, [plugin])).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("--confirm-prod");
+    expect(executeTeardown).not.toHaveBeenCalled();
+  });
+
+  test("--yes --confirm-prod tears a production-like environment down non-interactively", async () => {
+    const executeTeardown = vi.fn(async () => ({
+      outcomes: [{ name: "web", outcome: "deleted" as const }],
+    }));
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({
+        candidates: [{ name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "prod" } }],
+      }),
+      executeTeardown,
+    });
+    expect(await run({ extraPositional: "prod", yes: true, confirmProd: true }, [plugin])).toBe(0);
+    expect(executeTeardown).toHaveBeenCalledTimes(1);
+  });
+
+  test("the prod guard never fires without --yes — planning production is safe", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({ candidates: [] }),
+    });
+    expect(await run({ extraPositional: "prod" }, [plugin])).toBe(0);
+    expect(stderrBuf.join("\n")).not.toContain("--confirm-prod");
+  });
+
+  test("--yes --json emits the execution report", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({
+        candidates: [{ name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "dev" } }],
+      }),
+      executeTeardown: async () => ({ outcomes: [{ name: "web", outcome: "deleted" as const }] }),
+    });
+    expect(await run({ extraPositional: "dev", yes: true, json: true }, [plugin])).toBe(0);
+    const parsed = JSON.parse(stdoutBuf.join("\n"));
+    expect(parsed.outcomes).toEqual([
+      {
+        lexicon: "k8s",
+        name: "web",
+        type: "K8s::Apps::Deployment",
+        marker: { stack: "shop", env: "dev" },
+        outcome: "deleted",
+      },
+    ]);
+  });
+
+  test("refuses when the project declares no ownership.stack", async () => {
+    loadChantConfigMock.mockResolvedValue({ config: { environments: ["dev"] } });
+    expect(await run({ extraPositional: "dev" }, [])).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("no ownership.stack");
+  });
+
+  test("prints the would-delete set with resource, type, and marker identity", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({
+        candidates: [
+          { name: "web", type: "K8s::Apps::Deployment", physicalId: "web-1", marker: { stack: "shop", env: "dev" } },
+        ],
+      }),
+    });
+    expect(await run({ extraPositional: "dev" }, [plugin])).toBe(0);
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("Teardown plan");
+    expect(out).toContain("plan only");
+    expect(out).toContain("web");
+    expect(out).toContain("K8s::Apps::Deployment");
+    expect(out).toContain("shop/dev");
+    expect(stderrBuf.join("\n")).toContain("re-run with --yes to execute");
+  });
+
+  test("never selects foreign-stack or foreign-env resources on the fallback path", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticObservation({
+        mine: { type: "K8s::Apps::Deployment", status: "READY", marker: { stack: "shop", env: "dev" } },
+        theirs: { type: "K8s::Apps::Deployment", status: "READY", marker: { stack: "blog", env: "dev" } },
+        prodTwin: { type: "K8s::Apps::Deployment", status: "READY", marker: { stack: "shop", env: "prod" } },
+        unmarked: { type: "K8s::Apps::Deployment", status: "READY" },
+      }),
+    });
+    expect(await run({ extraPositional: "dev" }, [plugin])).toBe(0);
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("mine");
+    expect(out).not.toContain("theirs");
+    expect(out).not.toContain("prodTwin");
+    expect(out).not.toContain("unmarked");
+  });
+
+  test("an empty would-delete set is loud, not silent", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({ candidates: [] }),
+    });
+    expect(await run({ extraPositional: "dev" }, [plugin])).toBe(0);
+    expect(stderrBuf.join("\n")).toContain("nothing would be deleted");
+  });
+
+  test("holes are surfaced loudly (#1089)", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({
+        candidates: [],
+        holes: [{ name: "crds", type: "K8s::CRD", reason: "unsupported-kind" as const, detail: "no reader" }],
+      }),
+    });
+    expect(await run({ extraPositional: "dev" }, [plugin])).toBe(0);
+    expect(stderrBuf.join("\n")).toContain("incomplete, not clean");
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("HOLES");
+    expect(out).toContain("crds");
+    expect(out).toContain("unsupported-kind");
+  });
+
+  test("--json emits the plan as JSON", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      teardownOwned: async () => ({
+        candidates: [{ name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "dev" } }],
+      }),
+    });
+    expect(await run({ extraPositional: "dev", json: true }, [plugin])).toBe(0);
+    const parsed = JSON.parse(stdoutBuf.join("\n"));
+    expect(parsed.environment).toBe("dev");
+    expect(parsed.stack).toBe("shop");
+    expect(parsed.entries).toHaveLength(1);
+  });
+});

package/src/cli/handlers/lifecycle.ts

@@ -30,7 +30,9 @@ import { discoverComponents } from "../../components/discover";
 import { cfnDeployStacks } from "./components";
 import { affectedStacks } from "../../lifecycle/affected";
 import { rollbackToRevision } from "../../lifecycle/rollback";
-import { loadChantConfig, environmentNames } from "../../config";
+import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, resolveOwnershipStack } from "../../config";
+import { unknownEnvError, isProdLikeEnvironment } from "../../env";
+import { planTeardown, executeTeardown, type TeardownPlan, type TeardownReport } from "../../lifecycle/teardown";
 import { collectBuildRootContributors } from "../plugins";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { isResourceDeclarable } from "../../declarable";
@@ -109,7 +111,7 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const declaredParams = await commandBuildParams(config.buildParams, args);
   if (!declaredParams) return 1;
   const declaredEnvNames = environmentNames(config.environments);
-  if (declaredEnvNames && !declaredEnvNames.includes(environment)) {
+  if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
     console.error(formatError({
       message: `Unknown environment "${environment}"`,
       hint: `Defined environments: ${declaredEnvNames.join(", ")}`,
@@ -1240,6 +1242,220 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * chant lifecycle teardown <environment> (#1222).
+ *
+ * Enumerates what deleting the environment would remove: every live resource
+ * carrying this project's ownership marker (managed-by + `ownership.stack`)
+ * with the requested env identity. Stateless — live markers only, no build, no
+ * snapshot. Without `--yes` nothing is deleted; with it the planned set is
+ * executed per lexicon with one bounded retry pass over failures, and every
+ * candidate's outcome is reported (deleted / failed / not-prunable / skipped —
+ * never silence). A production-like environment name additionally requires an
+ * interactive confirmation, or `--confirm-prod` non-interactively.
+ */
+export async function runLifecycleTeardown(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  const environment = args.extraPositional;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle teardown <environment>" }));
+    return 1;
+  }
+
+  const { config } = await loadChantConfig(resolve("."));
+
+  // Refuse an env the project does not declare — a typo here is the difference
+  // between tearing down `dev` and tearing down `prod`. Literal `environments`
+  // entries only (#1221's pattern entries would extend this same check).
+  const envErr = unknownEnvError(environment, config.environments);
+  if (envErr) {
+    console.error(formatError({ message: envErr }));
+    return 1;
+  }
+
+  // Teardown selects on the ownership marker; a project that stamps none has
+  // nothing to key on, and "delete what looks like mine" is not a fallback.
+  const stack = resolveOwnershipStack(config);
+  if (stack === undefined) {
+    console.error(formatError({
+      message: "This project declares no ownership.stack — teardown is marker-scoped and has nothing to select on",
+      hint: 'Set `ownership: { stack: "<name>" }` in chant.config.ts and deploy, so resources carry the marker teardown keys on.',
+    }));
+    return 1;
+  }
+
+  // The prod guard (#1222): a production-like name never falls to `--yes`
+  // alone. Interactive runs re-type the environment name; non-interactive
+  // runs say `--confirm-prod` explicitly. Checked before any live read so a
+  // refused teardown touches nothing at all.
+  if (args.yes && isProdLikeEnvironment(environment) && !args.confirmProd) {
+    if (!process.stdin.isTTY) {
+      console.error(formatError({
+        message: `"${environment}" looks like a production environment — --yes alone is not enough`,
+        hint: "Re-run with --yes --confirm-prod to tear it down non-interactively.",
+      }));
+      return 1;
+    }
+    const confirmed = await promptProdTeardown(environment);
+    if (!confirmed) {
+      console.error(formatError({ message: "Confirmation did not match — nothing was deleted." }));
+      return 1;
+    }
+  }
+
+  // #1166 — teardown is always a live read (and with --yes, a live write), so
+  // an environment's declared endpoint applies here too, unless the ambient
+  // shell already set it.
+  const readingPlugins = plugins.filter((p) => p.teardownOwned || p.describeResources || p.executeTeardown);
+  const endpointResult = applyLiveEndpoint(config.environments, environment, readingPlugins);
+  if (endpointResult.notice) console.error(formatWarning({ message: endpointResult.notice }));
+
+  let plan: TeardownPlan;
+  let report: TeardownReport | undefined;
+  try {
+    // A multi-stack project's declared stacks, for stack-shaped teardowns
+    // (aws enumerates and deletes whole CloudFormation stacks). A single-stack
+    // project passes nothing and the env-named default convention applies.
+    const deployedStacks = (config.stacks ?? []).map((s) => ({
+      name: s.name,
+      ...(s.region ? { region: s.region } : {}),
+    }));
+    plan = await planTeardown({
+      environment,
+      stack,
+      plugins,
+      ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+    });
+    if (args.yes) {
+      report = await executeTeardown({
+        environment,
+        stack,
+        plugins,
+        plan,
+        ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+      });
+    }
+  } finally {
+    endpointResult.restore();
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(report ?? plan, null, 2));
+    return report && report.outcomes.some((o) => o.outcome === "failed") ? 1 : 0;
+  }
+
+  console.log(formatBold(
+    args.yes
+      ? `Teardown — environment: ${environment}, stack: ${stack}`
+      : `Teardown plan — environment: ${environment}, stack: ${stack} (plan only — nothing is deleted)`,
+  ));
+
+  if (plan.entries.length === 0) {
+    console.error(formatWarning({
+      message: `No live resources carry the marker stack "${stack}" + env "${environment}" — nothing would be deleted.` +
+        (plan.holes.length > 0
+          ? " But this plan has holes (below) — parts of the estate could not be read, so \"nothing\" is a claim about what was readable, not about the environment."
+          : " If this environment is deployed, check that its resources were stamped (ownership marking on, and the env identity resolved at build time)."),
+    }));
+  } else {
+    console.log(`\n${plan.entries.length} resource(s) would be deleted:`);
+    console.log("RESOURCE".padEnd(28) + "TYPE".padEnd(32) + "MARKER".padEnd(24) + "LEXICON");
+    console.log("-".repeat(96));
+    for (const entry of plan.entries) {
+      console.log(
+        entry.name.padEnd(28) +
+        entry.type.padEnd(32) +
+        `${entry.marker.stack}/${entry.marker.env}`.padEnd(24) +
+        entry.lexicon,
+      );
+    }
+  }
+
+  // Holes are loud (#1089): an unreadable kind is unknown, not absent, and the
+  // execution half must not treat this plan as the whole delete set.
+  if (plan.holes.length > 0) {
+    console.error(formatWarning({
+      message: `${plan.holes.length} hole(s) — resources chant may own but could not read. This plan is incomplete, not clean.`,
+    }));
+    console.log(formatBold("\nHOLES (stamped kinds the read could not cover):"));
+    for (const hole of plan.holes) {
+      console.log(`  ? ${hole.lexicon}: ${hole.name}${hole.type ? ` (${hole.type})` : ""} — ${hole.reason}${hole.detail ? `: ${hole.detail}` : ""}`);
+    }
+  }
+
+  if (plan.skipped.length > 0) {
+    console.error(formatWarning({
+      message: `Skipped (no teardown enumeration and no describeResources): ${plan.skipped.join(", ")} — those lexicons' resources are not in this plan.`,
+    }));
+  }
+
+  if (!report) {
+    console.error(formatWarning({ message: "Plan only — re-run with --yes to execute." }));
+    return 0;
+  }
+
+  if (report.outcomes.length > 0) {
+    console.log(formatBold("\nOutcomes:"));
+    console.log("RESOURCE".padEnd(28) + "OUTCOME".padEnd(14) + "LEXICON".padEnd(12) + "DETAIL");
+    console.log("-".repeat(96));
+    for (const o of report.outcomes) {
+      console.log(
+        o.name.padEnd(28) +
+        o.outcome.padEnd(14) +
+        o.lexicon.padEnd(12) +
+        (o.detail ?? "") +
+        (o.retried ? " (after retry)" : ""),
+      );
+    }
+  }
+
+  const counts = { deleted: 0, failed: 0, "not-prunable": 0, skipped: 0 };
+  for (const o of report.outcomes) counts[o.outcome]++;
+  console.log(
+    `\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ${counts.skipped} skipped`,
+  );
+
+  if (report.unimplemented.length > 0) {
+    console.error(formatWarning({
+      message: `Not executed (no teardown execution in these lexicons yet): ${report.unimplemented.join(", ")} — their candidates are reported as skipped, not deleted.`,
+    }));
+  }
+  if (plan.holes.length > 0) {
+    console.error(formatWarning({
+      message: "This teardown ran over an incomplete plan (holes above) — the environment cannot be called clean.",
+    }));
+  }
+  if (counts.failed > 0) {
+    console.error(formatError({
+      message: `${counts.failed} candidate(s) failed to delete after the retry pass — see the outcomes above.`,
+    }));
+    return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * The interactive half of the prod guard: the operator re-types the
+ * environment name. Anything else — including EOF — refuses.
+ */
+async function promptProdTeardown(environment: string): Promise<boolean> {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolvePrompt) => {
+    rl.question(
+      `"${environment}" looks like a production environment. Type the environment name to confirm teardown: `,
+      (answer) => {
+        resolvePrompt(answer.trim() === environment);
+        rl.close();
+      },
+    );
+    // EOF (Ctrl-D) closes the interface without answering — that is a refusal.
+    rl.on("close", () => resolvePrompt(false));
+  });
+}
+
 /**
  * chant lifecycle log [environment]
  */
@@ -1268,7 +1484,7 @@ export async function runLifecycleLog(ctx: CommandContext): Promise<number> {
 export async function runLifecycleUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown state subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
-    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle log",
+    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle teardown, chant lifecycle log",
   }));
   return 1;
 }

package/src/cli/handlers/search.ts

@@ -9,7 +9,7 @@ import { discover } from "../../discovery/index";
 import { observeResources } from "../../lifecycle/observe";
 import { replaySnapshots, hasSnapshot } from "../../lifecycle/replay";
 import type { LiveObservation } from "../../graph-ir";
-import { loadChantConfig } from "../../config";
+import { loadChantConfig, matchesDeclaredEnvironment } from "../../config";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { formatError, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
@@ -89,7 +89,10 @@ export async function runSearch(ctx: CommandContext): Promise<number> {
       }));
       return 1;
     }
-    if (config.environments && !config.environments.includes(environment)) {
+    // Membership via matchesDeclaredEnvironment (#1221): handles `{ name,
+    // endpoint }` entries (#1166) — a plain `.includes` never matched those —
+    // and glob-pattern entries like `"pr-*"`.
+    if (config.environments && config.environments.length > 0 && !matchesDeclaredEnvironment(config.environments, environment)) {
       console.error(formatError({ message: `Unknown environment "${environment}"` }));
       return 1;
     }

package/src/cli/main.ts

@@ -23,7 +23,7 @@ import { runCarveAdvise, runCarveUnknown } from "./handlers/carve";
 import { runCarveEmit } from "./handlers/carve-emit";
 import { runCarveBridge } from "./handlers/carve-bridge";
 import { runCarveApply } from "./handlers/carve-apply";
-import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
+import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsUnknown } from "./handlers/components";
 import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
@@ -78,6 +78,8 @@ const BOOLEAN_FLAGS = new Set([
   "--fold",
   "--no-fold",
   "--sandbox",
+  "--yes",
+  "--confirm-prod",
 ]);
 
 /**
@@ -228,6 +230,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.emit = args[++i];
     } else if (arg === "--dry-run") {
       result.dryRun = true;
+    } else if (arg === "--yes") {
+      result.yes = true;
+    } else if (arg === "--confirm-prod") {
+      result.confirmProd = true;
     } else if (arg === "--strict") {
       result.strict = true;
     } else if (arg === "--validate") {
@@ -484,6 +490,10 @@ Lifecycle (alias: lc):
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
+  lifecycle teardown <env>  Plan what deleting the environment would remove —
+                            marker-scoped (this project's stack + env); --yes
+                            executes the plan (production-like names also need
+                            --confirm-prod, or an interactive confirmation)
   lifecycle log [env]       History of lifecycle snapshots
 
 Component release ledger + status:
@@ -780,6 +790,7 @@ const registry: CommandDef[] = [
   { name: "lifecycle rollback", handler: runLifecycleRollback },
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
+  { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
 
   // Component release ledger + status surface (#568, epic #551)

package/src/cli/registry.ts

@@ -85,6 +85,13 @@ export interface ParsedArgs {
   namespace?: string;
   /** `chant lifecycle rollback --dry-run` — compute the rollback delta and print it; open no PR, push nothing, leave no branch. */
   dryRun?: boolean;
+  /** `chant lifecycle teardown <env> --yes` — execute the planned deletion
+   * (#1222). Without it the command plans and stops. */
+  yes?: boolean;
+  /** `chant lifecycle teardown <env> --yes --confirm-prod` — the non-interactive
+   * form of the extra confirmation a production-like environment name demands
+   * (#1222). Meaningless without `--yes`. */
+  confirmProd?: boolean;
   /** `chant import --verbatim` — keep server-defaulted fields in live import */
   verbatim?: boolean;
   /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */

package/src/codegen/lexicon-regen.ts

@@ -25,6 +25,7 @@
 import { existsSync, readFileSync, writeFileSync, readdirSync, type Dirent } from "fs";
 import { join } from "path";
 import { execSync } from "child_process";
+import { SNAPSHOT_UPDATE_ENV } from "./validate";
 import {
   extractSurface,
   diffSurface,
@@ -114,6 +115,17 @@ export interface RegenOptions {
    *   sha256:<64-hex-chars>  <relative-path-to-spec-file>
    */
   pinnedDigestPath?: string;
+  /**
+   * This run is about to rewrite the baseline snapshot (#1825).
+   *
+   * The `validate` step runs with {@link SNAPSHOT_UPDATE_ENV} set so its
+   * `surface-matches-snapshot` check is skipped. A lexicon whose snapshot gate
+   * runs in `"always"` mode (#1475) fails validate on a stale baseline, and a
+   * stale baseline is exactly what a re-baseline starts from — without this
+   * exemption the documented update flow deadlocks. Every other validate check
+   * still gates the run, so a broken generate cannot be baselined.
+   */
+  updatingSnapshot?: boolean;
 }
 
 // ── Pipeline ──────────────────────────────────────────────────────────
@@ -132,6 +144,7 @@ export async function regenLexicon(opts: RegenOptions): Promise<RegenResult> {
     skipBuild = false,
     skipLint = false,
     skipExamples = true,
+    updatingSnapshot = false,
   } = opts;
 
   const failures: RegenFailure[] = [];
@@ -177,7 +190,12 @@ export async function regenLexicon(opts: RegenOptions): Promise<RegenResult> {
   }
 
   // Step 4: validate
-  const validateFail = runScript(lexiconDir, "validate", process.env, verbose);
+  // A re-baseline run is exempt from the surface-matches-snapshot check only
+  // (#1825) — see RegenOptions.updatingSnapshot.
+  const validateEnv: NodeJS.ProcessEnv = updatingSnapshot
+    ? { ...process.env, [SNAPSHOT_UPDATE_ENV]: "1" }
+    : process.env;
+  const validateFail = runScript(lexiconDir, "validate", validateEnv, verbose);
   if (validateFail) {
     failures.push(validateFail);
   }

package/src/codegen/validate.test.ts

@@ -182,4 +182,37 @@ describe("surface snapshot gate (#1473)", () => {
     const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
     expect(check?.ok).toBe(false);
   });
+
+  test("an update run skips the staleness check it is about to fix (#1825)", async () => {
+    // `--update-snapshot` sets CHANT_SNAPSHOT_UPDATE for its validate run.
+    // Without this, an "always" gate deadlocks the documented re-baseline flow:
+    // validate fails on the stale snapshot, and the update writes only after a
+    // green validate.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: [],
+      basePath: fixture({ snapshot: stale }),
+      checkSurfaceSnapshot: "always",
+      env: { CHANT_SNAPSHOT_UPDATE: "1" },
+    });
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.success).toBe(true);
+  });
+
+  test("an update run is exempt from the staleness check and nothing else", async () => {
+    // A failing check other than surface-matches-snapshot must still refuse
+    // the run, so a broken generate cannot be baselined.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: ["NotThere"],
+      basePath: fixture({ snapshot: stale }),
+      checkSurfaceSnapshot: "always",
+      env: { CHANT_SNAPSHOT_UPDATE: "1" },
+    });
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.checks.find((c) => c.name === "required-names")?.ok).toBe(false);
+    expect(result.success).toBe(false);
+  });
 });