@intentius/chant 0.51.0 → 0.52.0

package/src/cli/handlers/lifecycle.ts

@@ -18,7 +18,7 @@ import {
 } from "../../lifecycle/observation-baseline";
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
-import { buildChangeSet, renderChangeSet, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
+import { buildChangeSet, renderChangeSet, renderChangeSetMarkdown, gitlabMrReport, unobservedPlanNotice, type ChangeSet } from "../../lifecycle/change-set";
 import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
 import { annotateDisruption, disruptionNotices } from "../../lifecycle/disruption";
 import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
@@ -1302,12 +1302,11 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
 
   // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
-  // shapes have no room for it) still learn the plan has a hole (#1089).
-  const unobservedCount = summarize(merged).unobserved;
-  if (unobservedCount > 0) {
-    console.error(formatWarning({
-      message: `${unobservedCount} declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.`,
-    }));
+  // shapes have no room for it) still learn the plan has a hole (#1089). The
+  // `markdown` report carries the same wording in its own body instead — a
+  // reviewer reading a comment never sees this stderr.
+  for (const notice of unobservedPlanNotice(merged)) {
+    console.error(formatWarning({ message: notice }));
   }
 
   // Same reason as above (#1665): the `--json` and `--report gitlab-mr` shapes
@@ -1324,6 +1323,14 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     return 0;
   }
 
+  // `--report markdown` emits the reviewer-facing projection (#1983) — a
+  // counts header, entries grouped and attributed to their lexicon, holes and
+  // disruption both carried in the body rather than left to stderr.
+  if (args.reportFile === "markdown") {
+    console.log(renderChangeSetMarkdown(merged));
+    return 0;
+  }
+
   if (args.json) {
     console.log(JSON.stringify(merged, null, 2));
   } else {

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

@@ -987,6 +987,102 @@ describe("runOp dispatcher", () => {
   });
 });
 
