gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

package/src/resources/extensions/gsd/tests/deep-project-setup-policy.test.ts

@@ -0,0 +1,144 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import {
+  resolveDeepProjectSetupState,
+} from "../deep-project-setup-policy.ts";
+import type { GSDPreferences } from "../preferences.ts";
+
+const deepPrefs = { planning_depth: "deep" } as GSDPreferences;
+
+const validProject = readFileSync(
+  new URL("../schemas/__fixtures__/valid-project.md", import.meta.url),
+  "utf-8",
+);
+const validRequirements = readFileSync(
+  new URL("../schemas/__fixtures__/valid-requirements.md", import.meta.url),
+  "utf-8",
+);
+
+function makeBase(): string {
+  const base = join(tmpdir(), `gsd-deep-policy-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function writeReadyProject(base: string): void {
+  writeFileSync(
+    join(base, ".gsd", "PREFERENCES.md"),
+    "---\nplanning_depth: deep\nworkflow_prefs_captured: true\n---\n",
+  );
+  writeFileSync(join(base, ".gsd", "PROJECT.md"), validProject);
+  writeFileSync(join(base, ".gsd", "REQUIREMENTS.md"), validRequirements);
+  mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+}
+
+function writeDecision(base: string, value: Record<string, unknown> | string): void {
+  mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "runtime", "research-decision.json"),
+    typeof value === "string" ? value : JSON.stringify(value),
+  );
+}
+
+function readDecision(base: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(base, ".gsd", "runtime", "research-decision.json"), "utf-8"));
+}
+
+function writeAllDimensionBlockers(base: string): void {
+  mkdirSync(join(base, ".gsd", "research"), { recursive: true });
+  for (const dimension of ["STACK", "FEATURES", "ARCHITECTURE", "PITFALLS"]) {
+    writeFileSync(join(base, ".gsd", "research", `${dimension}-BLOCKER.md`), "# blocked\n");
+  }
+}
+
+test("deep setup policy: skip decision wins over stale research blockers", () => {
+  const base = makeBase();
+  try {
+    writeReadyProject(base);
+    writeDecision(base, { decision: "skip", source: "workflow-preferences" });
+    writeAllDimensionBlockers(base);
+
+    const state = resolveDeepProjectSetupState(deepPrefs, base);
+    assert.deepEqual({ status: state.status, stage: state.stage }, { status: "complete", stage: null });
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("deep setup policy: legacy workflow research default normalizes to skip", () => {
+  const base = makeBase();
+  try {
+    writeReadyProject(base);
+    writeDecision(base, { decision: "research", source: "workflow-preferences" });
+    writeAllDimensionBlockers(base);
+
+    const state = resolveDeepProjectSetupState(deepPrefs, base);
+    assert.deepEqual({ status: state.status, stage: state.stage }, { status: "complete", stage: null });
+    const decision = readDecision(base);
+    assert.equal(decision.decision, "skip");
+    assert.equal(decision.source, "workflow-preferences");
+    assert.equal(decision.previous_source, "workflow-preferences");
+    assert.equal(decision.reason, "legacy-workflow-research-default");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("deep setup policy: missing and malformed markers repair to default skip", () => {
+  const missingBase = makeBase();
+  const malformedBase = makeBase();
+  try {
+    writeReadyProject(missingBase);
+    const missingState = resolveDeepProjectSetupState(deepPrefs, missingBase);
+    assert.deepEqual({ status: missingState.status, stage: missingState.stage }, { status: "complete", stage: null });
+    assert.equal(readDecision(missingBase).reason, "missing-default-repair");
+
+    writeReadyProject(malformedBase);
+    writeDecision(malformedBase, "{");
+    const malformedState = resolveDeepProjectSetupState(deepPrefs, malformedBase);
+    assert.deepEqual({ status: malformedState.status, stage: malformedState.stage }, { status: "complete", stage: null });
+    assert.equal(readDecision(malformedBase).reason, "malformed-default-repair");
+  } finally {
+    rmSync(missingBase, { recursive: true, force: true });
+    rmSync(malformedBase, { recursive: true, force: true });
+  }
+});
+
+test("deep setup policy: explicit research can dispatch, block, or complete", () => {
+  const pendingBase = makeBase();
+  const blockedBase = makeBase();
+  const completeBase = makeBase();
+  try {
+    writeReadyProject(pendingBase);
+    writeDecision(pendingBase, { decision: "research", source: "research-decision" });
+    const pending = resolveDeepProjectSetupState(deepPrefs, pendingBase);
+    assert.deepEqual({ status: pending.status, stage: pending.stage }, { status: "pending", stage: "project-research" });
+
+    writeReadyProject(blockedBase);
+    writeDecision(blockedBase, { decision: "research", source: "user" });
+    writeAllDimensionBlockers(blockedBase);
+    const blocked = resolveDeepProjectSetupState(deepPrefs, blockedBase);
+    assert.deepEqual({ status: blocked.status, stage: blocked.stage }, { status: "blocked", stage: "project-research" });
+
+    writeReadyProject(completeBase);
+    writeDecision(completeBase, { decision: "research", source: "research-decision" });
+    mkdirSync(join(completeBase, ".gsd", "research"), { recursive: true });
+    for (const name of ["STACK.md", "FEATURES.md", "ARCHITECTURE.md"]) {
+      writeFileSync(join(completeBase, ".gsd", "research", name), "# done\n");
+    }
+    writeFileSync(join(completeBase, ".gsd", "research", "PITFALLS-BLOCKER.md"), "# blocked\n");
+    const complete = resolveDeepProjectSetupState(deepPrefs, completeBase);
+    assert.deepEqual({ status: complete.status, stage: complete.stage }, { status: "complete", stage: null });
+    assert.equal(existsSync(join(completeBase, ".gsd", "runtime", "research-project-inflight")), false);
+  } finally {
+    rmSync(pendingBase, { recursive: true, force: true });
+    rmSync(blockedBase, { recursive: true, force: true });
+    rmSync(completeBase, { recursive: true, force: true });
+  }
+});
+

package/src/resources/extensions/gsd/tests/eval-review-schema.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Unit tests for the EVAL-REVIEW frontmatter schema and parser.
+ *
+ * Schema is the single source of truth for the machine-readable contract
+ * between the auditor agent (writes EVAL-REVIEW.md) and downstream
+ * consumers (`/gsd ship` pre-warning, future `/gsd eval-fix`). Regex over
+ * LLM prose is explicitly forbidden — every consumer reads the validated
+ * frontmatter only.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  EvalReviewFrontmatter,
+  computeOverallScore,
+  deriveCounts,
+  extractFrontmatterRaw,
+  parseEvalReviewFrontmatter,
+} from "../eval-review-schema.js";
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────────
+
+function buildFrontmatterText(overrides: Record<string, string> = {}): string {
+  const fields: Record<string, string> = {
+    schema: "eval-review/v1",
+    verdict: "PRODUCTION_READY",
+    coverage_score: "85",
+    infrastructure_score: "80",
+    overall_score: "83",
+    generated: "2026-04-28T14:00:00Z",
+    slice: "S07",
+    milestone: "M001-eh88as",
+    ...overrides,
+  };
+  const lines = ["---"];
+  for (const [k, v] of Object.entries(fields)) lines.push(`${k}: ${v}`);
+  lines.push("gaps: []");
+  lines.push("counts:");
+  lines.push("  blocker: 0");
+  lines.push("  major: 0");
+  lines.push("  minor: 0");
+  lines.push("---");
+  lines.push("");
+  lines.push("# Free-form body — never parsed");
+  return lines.join("\n");
+}
+
+const HAPPY_PATH_FRONTMATTER = [
+  "---",
+  "schema: eval-review/v1",
+  "verdict: PRODUCTION_READY",
+  "coverage_score: 78",
+  "infrastructure_score: 92",
+  "overall_score: 84",
+  "generated: 2026-04-28T14:00:00Z",
+  "slice: S07",
+  "milestone: M001-eh88as",
+  "gaps:",
+  "  - id: G01",
+  "    dimension: observability",
+  "    severity: major",
+  "    description: \"No structured trace ID propagation between LLM call and post-processing.\"",
+  "    evidence: \"src/llm/call.ts:42 logs latency only; no traceId emitted to sink.\"",
+  "    suggested_fix: \"Pass ctx.traceId into emitLatencyMetric() and persist alongside the latency event.\"",
+  "counts:",
+  "  blocker: 0",
+  "  major: 1",
+  "  minor: 0",
+  "---",
+  "",
+  "# Detailed analysis",
+  "Free-form prose body. Never parsed.",
+].join("\n");
+
+// ─── extractFrontmatterRaw ────────────────────────────────────────────────────
+
+describe("extractFrontmatterRaw", () => {
+  it("returns the YAML content between --- delimiters", () => {
+    const result = extractFrontmatterRaw("---\nfoo: bar\n---\nbody");
+    assert.deepEqual(result, { yaml: "foo: bar" });
+  });
+
+  it("errors when the first line is not ---", () => {
+    const result = extractFrontmatterRaw("foo: bar\n---\nbody");
+    assert.ok("error" in result);
+  });
+
+  it("errors when no closing --- is found", () => {
+    const result = extractFrontmatterRaw("---\nfoo: bar\nbody");
+    assert.ok("error" in result);
+  });
+
+  it("handles CRLF line endings", () => {
+    const result = extractFrontmatterRaw("---\r\nfoo: bar\r\n---\r\nbody");
+    assert.deepEqual(result, { yaml: "foo: bar" });
+  });
+});
+
+// ─── parseEvalReviewFrontmatter — happy path ──────────────────────────────────
+
+describe("parseEvalReviewFrontmatter — happy path", () => {
+  it("parses a valid frontmatter into typed data", () => {
+    const result = parseEvalReviewFrontmatter(HAPPY_PATH_FRONTMATTER);
+    assert.equal(result.ok, true);
+    if (result.ok) {
+      assert.equal(result.data.verdict, "PRODUCTION_READY");
+      assert.equal(result.data.coverage_score, 78);
+      assert.equal(result.data.infrastructure_score, 92);
+      assert.equal(result.data.gaps.length, 1);
+      assert.equal(result.data.gaps[0]!.id, "G01");
+      assert.equal(result.data.gaps[0]!.dimension, "observability");
+      assert.equal(result.data.gaps[0]!.severity, "major");
+    }
+  });
+
+  it("ignores the body content entirely (body content must not be parsed)", () => {
+    const withProseBody = HAPPY_PATH_FRONTMATTER + "\n\n## Gap Analysis\n- some prose bullet that isn't a real gap";
+    const result = parseEvalReviewFrontmatter(withProseBody);
+    assert.equal(result.ok, true);
+    if (result.ok) {
+      assert.equal(result.data.gaps.length, 1, "body bullets must not be confused with frontmatter gaps");
+    }
+  });
+
+  it("ignores tables in the body (regression: body content must not be parsed)", () => {
+    const withTable = HAPPY_PATH_FRONTMATTER + "\n\n| dim | sev |\n|---|---|\n| metrics | major |\n";
+    const result = parseEvalReviewFrontmatter(withTable);
+    assert.equal(result.ok, true);
+  });
+
+  it("ignores numbered lists in the body (regression: body content must not be parsed)", () => {
+    const withNumbered = HAPPY_PATH_FRONTMATTER + "\n\n## Gaps\n1. first numbered\n2. second numbered\n";
+    const result = parseEvalReviewFrontmatter(withNumbered);
+    assert.equal(result.ok, true);
+  });
+});
+
+// ─── parseEvalReviewFrontmatter — schema violations ───────────────────────────
+
+describe("parseEvalReviewFrontmatter — schema violations", () => {
+  it("rejects an unknown verdict literal", () => {
+    const fm = buildFrontmatterText({ verdict: "MOSTLY_OK" });
+    const result = parseEvalReviewFrontmatter(fm);
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.ok(result.pointer.includes("verdict"), `pointer should reference verdict, got ${result.pointer}`);
+    }
+  });
+
+  it("rejects coverage_score above 100", () => {
+    const fm = buildFrontmatterText({ coverage_score: "101" });
+    const result = parseEvalReviewFrontmatter(fm);
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.ok(result.pointer.includes("coverage_score"));
+    }
+  });
+
+  it("rejects negative infrastructure_score", () => {
+    const fm = buildFrontmatterText({ infrastructure_score: "-1" });
+    const result = parseEvalReviewFrontmatter(fm);
+    assert.equal(result.ok, false);
+  });
+
+  it("rejects gap severity outside the allowed enum", () => {
+    const raw = HAPPY_PATH_FRONTMATTER.replace("severity: major", "severity: critical");
+    const result = parseEvalReviewFrontmatter(raw);
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.ok(result.pointer.includes("severity") || result.pointer.includes("gaps"));
+    }
+  });
+
+  it("rejects a gap id that does not match /^G\\d+$/", () => {
+    const raw = HAPPY_PATH_FRONTMATTER.replace("id: G01", "id: gap-one");
+    const result = parseEvalReviewFrontmatter(raw);
+    assert.equal(result.ok, false);
+  });
+
+  it("rejects a slice id that does not match /^S\\d+$/", () => {
+    const fm = buildFrontmatterText({ slice: "../etc/passwd" });
+    const result = parseEvalReviewFrontmatter(fm);
+    assert.equal(result.ok, false);
+  });
+
+  it("rejects a wrong schema version literal", () => {
+    const fm = buildFrontmatterText({ schema: "eval-review/v0" });
+    const result = parseEvalReviewFrontmatter(fm);
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.ok(result.pointer.includes("schema"));
+    }
+  });
+});
+
+// ─── parseEvalReviewFrontmatter — structural failures ─────────────────────────
+
+describe("parseEvalReviewFrontmatter — structural failures", () => {
+  it("errors on a body-only file with no frontmatter", () => {
+    const result = parseEvalReviewFrontmatter("# Just a body, no frontmatter");
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.equal(result.pointer, "/");
+    }
+  });
+
+  it("errors on malformed YAML inside the frontmatter block", () => {
+    const result = parseEvalReviewFrontmatter("---\nfoo: : bar\n---\n");
+    assert.equal(result.ok, false);
+    if (!result.ok) {
+      assert.ok(result.error.toLowerCase().includes("yaml"));
+    }
+  });
+
+  it("errors when the closing --- is missing", () => {
+    const result = parseEvalReviewFrontmatter("---\nfoo: bar\nno closing");
+    assert.equal(result.ok, false);
+  });
+});
+
+// ─── computeOverallScore ──────────────────────────────────────────────────────
+
+describe("computeOverallScore", () => {
+  it("applies the 60/40 weighting", () => {
+    // 100 * 0.6 + 0 * 0.4 = 60
+    assert.equal(computeOverallScore(100, 0), 60);
+    // 0 * 0.6 + 100 * 0.4 = 40
+    assert.equal(computeOverallScore(0, 100), 40);
+    // 78 * 0.6 + 92 * 0.4 = 46.8 + 36.8 = 83.6 → 84
+    assert.equal(computeOverallScore(78, 92), 84);
+  });
+
+  it("rounds to the nearest integer", () => {
+    // 50 * 0.6 + 50 * 0.4 = 50 (exact)
+    assert.equal(computeOverallScore(50, 50), 50);
+    // 51 * 0.6 + 50 * 0.4 = 30.6 + 20 = 50.6 → 51
+    assert.equal(computeOverallScore(51, 50), 51);
+  });
+
+  it("clamps to 0..100 range when inputs are at extremes", () => {
+    assert.equal(computeOverallScore(0, 0), 0);
+    assert.equal(computeOverallScore(100, 100), 100);
+  });
+
+  it("clamps out-of-range inputs to MAX_SCORE (defense-in-depth for callers that bypass the schema)", () => {
+    assert.equal(computeOverallScore(150, 200), 100);
+    assert.equal(computeOverallScore(101, 100), 100);
+  });
+
+  it("clamps negative inputs to MIN_SCORE", () => {
+    assert.equal(computeOverallScore(-50, -50), 0);
+    assert.equal(computeOverallScore(-1, 0), 0);
+  });
+});
+
+// ─── deriveCounts ─────────────────────────────────────────────────────────────
+
+describe("deriveCounts", () => {
+  it("returns zero counts for an empty gap list", () => {
+    assert.deepEqual(deriveCounts([]), { blocker: 0, major: 0, minor: 0 });
+  });
+
+  it("counts gaps by severity", () => {
+    const gaps = [
+      { id: "G01", dimension: "tests" as const, severity: "blocker" as const, description: "x", evidence: "x", suggested_fix: "x" },
+      { id: "G02", dimension: "tests" as const, severity: "major" as const, description: "x", evidence: "x", suggested_fix: "x" },
+      { id: "G03", dimension: "tests" as const, severity: "major" as const, description: "x", evidence: "x", suggested_fix: "x" },
+      { id: "G04", dimension: "tests" as const, severity: "minor" as const, description: "x", evidence: "x", suggested_fix: "x" },
+    ];
+    assert.deepEqual(deriveCounts(gaps), { blocker: 1, major: 2, minor: 1 });
+  });
+});
+
+// ─── Schema export — sanity ───────────────────────────────────────────────────
+
+describe("EvalReviewFrontmatter schema", () => {
+  it("is exported as a TypeBox object schema", () => {
+    assert.ok(EvalReviewFrontmatter);
+    assert.equal(typeof EvalReviewFrontmatter, "object");
+  });
+});

package/src/resources/extensions/gsd/tests/git-checkpoint.test.ts

@@ -26,6 +26,15 @@ function createTempRepo(): string {
 }
 
 describe("git-checkpoint rollback", () => {
+  it("skips checkpoint creation in a git repo without commits", (t) => {
+    const repo = mkdtempSync(join(tmpdir(), "ckpt-unborn-"));
+    t.after(() => rmSync(repo, { recursive: true, force: true }));
+    git(["init"], repo);
+
+    const sha = createCheckpoint(repo, "unit-unborn");
+    assert.equal(sha, null, "unborn repos do not have a checkpointable HEAD");
+  });
+
   it("rolls back to checkpoint on checked-out branch", (t) => {
     const repo = createTempRepo();
     t.after(() => rmSync(repo, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/gsd-home.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Tests for gsdHome() — GSD home directory resolution.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+describe("gsdHome", () => {
+  let savedGsdHome: string | undefined;
+  let gsdHome: () => string;
+
+  beforeEach(async () => {
+    savedGsdHome = process.env.GSD_HOME;
+    const mod = await import("../gsd-home.js");
+    gsdHome = mod.gsdHome;
+  });
+
+  afterEach(() => {
+    if (savedGsdHome !== undefined) {
+      process.env.GSD_HOME = savedGsdHome;
+    } else {
+      delete process.env.GSD_HOME;
+    }
+  });
+
+  it("returns ~/.gsd by default", () => {
+    delete process.env.GSD_HOME;
+    assert.equal(gsdHome(), join(homedir(), ".gsd"));
+  });
+
+  it("uses GSD_HOME env var when set", () => {
+    process.env.GSD_HOME = "/custom/gsd/home";
+    // resolve() normalizes to platform absolute path on Windows
+    assert.equal(gsdHome(), resolve("/custom/gsd/home"));
+  });
+
+  it("returns a non-empty string", () => {
+    assert.ok(gsdHome().length > 0);
+  });
+});

package/src/resources/extensions/gsd/tests/has-pending-deep-stage.test.ts

@@ -0,0 +1,98 @@
+// gsd-2 / Deep planning mode — Regression coverage for hasPendingDeepStage()
+// being exported and consumed by the showSmartEntry deep-mode kickoff branch.
+//
+// Context: PR #5094 wires a deep-mode branch into showSmartEntry that calls
+// hasPendingDeepStage() to decide whether to hand off to startAutoDetached().
+// Without this guard, /gsd new-project --deep set the planning_depth flag but
+// never actually triggered the staged interview because showSmartEntry fell
+// straight through to the standard milestone wizard. These tests pin the
+// exported contract so the kickoff branch can rely on it.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { hasPendingDeepStage } from "../auto-dispatch.ts";
+import type { GSDPreferences } from "../preferences.ts";
+import { loadEffectiveGSDPreferences } from "../preferences.ts";
+
+function makeBase(): string {
+  const base = join(tmpdir(), `gsd-deep-pending-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+const lightPrefs: GSDPreferences = { planning_depth: "light" } as GSDPreferences;
+const deepPrefs: GSDPreferences = { planning_depth: "deep" } as GSDPreferences;
+
+test("hasPendingDeepStage: returns false when prefs is undefined (light by omission)", () => {
+  const base = makeBase();
+  try {
+    assert.equal(hasPendingDeepStage(undefined, base), false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("hasPendingDeepStage: returns false in light mode regardless of artifacts", () => {
+  const base = makeBase();
+  try {
+    assert.equal(hasPendingDeepStage(lightPrefs, base), false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("hasPendingDeepStage: returns true in deep mode when nothing has been captured", () => {
+  // Fresh project — no PREFERENCES.md frontmatter, no PROJECT.md, no
+  // REQUIREMENTS.md, no research-decision marker. Every gate is pending.
+  const base = makeBase();
+  try {
+    assert.equal(hasPendingDeepStage(deepPrefs, base), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("hasPendingDeepStage: returns true in deep mode when only some gates pass", () => {
+  // workflow-preferences captured but PROJECT.md still missing.
+  const base = makeBase();
+  try {
+    writeFileSync(
+      join(base, ".gsd", "PREFERENCES.md"),
+      "---\nplanning_depth: deep\nworkflow_prefs_captured: true\n---\n",
+    );
+    assert.equal(hasPendingDeepStage(deepPrefs, base), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// Regression test for the bug found while debugging /gsd new-project --deep:
+// `planning_depth` was missing from KNOWN_PREFERENCE_KEYS, validatePreferences,
+// and mergePreferences, so it was stripped on every load. The deep-mode flow
+// silently never triggered because every dispatch saw planning_depth: undefined.
+test("loadEffectiveGSDPreferences: planning_depth survives the validate + merge pipeline", () => {
+  const base = makeBase();
+  try {
+    writeFileSync(
+      join(base, ".gsd", "PREFERENCES.md"),
+      "---\nplanning_depth: deep\n---\n",
+    );
+    const loaded = loadEffectiveGSDPreferences(base);
+    assert.equal(
+      loaded?.preferences?.planning_depth,
+      "deep",
+      "planning_depth must survive load — see KNOWN_PREFERENCE_KEYS, validatePreferences, mergePreferences",
+    );
+    // Cross-check: the dispatch helper reads loaded.preferences, so it must
+    // see the same value. If planning_depth gets stripped anywhere in the
+    // pipeline, hasPendingDeepStage returns false and the deep flow dies.
+    assert.equal(hasPendingDeepStage(loaded?.preferences, base), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});