@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/tests/preferences.test.ts

@@ -10,7 +10,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import {
@@ -24,6 +24,7 @@ import {
   loadProjectGSDPreferences,
   parsePreferencesMarkdown,
   renderPreferencesForSystemPrompt,
+  clearGSDPreferencesCache,
   _resetParseWarningFlag,
 } from "../preferences.ts";
 import { collectPreferenceDiagnostics, formatPreferenceDiagnostic } from "../preferences-diagnostics.ts";
@@ -140,6 +141,26 @@ test("invalid value types produce errors and fall back to undefined", () => {
   }
 });
 
+test("remote_questions accepts object config and false disables without error", () => {
+  const disabled = validatePreferences({ remote_questions: false } as any);
+  assert.equal(disabled.errors.length, 0);
+  assert.equal(disabled.preferences.remote_questions, undefined);
+
+  const configured = validatePreferences({
+    remote_questions: { channel: "telegram", channel_id: "12345" },
+  });
+  assert.equal(configured.errors.length, 0);
+  assert.deepEqual(configured.preferences.remote_questions, {
+    channel: "telegram",
+    channel_id: "12345",
+  });
+
+  for (const value of ["telegram", 0]) {
+    const invalid = validatePreferences({ remote_questions: value } as any);
+    assert.ok(invalid.errors.includes("remote_questions must be an object"));
+  }
+});
+
 test("flat_rate_providers: accepts string array", () => {
   const { errors, preferences } = validatePreferences({
     flat_rate_providers: ["my-proxy", "private-cli"],
@@ -326,6 +347,136 @@ test("workspace.repositories duplicate path error includes both repository ids",
   );
 });
 
+test("workspace.mode parent with no repositories is rejected", () => {
+  const { errors } = validatePreferences({
+    workspace: {
+      mode: "parent",
+    },
+  });
+
+  assert.ok(
+    errors.some((e) =>
+      e.includes('workspace.mode "parent" requires at least one repository under workspace.repositories'),
+    ),
+  );
+});
+
+test("workspace.mode parent with empty repositories map is rejected", () => {
+  const { errors } = validatePreferences({
+    workspace: {
+      mode: "parent",
+      repositories: {},
+    },
+  });
+
+  assert.ok(
+    errors.some((e) =>
+      e.includes('workspace.mode "parent" requires at least one repository under workspace.repositories'),
+    ),
+  );
+});
+
+test("workspace.mode parent with declared repositories is valid", () => {
+  const { errors } = validatePreferences({
+    workspace: {
+      mode: "parent",
+      repositories: {
+        frontend: { path: "frontend" },
+      },
+    },
+  });
+
+  assert.equal(errors.length, 0);
+});
+
+test("mode:team + workspace.mode:parent warns about root-only push/PR", () => {
+  const { warnings } = validatePreferences({
+    mode: "team",
+    workspace: {
+      mode: "parent",
+      repositories: {
+        frontend: { path: "frontend" },
+      },
+    },
+  });
+  const crossAxisWarnings = warnings.filter((w) => w.includes("mode:team + workspace.mode:parent"));
+
+  assert.ok(
+    crossAxisWarnings.some((w) =>
+      w.includes("ADR-044"),
+    ),
+    "expected a cross-axis warning naming ADR-044",
+  );
+  assert.equal(crossAxisWarnings.length, 1, "expected exactly one cross-axis warning");
+});
+
+test("mode:team + workspace.mode:parent warns after global/project merge", (t) => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-prefs-cross-axis-project-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-cross-axis-home-"));
+
+  t.after(() => {
+    clearGSDPreferencesCache();
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  });
+
+  mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(tempProject);
+  clearGSDPreferencesCache();
+
+  writeFileSync(getGlobalGSDPreferencesPath(), "---\nversion: 1\nmode: team\n---\n", "utf-8");
+  writeFileSync(
+    getProjectGSDPreferencesPath(tempProject),
+    [
+      "---",
+      "version: 1",
+      "workspace:",
+      "  mode: parent",
+      "  repositories:",
+      "    frontend:",
+      "      path: frontend",
+      "---",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const rawGlobalWarnings = loadGlobalGSDPreferences()?.warnings ?? [];
+  const rawProjectWarnings = loadProjectGSDPreferences(tempProject)?.warnings ?? [];
+  assert.equal(rawGlobalWarnings.filter((w) => w.includes("workspace.mode:parent")).length, 0);
+  assert.equal(rawProjectWarnings.filter((w) => w.includes("mode:team + workspace.mode:parent")).length, 0);
+
+  const loaded = loadEffectiveGSDPreferences(tempProject);
+  assert.equal(loaded?.preferences.mode, "team");
+  assert.equal(loaded?.preferences.workspace?.mode, "parent");
+  assert.equal(
+    (loaded?.warnings ?? []).filter((w) => w.includes("mode:team + workspace.mode:parent")).length,
+    1,
+  );
+
+  const diagnostics = collectPreferenceDiagnostics(tempProject).filter((diagnostic) =>
+    diagnostic.message.includes("mode:team + workspace.mode:parent"),
+  );
+  assert.equal(diagnostics.length, 1);
+  assert.equal(diagnostics[0]?.scope, "project");
+});
+
+test("mode:team without workspace.mode:parent does not warn about push", () => {
+  const { warnings } = validatePreferences({
+    mode: "team",
+  });
+
+  assert.ok(
+    !warnings.some((w) => w.includes("workspace.mode:parent")),
+    "team mode alone must not trigger the parent-workspace push warning",
+  );
+});
 
 test("workspace is a recognized preference key (no unknown warning)", () => {
   const { warnings } = validatePreferences({
@@ -446,6 +597,51 @@ test("loadEffectiveGSDPreferences preserves disabled_model_providers across merg
   }
 });
 
+test("loadEffectiveGSDPreferences caches unchanged files until mtime changes", (t) => {
+  const originalCwd = process.cwd();
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-prefs-cache-project-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-prefs-cache-home-"));
+
+  t.after(() => {
+    clearGSDPreferencesCache();
+    process.chdir(originalCwd);
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  });
+
+  mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+  process.env.GSD_HOME = tempGsdHome;
+  process.chdir(tempProject);
+  clearGSDPreferencesCache();
+
+  const globalPrefsPath = join(tempGsdHome, "PREFERENCES.md");
+  const fixedMtime = new Date("2025-01-01T00:00:00.000Z");
+  const changedMtime = new Date("2025-01-01T00:00:01.000Z");
+
+  writeFileSync(globalPrefsPath, "---\nversion: 1\nlanguage: Spanish\n---\n", "utf-8");
+  utimesSync(globalPrefsPath, fixedMtime, fixedMtime);
+
+  const first = loadEffectiveGSDPreferences();
+  assert.notEqual(first, null);
+  assert.equal(first!.preferences.language, "Spanish");
+
+  writeFileSync(globalPrefsPath, "---\nversion: 1\nlanguage: English\n---\n", "utf-8");
+  utimesSync(globalPrefsPath, fixedMtime, fixedMtime);
+
+  const cached = loadEffectiveGSDPreferences();
+  assert.notEqual(cached, null);
+  assert.equal(cached!.preferences.language, "Spanish");
+
+  utimesSync(globalPrefsPath, changedMtime, changedMtime);
+
+  const reloaded = loadEffectiveGSDPreferences();
+  assert.notEqual(reloaded, null);
+  assert.equal(reloaded!.preferences.language, "English");
+});
+
 // ── Wizard fields ────────────────────────────────────────────────────────────
 
 test("budget fields validate correctly", () => {

package/src/resources/extensions/gsd/tests/prefs-wizard-coverage.test.ts

@@ -6,7 +6,12 @@ import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { buildCategorySummaries, handlePrefsWizard } from "../commands-prefs-wizard.ts";
+import {
+  buildCategorySummaries,
+  handlePrefsWizard,
+  serializePreferencesToFrontmatter,
+} from "../commands-prefs-wizard.ts";
+import { parsePreferencesMarkdown, validatePreferences } from "../preferences.ts";
 import { KNOWN_PREFERENCE_KEYS } from "../preferences-types.ts";
 
 const PREF_SAMPLE_VALUES: Record<string, unknown> = {
@@ -103,6 +108,54 @@ const PREF_SAMPLE_VALUES: Record<string, unknown> = {
   },
 };
 
+test("prefs serializer preserves nested hook on_block objects", () => {
+  const frontmatter = serializePreferencesToFrontmatter({
+    post_unit_hooks: [{
+      name: "plan-review",
+      after: ["execute-task"],
+      prompt: "write PLAN-REVIEW.md",
+      artifact: "PLAN-REVIEW.md",
+      criticality: "blocking",
+      on_block: { action: "pause" },
+    }],
+  });
+
+  assert.doesNotMatch(frontmatter, /\[object Object\]/);
+  assert.ok(frontmatter.includes("    on_block:\n      action: pause\n"));
+
+  const parsed = parsePreferencesMarkdown(`---\n${frontmatter}---\n`);
+  assert.notEqual(parsed, null);
+
+  const { errors, preferences } = validatePreferences(parsed!);
+  assert.deepEqual(errors, []);
+  assert.deepEqual(preferences.post_unit_hooks?.[0]?.on_block, { action: "pause" });
+});
+
+test("prefs serializer correctly indents nested object when it is the first array-item property", () => {
+  // on_block is the FIRST property — exercises the first-key-is-object branch
+  const frontmatter = serializePreferencesToFrontmatter({
+    post_unit_hooks: [{
+      on_block: { action: "pause" }, // first property — exercises the first-key-is-object branch
+      name: "gate",                  // required fields come after so on_block stays first
+      after: ["execute-task"],
+      prompt: "review output",
+    }],
+  });
+
+  assert.doesNotMatch(frontmatter, /\[object Object\]/);
+  // Children of on_block must be indented deeper than on_block itself (not siblings)
+  assert.ok(
+    frontmatter.includes("  - on_block:\n      action: pause\n"),
+    `Expected on_block children indented as nested YAML, got:\n${frontmatter}`,
+  );
+  // Sanity: parse + validate round-trip
+  const parsed = parsePreferencesMarkdown(`---\n${frontmatter}---\n`);
+  assert.notEqual(parsed, null);
+  const { errors, preferences } = validatePreferences(parsed!);
+  assert.deepEqual(errors, []);
+  assert.deepEqual(preferences.post_unit_hooks?.[0]?.on_block, { action: "pause" });
+});
+
 test("prefs wizard save path preserves every known preference key", async () => {
   const missingSamples = [...KNOWN_PREFERENCE_KEYS].filter((key) => !(key in PREF_SAMPLE_VALUES));
   assert.deepEqual(missingSamples, [], "test fixture must cover every known preference key");
@@ -129,6 +182,70 @@ test("prefs wizard save path preserves every known preference key", async () =>
   }
 });
 
+test("verification wizard prompts for per-unit cost cap and persists it (regression #1121)", async () => {
+  // Regression for #1121: the `/gsd prefs` Verification category never prompted for
+  // `per_unit_cost_cap_usd`, so the per-unit cost cap could only be set by hand-editing
+  // PREFERENCES.md. Drive the wizard into Verification, answer the cap prompt, and assert
+  // the prompt exists and the entered value is serialized + round-trips back as a number.
+  const dir = mkdtempSync(join(tmpdir(), "gsd-prefs-wizard-"));
+  const prefsPath = join(dir, "PREFERENCES.md");
+
+  const inputLabels: string[] = [];
+  let topMenuVisits = 0;
+
+  const ctx = {
+    ui: {
+      notify() {},
+      select: async (label: string, options: string[]) => {
+        if (label === "GSD Preferences") {
+          topMenuVisits += 1;
+          if (topMenuVisits === 1) {
+            const verification = options.find((o) => o.startsWith("Verification"));
+            assert.ok(verification, "wizard menu must offer a Verification category");
+            return verification;
+          }
+          return "── Save & Exit ──";
+        }
+        // verification_commands string-list sub-menu — leave it untouched
+        if (options.includes("Done")) return "Done";
+        // boolean/enum prompts within the category — keep the current value
+        if (options.includes("(keep current)")) return "(keep current)";
+        return options[options.length - 1];
+      },
+      input: async (label: string) => {
+        inputLabels.push(label);
+        if (label.includes("Per-unit cost cap")) return "12.5";
+        return null; // escape every other numeric/string prompt (no change)
+      },
+    },
+    waitForIdle: async () => {},
+    reload: async () => {},
+  } as any;
+
+  try {
+    await handlePrefsWizard(ctx, "project", {}, { pathOverride: prefsPath });
+
+    // The Verification wizard must actually ask for the per-unit cost cap.
+    assert.ok(
+      inputLabels.some((l) => l.includes("Per-unit cost cap")),
+      `Verification wizard must prompt for the per-unit cost cap; prompts seen:\n${inputLabels.join("\n")}`,
+    );
+
+    // The entered value must be serialized to PREFERENCES.md...
+    const saved = readFileSync(prefsPath, "utf-8");
+    assert.match(saved, /per_unit_cost_cap_usd:\s*12\.5(\s|$)/m);
+
+    // ...and round-trip back through the parser/validator as a number.
+    const parsed = parsePreferencesMarkdown(saved);
+    assert.notEqual(parsed, null);
+    const { errors, preferences } = validatePreferences(parsed!);
+    assert.deepEqual(errors, []);
+    assert.equal(preferences.per_unit_cost_cap_usd, 12.5);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("category summaries expose the wizard menu surface for configured prefs", () => {
   const summaries = buildCategorySummaries(PREF_SAMPLE_VALUES);
   assert.deepEqual(
@@ -150,11 +267,14 @@ test("category summaries expose the wizard menu surface for configured prefs", (
       "timeouts",
       "uok",
       "verification",
+      "workspace",
     ],
   );
   assert.match(summaries.models, /phase/);
   assert.match(summaries.integrations, /remote: C123/);
   assert.match(summaries.verification, /1 cmd/);
+  assert.match(summaries.workspace, /mode: parent/);
+  assert.match(summaries.workspace, /1 repo/);
 });
 
 test("models wizard offers discovered models for enabled providers", async () => {
@@ -223,3 +343,78 @@ test("models wizard offers discovered models for enabled providers", async () =>
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test("workspace wizard category configures parent mode with a declared repository", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-prefs-wizard-workspace-"));
+  const prefsPath = join(dir, "PREFERENCES.md");
+  try {
+    // Drive: Workspace → parent mode → Add repository (id=frontend, path=frontend,
+    // role=ui, verification=npm test, commit policy auto) → Done → Save & Exit.
+    const selects = [
+      "Workspace       (single-repo)",       // pick the Workspace category
+      "parent",                               // promptEnum: workspace mode
+      "Add repository",                       // sub-menu
+      "(keep current)",                       // promptEnum: commit policy -> keep auto default
+      "Done",                                 // exit repo sub-menu
+      "── Save & Exit ──",                    // exit wizard
+    ];
+    const inputs = [
+      "frontend",                             // repository id
+      "frontend",                             // repository path
+      "ui",                                   // role
+      "npm test",                             // verification commands
+    ];
+    const ctx = {
+      ui: {
+        notify() {},
+        select: async () => selects.shift(),
+        input: async () => inputs.shift(),
+      },
+      waitForIdle: async () => {},
+      reload: async () => {},
+    } as any;
+
+    await handlePrefsWizard(ctx, "project", {}, { pathOverride: prefsPath });
+
+    const saved = readFileSync(prefsPath, "utf-8");
+    assert.match(saved, /mode: parent/);
+    assert.match(saved, /frontend:/);
+    assert.match(saved, /path: frontend/);
+    assert.match(saved, /role: ui/);
+    assert.match(saved, /npm test/);
+    assert.equal(selects.length, 0, "all queued selects should be consumed");
+    assert.equal(inputs.length, 0, "all queued inputs should be consumed");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("workspace wizard does not save parent mode when no repository is declared", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-prefs-wizard-workspace-empty-"));
+  const prefsPath = join(dir, "PREFERENCES.md");
+  try {
+    // parent mode with no repos added → should warn and not persist workspace.
+    const selects = [
+      "Workspace       (single-repo)",
+      "parent",
+      "Done",                                 // add nothing
+      "── Save & Exit ──",
+    ];
+    const ctx = {
+      ui: {
+        notify() {},
+        select: async () => selects.shift(),
+        input: async () => "",
+      },
+      waitForIdle: async () => {},
+      reload: async () => {},
+    } as any;
+
+    await handlePrefsWizard(ctx, "project", {}, { pathOverride: prefsPath });
+
+    const saved = readFileSync(prefsPath, "utf-8");
+    assert.doesNotMatch(saved, /mode: parent/, "parent mode must not persist without a declared repo");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/progressive-planning.test.ts

@@ -17,7 +17,8 @@ import {
   getSlice,
 } from "../gsd-db.ts";
 import { autoHealSketchFlags } from "../state-reconciliation/drift/sketch-flag.ts";
-import { deriveState, deriveStateFromDb } from "../state.ts";
+import { deriveState, deriveStateFromDb, invalidateStateCache } from "../state.ts";
+import { reconcileBeforeDispatch } from "../state-reconciliation.ts";
 import { resolveDispatch } from "../auto-dispatch.ts";
 import type { DispatchContext } from "../auto-dispatch.ts";
 
@@ -174,7 +175,7 @@ test("ADR-011: refining + flag flipped OFF mid-milestone → falls through to pl
   }
 });
 
-test("ADR-011: existing PLAN heals stale sketch flag via deriveStateFromDb (progressive_planning ON)", async (t) => {
+test("ADR-011: existing PLAN + stale sketch flag heals via reconcileBeforeDispatch, then dispatch routes past refining (progressive_planning ON)", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -188,11 +189,22 @@ test("ADR-011: existing PLAN heals stale sketch flag via deriveStateFromDb (prog
   );
   process.chdir(base);
 
-  // deriveStateFromDb auto-heals the stale sketch flag when PLAN.md exists,
-  // regardless of the progressive_planning preference.
+  // Derivation is pure (ADR-017): a stale sketch flag (PLAN on disk but
+  // is_sketch=1) yields 'refining' and must NOT mutate the DB. Healing is
+  // owned by reconcileBeforeDispatch, which runs before every dispatch.
+  invalidateStateCache();
+  const beforeReconcile = await deriveStateFromDb(base);
+  assert.equal(beforeReconcile.activeSlice?.id, "S02");
+  assert.equal(beforeReconcile.phase, "refining", "derive alone must not heal the stale sketch flag");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "derive must not mutate is_sketch");
+
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile clears the stale sketch flag once PLAN exists");
+
+  invalidateStateCache();
   const state = await deriveStateFromDb(base);
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "derive: flag cleared when PLAN exists");
-  assert.equal(state.phase, "planning", "derive: phase advances past refining once flag is healed");
+  assert.equal(state.phase, "planning", "re-derive advances past refining once the flag is healed");
 
   const ctx: DispatchContext = {
     basePath: base,
@@ -229,7 +241,7 @@ test("ADR-011: autoHealSketchFlags flips is_sketch=0 when PLAN file exists", asy
   assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "post-heal: flag cleared");
 });
 
-test("ADR-011: deriveStateFromDb auto-heals stale sketch flag when PLAN exists", async (t) => {
+test("ADR-011: reconcileBeforeDispatch auto-heals stale sketch flag when PLAN exists", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -244,12 +256,23 @@ test("ADR-011: deriveStateFromDb auto-heals stale sketch flag when PLAN exists",
   );
   process.chdir(base);
 
-  const state = await deriveStateFromDb(base);
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "derive should clear stale is_sketch");
-  assert.equal(state.phase, "planning", "state should advance past refining once stale flag is healed");
+  // Pure derivation reports the stale flag as 'refining' without repairing it.
+  invalidateStateCache();
+  const stale = await deriveStateFromDb(base);
+  assert.equal(stale.phase, "refining", "derive alone must not heal the stale flag");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "is_sketch unchanged before reconcile");
+
+  // Reconciliation owns the repair (ADR-017 stale-sketch-flag drift handler).
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile should clear stale is_sketch");
+
+  invalidateStateCache();
+  const healed = await deriveStateFromDb(base);
+  assert.equal(healed.phase, "planning", "state advances past refining once the stale flag is healed");
 });
 
-test("ADR-011: deriveState uses canonical artifact root for sketch-flag healing", async (t) => {
+test("ADR-011: deriveState stays pure across worktree/canonical-root; healing belongs to reconcile at the canonical artifact root", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -265,9 +288,22 @@ test("ADR-011: deriveState uses canonical artifact root for sketch-flag healing"
   mkdirSync(worktreePath, { recursive: true });
   process.chdir(worktreePath);
 
-  const state = await deriveState(worktreePath, { projectRootForReads: base });
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "deriveState should heal from canonical artifact root");
-  assert.equal(state.phase, "planning", "state should advance past refining when PLAN exists at canonical root");
+  // Deriving from the worktree with reads routed to the canonical artifact
+  // root resolves DB state but never mutates it (ADR-017: derive is pure).
+  // The legacy projectRootForReads-driven heal is gone; healing now happens
+  // in reconcileBeforeDispatch, which auto runs against canonicalProjectRoot.
+  invalidateStateCache();
+  const beforeReconcile = await deriveState(worktreePath, { projectRootForReads: base });
+  assert.equal(beforeReconcile.phase, "refining", "derive alone must not heal, even via projectRootForReads");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "derive must not mutate is_sketch");
+
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile at the canonical root heals the stale flag");
+
+  invalidateStateCache();
+  const healed = await deriveState(worktreePath, { projectRootForReads: base });
+  assert.equal(healed.phase, "planning", "re-derive advances past refining once healed at the canonical root");
 });
 
 test("ADR-011: schema v16 is idempotent — re-opening DB preserves is_sketch and sketch_scope columns", async (t) => {

package/src/resources/extensions/gsd/tests/prompt-budget-enforcement.test.ts

@@ -72,6 +72,25 @@ function setupDependencyFixture(
   mkdirSync(targetSliceDir, { recursive: true });
 }
 
+function setupFlatPhaseSlicePlan(base: string): void {
+  const phaseDir = join(base, ".gsd", "phases", "01-flat-phase");
+  mkdirSync(phaseDir, { recursive: true });
+  writeFileSync(
+    join(phaseDir, "01-01-PLAN.md"),
+    [
+      "# S01: Flat phase slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: Flat task** `est:15m`",
+      "",
+      "## Verification",
+      "",
+      "- Rendered prompt points at this slice plan.",
+    ].join("\n"),
+  );
+}
+
 // ─── inlineDependencySummaries truncation ─────────────────────────────────────
 
 describe("prompt-budget: inlineDependencySummaries truncation", () => {
@@ -412,6 +431,26 @@ describe("prompt-budget: execute-task template", () => {
     }
   });
 
+  it("flat-phase execute-task fallback points at the slice plan", async () => {
+    const base = createFixtureBase();
+    try {
+      setupFlatPhaseSlicePlan(base);
+
+      const prompt = await buildExecuteTaskPrompt("M001", "S01", "Slice", "T01", "Task", base, {
+        level: "minimal",
+        sessionContextWindow: 128_000,
+      });
+
+      assert.match(
+        prompt,
+        /Task plan not found at dispatch time\. Read `\.gsd\/phases\/01-flat-phase\/01-01-PLAN\.md` before executing\./,
+      );
+      assert.doesNotMatch(prompt, /\.gsd\/phases\/01-flat-phase\/tasks\/T01-PLAN\.md/);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("verificationBudget format varies with context window size", () => {
     const budget128K = computeBudgets(128_000);
     const budget1M = computeBudgets(1_000_000);
@@ -566,6 +605,25 @@ describe("prompt-budget: execute-task builder truncation pattern", () => {
 });
 
 describe("prompt-budget: reactive-execute builder", () => {
+  it("flat-phase subagent fallback points at the slice plan", async () => {
+    const base = createFixtureBase();
+    try {
+      setupFlatPhaseSlicePlan(base);
+
+      const prompt = await buildReactiveExecutePrompt("M001", "Milestone", "S01", "Slice", ["T01"], base, undefined, {
+        sessionContextWindow: 128_000,
+      });
+
+      assert.match(
+        prompt,
+        /Task plan not found at dispatch time\. Read `\.gsd\/phases\/01-flat-phase\/01-01-PLAN\.md` before executing\./,
+      );
+      assert.doesNotMatch(prompt, /\.gsd\/phases\/01-flat-phase\/tasks\/T01-PLAN\.md/);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("caps dependency carry-forward per ready subagent", async () => {
     const base = createFixtureBase();
     try {