+/**
+ * chant #2003 — `--sandbox` is a global flag and `../main.ts` arms the
+ * process-wide policy latch off it for every command, so `chant run <op>
+ * --sandbox` on an Op with a `policyGate` step used to reach `loadPolicyChecks`
+ * mid-run and show the user a message written for a chant maintainer ("This is
+ * a chant bug"). At the CLI level, not on `loadPolicyChecks`: the defect was
+ * that the combination got that far, not what the refusal says.
+ */
+describe("runOp: --sandbox with a policyGate step (chant #2003)", () => {
+  const policyGateOp = (name: string) =>
+    localOp(name, [{ kind: "activity", fn: "policyGate", args: { path: "." } }]);
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadTemporalClientMock.mockReset();
+    loadChantConfigMock.mockReset();
+    resolveProfileMock.mockReset();
+    existsSyncMock.mockReset();
+    spawnChildMock.mockReset();
+  });
+
+  test("local mode → refuses before any phase runs, naming the combination", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = stderr.join("\n");
+    expect(out).toContain("policyGate");
+    expect(out).toContain("--sandbox");
+    // The message the user used to get instead.
+    expect(out).not.toContain("This is a chant bug");
+  });
+
+  test("--temporal → the same refusal, as a CLI error rather than an activity failure", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: true, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("policyGate");
+    // Refused before the project config is even loaded — nothing is scheduled.
+    expect(loadChantConfigMock).not.toHaveBeenCalled();
+    expect(loadTemporalClientMock).not.toHaveBeenCalled();
+  });
+
+  test("a policyGate nested in an effect step is found too", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([
+        localOp("gate", [
+          { kind: "effect", steps: [{ kind: "activity", fn: "policyGate", args: { path: "." } }] },
+        ]),
+      ]),
+      errors: [],
+    });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("policyGate");
+  });
+
+  test("without --sandbox the same Op is not refused", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveProfileMock.mockReturnValue({ address: "localhost:7233", namespace: "default", taskQueue: "q" });
+    existsSyncMock.mockReturnValue(false);
+    const stderr = makeStderrSpy();
+
+    // The Temporal path, so the run stops at the missing worker.ts rather than
+    // actually building a project: reaching that point proves the pre-flight
+    // let it through.
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("worker.ts not found");
+    expect(loadChantConfigMock).toHaveBeenCalled();
+  });
+
+  test("--sandbox on an Op with no policyGate step is untouched", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("hello", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const exit = await runOp({ args: makeArgs({ path: "hello", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    stderrWrite.mockRestore();
+  });
+});
+
 describe("Temporal-only subcommand guards", () => {
   const cases: Array<[string, (ctx: { args: ParsedArgs; plugins: never[]; serializers: never[] }) => Promise<number>]> = [
     ["list", runOpList],

package/src/cli/handlers/run.ts

@@ -4,8 +4,9 @@ import { createConnection } from "node:net";
 import { spawn as spawnChild, type ChildProcess } from "node:child_process";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
 import { discoverOps } from "../../op/discover";
+import type { OpConfig } from "../../op/types";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
-import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure, type StepRecord } from "../../op/local-executor";
+import { runOpLocally, findGate, findPolicyGateStep, LocalGateUnsupportedError, OpRunFailure, type StepRecord } from "../../op/local-executor";
 import { renderHuman, renderJson } from "../../op/local-output";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
@@ -561,6 +562,32 @@ function renderProgress(opName: string, history: WorkflowHistoryRaw): void {
  * live reaching an actual cloud shell-out. Erroring here is the safe minimum
  * called out on the issue; a real preview is future work.
  */
+/**
+ * Pre-flight for `chant run <op> --sandbox` on an Op containing a `policyGate`
+ * step (chant #2003). `--sandbox` is a global flag, and `../main.ts` arms the
+ * process-wide policy latch off it for every command — so the gate's
+ * `loadPolicyChecks` refuses mid-run with a message addressed to a chant
+ * maintainer ("This is a chant bug"), or, under `--temporal`, as a
+ * non-retryable activity failure inside the workflow. Neither is an answer a
+ * user can act on. Refuse here instead, before anything runs, naming the
+ * combination and what to do about it.
+ *
+ * Keyed on the flag rather than on whether the project declares
+ * `lint.policies`: the flag is what arms the latch, and a gate that builds the
+ * project in this process is a divergence from what `--sandbox` promises
+ * whether or not a policy module happens to be declared. Returns true when the
+ * caller should stop.
+ */
+function refusesPolicyGateUnderSandbox(ctx: CommandContext, config: OpConfig, opName: string): boolean {
+  if (!ctx.args.sandbox) return false;
+  if (!findPolicyGateStep(config)) return false;
+  console.error(formatError({
+    message: `Op "${opName}" has a policyGate step, which cannot run under --sandbox: the gate builds this project and imports its lint.policies in the chant process, which --sandbox forbids.`,
+    hint: "Re-run without --sandbox, or drop the policyGate step from this Op. Running the gate itself inside the sandbox boundary is tracked on chant#1157.",
+  }));
+  return true;
+}
+
 export async function runOp(ctx: CommandContext): Promise<number> {
   if (ctx.args.components && ctx.args.report) {
     console.error(formatError({
@@ -1061,6 +1088,9 @@ export async function runOpLocal(ctx: CommandContext): Promise<number> {
 
   const { config } = discovered;
 
+  // Pre-flight: --sandbox cannot cover a policyGate step (#2003).
+  if (refusesPolicyGateUnderSandbox(ctx, config, opName)) return 1;
+
   // Pre-flight: gates/schedules need a durable runtime — fail before any step.
   const gate = findGate(config);
   if (gate) {
@@ -1145,6 +1175,12 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
   }
 
   const { config } = discovered;
+
+  // Pre-flight: --sandbox cannot cover a policyGate step (#2003). Refused here
+  // too, so the durable path fails as a CLI error rather than as a
+  // non-retryable activity failure buried in workflow history.
+  if (refusesPolicyGateUnderSandbox(ctx, config, opName)) return 1;
+
   const projectPath = resolve(".");
 
   // Load config + profile

package/src/cli/main.ts

@@ -624,6 +624,8 @@ Options:
                         OR with a path arg: SARIF report destination (migrate)
                         OR '--report gitlab-mr': emit the GitLab MR plan-widget
                         JSON (lifecycle plan)
+                        OR '--report markdown': emit a reviewer-facing markdown
+                        render, holes and disruption included (lifecycle plan)
   --from <name>         Source lexicon for migrate (default: github)
   --to <name>           Target lexicon for migrate (default: gitlab)
   --emit <fmt>          Migration output format: yaml (default) or ts

package/src/lifecycle/change-set.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, test } from "vitest";
-import { buildChangeSet, renderChangeSet, summarize, gitlabMrReport } from "./change-set";
+import {
+  buildChangeSet,
+  renderChangeSet,
+  renderChangeSetMarkdown,
+  summarize,
+  gitlabMrReport,
+  unobservedPlanNotice,
+  type ChangeSet,
+  type ChangeSetEntry,
+} from "./change-set";
 import type { ResourceMetadata } from "../lexicon";
 
 const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
@@ -446,3 +455,137 @@ describe("buildChangeSet: not-observed is not absent (#1089)", () => {
     expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
   });
 });
+
+// ── Markdown report (#1983) ──────────────────────────────────────────────
+
+function entry(overrides: Partial<ChangeSetEntry> = {}): ChangeSetEntry {
+  return {
+    name: "db",
+    type: "AWS::RDS::DBInstance",
+    lexicon: "aws",
+    action: "update",
+    evidence: { declared: true, inSnapshot: true, live: true, observed: true },
+    ownership: "unknown",
+    ...overrides,
+  };
+}
+
+function set(entries: ChangeSetEntry[]): ChangeSet {
+  return { env: "prod", entries };
+}
+
+describe("unobservedPlanNotice (#1983)", () => {
+  test("empty when nothing is unobserved", () => {
+    expect(unobservedPlanNotice(set([entry({ action: "noop" })]))).toEqual([]);
+  });
+
+  test("one notice naming the count, matching the CLI's stderr wording", () => {
+    const cs = set([
+      entry({ name: "a", action: "unobserved", unobservedReason: "no-binding" }),
+      entry({ name: "b", action: "unobserved", unobservedReason: "read-failed" }),
+      entry({ name: "c", action: "noop" }),
+    ]);
+    expect(unobservedPlanNotice(cs)).toEqual([
+      "2 declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.",
+    ]);
+  });
+});
+
+describe("renderChangeSetMarkdown (#1983)", () => {
+  test("empty plan: header only, no ANSI, deterministic", () => {
+    const out = renderChangeSetMarkdown(set([]));
+    expect(out).toBe(
+      "## Plan for `prod`\n\n0 create, 0 update, 0 effect, 0 delete, 0 adopt, 0 runtime, 0 noop, 0 unobserved\n",
+    );
+    expect(out).not.toMatch(/\x1b\[/);
+  });
+
+  test("counts header and grouped sections, attributed to lexicon", () => {
+    const cs = set([
+      entry({ name: "new-bucket", type: "S3::Bucket", lexicon: "aws", action: "create", evidence: { declared: true, inSnapshot: false, live: false, observed: true } }),
+      entry({ name: "web", type: "K8s::Apps::Deployment", lexicon: "k8s", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true } }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("## Plan for `prod`");
+    expect(out).toContain("1 create, 0 update, 0 effect, 0 delete, 0 adopt, 0 runtime, 1 noop, 0 unobserved");
+    expect(out).toContain("### CREATE");
+    expect(out).toContain("- `new-bucket` (S3::Bucket) `aws`");
+    expect(out).toContain("### NOOP");
+    expect(out).toContain("- `web` (K8s::Apps::Deployment) `k8s`");
+  });
+
+  test("deltas render in a fenced block, forced path marked", () => {
+    const cs = set([
+      entry({
+        deltas: [
+          { path: "attributes.DBInstanceIdentifier", oldValue: "app-db", newValue: "app-db-2" },
+          { path: "attributes.AllocatedStorage", oldValue: 20, newValue: 40 },
+        ],
+        disruption: "destroy",
+        disruptionBecause: ["attributes.DBInstanceIdentifier"],
+        disruptionDetail: "DBInstanceIdentifier is create-only",
+      }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("**destroy**: DBInstanceIdentifier is create-only");
+    expect(out).toContain("```");
+    expect(out).toContain("! attributes.DBInstanceIdentifier: app-db → app-db-2");
+    expect(out).toContain("attributes.AllocatedStorage: 20 → 40");
+  });
+
+  test("disruption count rides the header, same as the human render", () => {
+    const cs = set([entry({ disruption: "in-place" }), entry({ name: "web", disruption: "destroy" })]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("**Disruption:** 1 in-place, 1 destroy");
+  });
+
+  test("unobserved renders both the prominent notice and its own section, same wording as the human render", () => {
+    const cs = set([
+      entry({ name: "crd-widget", action: "unobserved", unobservedReason: "no-binding", unobservedDetail: "no kubectl context for prod" }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain(
+      "> **1 declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.**",
+    );
+    expect(out).toContain("### UNOBSERVED (declared; chant could not read live state — no action proposed)");
+    expect(out).toContain("- `crd-widget`");
+    expect(out).toContain("no binding for this environment");
+    expect(out).toContain("no kubectl context for prod");
+  });
+
+  test("a clean plan (no holes) carries no unobserved notice at all", () => {
+    const out = renderChangeSetMarkdown(set([entry({ action: "noop" })]));
+    expect(out).not.toContain("could not be observed");
+    expect(out).not.toContain("UNOBSERVED");
+  });
+
+  test("effect entries render as their own line, no deltas", () => {
+    const cs = set([
+      entry({
+        name: "receipt-x",
+        action: "effect",
+        effect: "seed-admin",
+        effectReason: "receipt-absent",
+        effectDetail: "no receipt recorded yet",
+        deltas: undefined,
+      }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("- effect will fire: `seed-admin` — receipt `receipt-x`");
+    expect(out).toContain("no receipt recorded yet");
+  });
+
+  test("a group past the fold threshold collapses into <details>, a small one does not", () => {
+    const many = Array.from({ length: 25 }, (_, i) =>
+      entry({ name: `bucket-${i}`, action: "create", evidence: { declared: true, inSnapshot: false, live: false, observed: true }, deltas: undefined }),
+    );
+    const out = renderChangeSetMarkdown(set(many));
+    expect(out).toContain("<details><summary>25 entries — click to expand</summary>");
+    expect(out).toContain("</details>");
+    expect(out).toContain("- `bucket-0`");
+    expect(out).toContain("- `bucket-24`");
+
+    const few = renderChangeSetMarkdown(set(many.slice(0, 3)));
+    expect(few).not.toContain("<details>");
+  });
+});

package/src/lifecycle/change-set.ts

@@ -325,6 +325,45 @@ export function gitlabMrReport(cs: ChangeSet): GitlabMrReport {
   return { create: counts.create, update: counts.update, delete: counts.delete };
 }
 
+/**
+ * Warning a plan should print when it carries a hole — a declared entity the
+ * lexicon could not observe (#1089). The `--json` and `--report gitlab-mr`
+ * shapes have no column for `unobserved`, so both the CLI (on stderr) and the
+ * `markdown` report (in the body, since a reviewer never sees a job's stderr)
+ * read this same wording rather than drifting apart. Empty when the plan has
+ * no hole. Same discipline as {@link disruptionNotices} in `./disruption`.
+ */
+export function unobservedPlanNotice(cs: ChangeSet): string[] {
+  const count = summarize(cs).unobserved;
+  return count > 0
+    ? [
+        `${count} declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.`,
+      ]
+    : [];
+}
+
+/**
+ * Section heading text for one action group — shared between {@link renderChangeSet}
+ * and {@link renderChangeSetMarkdown} so the wording never drifts between the
+ * terminal render and the reviewer-facing one.
+ */
+function actionSectionLabel(action: ChangeAction, hasDisruption: boolean): string {
+  switch (action) {
+    case "unobserved":
+      return "UNOBSERVED (declared; chant could not read live state — no action proposed)";
+    case "runtime":
+      return "RUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate)";
+    case "effect":
+      return "EFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt)";
+    case "update":
+      return hasDisruption
+        ? "UPDATE (disruption from the lexicon that owns the spec; unknown means nobody could say, not that it is safe)"
+        : "UPDATE";
+    default:
+      return action.toUpperCase();
+  }
+}
+
 /** Human-readable render of a change set. Pure — returns a string. */
 export function renderChangeSet(cs: ChangeSet): string {
   const counts = summarize(cs);
@@ -344,17 +383,7 @@ export function renderChangeSet(cs: ChangeSet): string {
   for (const action of ACTION_ORDER) {
     const group = cs.entries.filter((e) => e.action === action);
     if (group.length === 0) continue;
-    lines.push(
-      action === "unobserved"
-        ? "\nUNOBSERVED (declared; chant could not read live state — no action proposed):"
-        : action === "runtime"
-          ? "\nRUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate):"
-          : action === "effect"
-            ? "\nEFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt):"
-            : action === "update" && disruptionParts.length > 0
-              ? "\nUPDATE (disruption from the lexicon that owns the spec; unknown means nobody could say, not that it is safe):"
-              : `\n${action.toUpperCase()}:`,
-    );
+    lines.push(`\n${actionSectionLabel(action, disruptionParts.length > 0)}:`);
     for (const e of group) {
       if (e.action === "effect") {
         lines.push(
@@ -381,6 +410,99 @@ export function renderChangeSet(cs: ChangeSet): string {
   return lines.join("\n");
 }
 
+/**
+ * Entries beyond this in one action group are collapsed into a `<details>`
+ * block in {@link renderChangeSetMarkdown} — a group's worth of rows is fine
+ * to read inline, a hundred-entry plan is not (#1983).
+ */
+const MARKDOWN_FOLD_THRESHOLD = 20;
+
+/** One entry's markdown, mirroring the rows {@link renderChangeSet} prints. */
+function renderMarkdownEntry(e: ChangeSetEntry): string[] {
+  if (e.action === "effect") {
+    return [
+      `- effect will fire: \`${e.effect ?? e.name}\` — receipt \`${e.name}\`${e.type ? ` (${e.type})` : ""}` +
+        `${e.effectDetail ? ` — ${e.effectDetail}` : ""}`,
+    ];
+  }
+  const lexicon = e.lexicon ? ` \`${e.lexicon}\`` : "";
+  const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
+  const why = e.unobservedReason
+    ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
+    : "";
+  const owner = e.runtimeOwner ? ` — owned by \`${e.runtimeOwner}\`` : "";
+  // Bolded rather than the plain-text render's bare " — destroy: ..." — a
+  // reviewer scanning a wall of "update" rows should see disruption without
+  // reading every one (#1665).
+  const disruption = e.disruption
+    ? ` — **${e.disruption}**${e.disruptionDetail ? `: ${e.disruptionDetail}` : ""}`
+    : "";
+  const lines = [`- \`${e.name}\`${e.type ? ` (${e.type})` : ""}${lexicon}${own}${why}${owner}${disruption}`];
+
+  if (e.deltas && e.deltas.length > 0) {
+    const forced = new Set(e.disruptionBecause ?? []);
+    lines.push("  ```");
+    for (const d of e.deltas) {
+      lines.push(`  ${forced.has(d.path) ? "! " : "  "}${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
+    }
+    lines.push("  ```");
+  }
+  return lines;
+}
+
+/**
+ * Markdown projection of a change set (#1983) — sized for a PR/MR comment
+ * rather than a terminal. A scannable counts header, entries grouped by
+ * action and attributed to their lexicon, deltas in a fenced block, and any
+ * group past {@link MARKDOWN_FOLD_THRESHOLD} folded into a `<details>` so a
+ * large plan doesn't bury the comment. Pure — no ANSI, no I/O — and
+ * deterministic: same entry ordering as {@link renderChangeSet}.
+ *
+ * Both a hole (#1089) and an expensive verdict (#1665) are surfaced IN the
+ * body, not left to stderr the way `--json` and `--report gitlab-mr` leave
+ * them: a reviewer reading a comment never sees the job's log, so a plan
+ * carrying either must not read as clean.
+ */
+export function renderChangeSetMarkdown(cs: ChangeSet): string {
+  const counts = summarize(cs);
+  const lines: string[] = [`## Plan for \`${cs.env}\``, "", ACTION_ORDER.map((a) => `${counts[a]} ${a}`).join(", ")];
+
+  const disruption = summarizeDisruption(cs);
+  const disruptionParts = (Object.entries(disruption) as Array<[Disruption, number]>)
+    .filter(([, n]) => n > 0)
+    .map(([level, n]) => `${n} ${level}`);
+  if (disruptionParts.length > 0) {
+    lines.push("", `**Disruption:** ${disruptionParts.join(", ")}`);
+  }
+
+  for (const notice of unobservedPlanNotice(cs)) {
+    lines.push("", `> **${notice}**`);
+  }
+
+  for (const action of ACTION_ORDER) {
+    const group = cs.entries.filter((e) => e.action === action);
+    if (group.length === 0) continue;
+
+    lines.push("", `### ${actionSectionLabel(action, disruptionParts.length > 0)}`);
+
+    const body = group.flatMap((e) => renderMarkdownEntry(e));
+    if (group.length > MARKDOWN_FOLD_THRESHOLD) {
+      lines.push(
+        "",
+        `<details><summary>${group.length} entries — click to expand</summary>`,
+        "",
+        ...body,
+        "",
+        "</details>",
+      );
+    } else {
+      lines.push("", ...body);
+    }
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
 function fmt(v: unknown): string {
   if (v === undefined) return "<unset>";
   if (typeof v === "string") return v.length > 60 ? v.slice(0, 57) + "..." : v;