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

package/src/resources/extensions/gsd/tests/orphan-stash-audit.test.ts

@@ -1,6 +1,7 @@
 // gsd-pi + src/resources/extensions/gsd/tests/orphan-stash-audit.test.ts
-// Regression: orphaned gsd-preflight-stash entries from completed milestones
-// must be auto-applied at startup so the user's pre-merge work returns.
+// Regression coverage for orphaned gsd-preflight-stash entries from completed
+// milestones: safe startup recovery for untracked work, manual warnings for
+// tracked or dirty-tree cases that would silently mutate user state.
 
 import { describe, test, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
@@ -37,6 +38,13 @@ function pushPreflightStash(repo: string, milestoneId: string, fileName: string,
   return marker;
 }
 
+function pushTrackedPreflightStash(repo: string, milestoneId: string, fileName: string, content: string): string {
+  writeFileSync(join(repo, fileName), content);
+  const marker = `gsd-preflight-stash:${milestoneId}:42:1700000000000:tracked`;
+  git(repo, "stash", "push", "-m", `gsd-preflight-stash [${marker}]`);
+  return marker;
+}
+
 describe("auditOrphanedPreflightStashes", () => {
   let repo: string;
 
@@ -83,6 +91,23 @@ describe("auditOrphanedPreflightStashes", () => {
     assert.match(list, /gsd-preflight-stash:M002:/);
   });
 
+  test("does not auto-apply a tracked orphan preflight stash onto a clean working tree", () => {
+    pushTrackedPreflightStash(repo, "M006", "seed.txt", "seed\ntracked pre-merge work\n");
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "seed\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1);
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /stash modifies tracked files/);
+    assert.match(result.warnings[0], /git stash apply stash@\{\d+\}/);
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "seed\n");
+
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M006:/);
+  });
+
   test("ignores stashes whose milestone is not complete", () => {
     pushPreflightStash(repo, "M003", "wip.txt", "still-working\n");
 
@@ -115,23 +140,25 @@ describe("auditOrphanedPreflightStashes", () => {
     assert.match(result.warnings[0], /db unavailable/);
   });
 
-  test("collects a warning when stash apply fails (conflicting working tree)", () => {
-    // Push a stash containing a change to seed.txt; then dirty seed.txt with
-    // a conflicting modification before the audit runs so apply fails.
+  test("collects a warning instead of applying when the working tree is not clean", () => {
+    // Push a stash containing a change to seed.txt; then dirty seed.txt before
+    // the audit runs. Startup recovery must leave the tree untouched and ask
+    // the user to apply the retained backup stash manually.
     writeFileSync(join(repo, "seed.txt"), "stashed\n");
     const marker = `gsd-preflight-stash:M005:42:1700:zz`;
     git(repo, "stash", "push", "-m", `gsd-preflight-stash [${marker}]`);
 
-    // Dirty the working tree so apply will conflict.
     writeFileSync(join(repo, "seed.txt"), "conflicting modification\n");
 
     const result = auditOrphanedPreflightStashes(repo, () => true);
 
     assert.equal(result.applied.length, 0);
     assert.equal(result.warnings.length, 1);
-    assert.match(result.warnings[0], /Could not apply orphaned preflight stash/);
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /working tree not clean/);
     assert.match(result.warnings[0], /M005/);
     assert.match(result.warnings[0], /git stash apply/);
+    assert.equal(readFileSync(join(repo, "seed.txt"), "utf-8"), "conflicting modification\n");
 
     const list = git(repo, "stash", "list");
     assert.match(list, /gsd-preflight-stash:M005:/);
@@ -169,6 +196,63 @@ describe("auditOrphanedPreflightStashes", () => {
       "second run must NOT warn — files are already restored from first run",
     );
   });
+
+  test("warns instead of silently skipping when only some stash untracked files were restored", () => {
+    // Cursor Bugbot caught: isAlreadyRestoredUntrackedStatus treated a dirty
+    // tree as fully restored when every *current* untracked path appeared in
+    // the stash, without requiring every *stash* untracked path to be present.
+    // A partial restore (only some files recovered) was misread as the
+    // idempotent steady state, so the audit no-oped and the remaining pre-merge
+    // files stayed missing with no warning.
+    writeFileSync(join(repo, "first.txt"), "first\n");
+    writeFileSync(join(repo, "second.txt"), "second\n");
+    const marker = `gsd-preflight-stash:M007:42:1700000000000:partial`;
+    git(repo, "stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${marker}]`);
+
+    // Both files are stashed away.
+    assert.equal(existsSync(join(repo, "first.txt")), false);
+    assert.equal(existsSync(join(repo, "second.txt")), false);
+
+    // Simulate a partial restore: only first.txt came back; second.txt is still
+    // missing from the working tree.
+    writeFileSync(join(repo, "first.txt"), "first\n");
+
+    const result = auditOrphanedPreflightStashes(repo, () => true);
+
+    // Must NOT be treated as already-restored: second.txt is still missing, so
+    // the audit must surface a manual-recovery warning rather than no-op.
+    assert.equal(result.applied.length, 0);
+    assert.equal(result.warnings.length, 1, "partial restore must warn, not silently no-op");
+    assert.match(result.warnings[0], /not auto-applied/);
+    assert.match(result.warnings[0], /working tree not clean/);
+    assert.match(result.warnings[0], /M007/);
+    assert.match(result.warnings[0], /git stash apply/);
+
+    // The stash entry must remain so the user can recover second.txt manually.
+    const list = git(repo, "stash", "list");
+    assert.match(list, /gsd-preflight-stash:M007:/);
+  });
+
+  test("fully restored multi-file untracked stash stays a silent no-op", () => {
+    // Guards the other direction of the set-equality fix: when EVERY stash
+    // untracked file is present in the working tree, the genuine idempotent
+    // steady state must still be recognized and skipped without warning, even
+    // when the stash captured more than one file.
+    writeFileSync(join(repo, "alpha.txt"), "alpha\n");
+    writeFileSync(join(repo, "beta.txt"), "beta\n");
+    const marker = `gsd-preflight-stash:M008:42:1700000000000:multi`;
+    git(repo, "stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${marker}]`);
+
+    const first = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(first.applied.length, 1, "first run applies both files");
+    assert.equal(first.warnings.length, 0);
+    assert.equal(existsSync(join(repo, "alpha.txt")), true);
+    assert.equal(existsSync(join(repo, "beta.txt")), true);
+
+    const second = auditOrphanedPreflightStashes(repo, () => true);
+    assert.equal(second.applied.length, 0, "second run skips");
+    assert.equal(second.warnings.length, 0, "fully restored multi-file stash must not warn");
+  });
 });
 
 test("_isAlreadyRestoredApplyError detects the git stash apply already-exists error", () => {

package/src/resources/extensions/gsd/tests/parsers-legacy-importers.test.ts

@@ -54,9 +54,12 @@ const ALLOWED_IMPORTERS = new Set([
   // explicit degraded-mode fallback when DB has no task rows (warns on use)
   "gsd/reactive-graph.ts",
   // recovery path: explicit pre-migration/DB-unavailable fallback branches
-  "gsd/auto-recovery.ts",
+  // (verifyExpectedArtifact extracted here from auto-recovery.ts)
+  "gsd/artifact-verification.ts",
   // diagnostics-only surfaces: report on projections, make no dispatch decisions
   "gsd/doctor.ts",
+  // diagnostics-only: compares PLAN.md task checkboxes against DB status
+  "gsd/doctor-engine-checks.ts",
   // display/telemetry-only surfaces
   "gsd/workspace-index.ts",
   "gsd/visualizer-data.ts",

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -94,6 +94,16 @@ test("plan-slice prompt: absence checks use negated quiet searches", () => {
   assert.ok(result.includes("count commands exit 1 when they find zero matches"));
 });
 
+test("plan-slice prompt: npm package existence rule is stated during generation", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
+  assert.ok(result.includes("reference only packages that exist on the public npm registry"));
+  assert.ok(result.includes("remove or correct any package name that is not real"));
+  // The post-unit pre-execution gate parses package names from require/import
+  // patterns too, not just install commands, so the rule must cover that scope.
+  assert.ok(result.includes("require('...')"));
+  assert.ok(result.includes("import ... from '...'"));
+});
+
 test("plan-slice prompt: footer references gsd_plan_slice tool, not direct write", () => {
   const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
   assert.ok(

package/src/resources/extensions/gsd/tests/plan-slice.test.ts

@@ -8,6 +8,7 @@ import { tmpdir } from 'node:os';
 
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getSlice, getSliceTasks, getTask, getGateResults, updateTaskStatus } from '../gsd-db.ts';
 import { handlePlanSlice } from '../tools/plan-slice.ts';
+import { handlePlanTask } from '../tools/plan-task.ts';
 import { parsePlan } from '../parsers-legacy.ts';
 import { deriveState, invalidateStateCache } from '../state.ts';
 
@@ -511,15 +512,113 @@ test('handlePlanSlice leaves omitted enrichment fields empty instead of renderin
   }
 });
 
-test('handlePlanSlice rejects invalid payloads', async () => {
+test('handlePlanSlice accepts metadata-only payloads without deleting existing tasks', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));
 
   try {
     seedParentSlice();
-    const result = await handlePlanSlice({ ...validParams(), tasks: [] }, base);
-    assert.ok('error' in result);
-    assert.match(result.error, /validation failed: tasks must be a non-empty array/);
+    const first = await handlePlanSlice(validParams(), base);
+    assert.ok(!('error' in first), `unexpected error: ${'error' in first ? first.error : ''}`);
+    assert.equal(getSliceTasks('M001', 'S02').length, 2);
+
+    const second = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Persist updated slice metadata before incremental tasks.',
+      successCriteria: '- Metadata renders before task planning',
+      proofLevel: 'unit',
+      integrationClosure: 'Task details follow through gsd_plan_task.',
+      observabilityImpact: 'Progress survives between tool calls.',
+    }, base);
+    assert.ok(!('error' in second), `unexpected error: ${'error' in second ? second.error : ''}`);
+    assert.equal(getSlice('M001', 'S02')?.goal, 'Persist updated slice metadata before incremental tasks.');
+    assert.deepEqual(getSliceTasks('M001', 'S02').map((task) => task.id), ['T01', 'T02']);
+
+    const third = await handlePlanSlice({ ...validParams(), tasks: [] }, base);
+    assert.ok(!('error' in third), `unexpected error: ${'error' in third ? third.error : ''}`);
+    assert.deepEqual(getSliceTasks('M001', 'S02').map((task) => task.id), ['T01', 'T02']);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanSlice metadata-only on a fresh sketch slice keeps is_sketch set and renders no PLAN.md (#1027)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    // The incremental flow's first call carries metadata only (no tasks). It
+    // must NOT error (renderPlanFromDb throws on a task-less slice), and it must
+    // NOT clear the sketch flag — clearing it without a PLAN.md would leave the
+    // slice out of refining with no plan artifact, breaking sketch/plan signaling.
+    const result = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Persist slice metadata before any tasks exist.',
+    }, base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+    assert.equal(getSlice('M001', 'S02')?.goal, 'Persist slice metadata before any tasks exist.');
+    assert.equal(getSliceTasks('M001', 'S02').length, 0);
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 1, 'sketch flag must stay set until a task-bearing plan renders');
+
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(!existsSync(planPath), 'no PLAN.md should be rendered until the first task is planned');
+
+    invalidateStateCache();
+    const after = await deriveState(base);
+    assert.equal(after.phase, 'refining', 'a task-less sketch slice stays in refining');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask materializes the slice PLAN.md and clears the sketch flag on the incremental path (#1027)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    const sliceResult = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Incrementally planned slice.',
+      successCriteria: '- The slice plan is built up one task at a time',
+    }, base);
+    assert.ok(!('error' in sliceResult), `unexpected error: ${'error' in sliceResult ? sliceResult.error : ''}`);
+
+    const taskResult = await handlePlanTask({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      taskId: 'T01',
+      title: 'First incremental task',
+      description: 'Implement the first task added through gsd_plan_task.',
+      estimate: '30m',
+      files: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+      verify: 'node --test src/resources/extensions/gsd/tests/plan-task.test.ts',
+      inputs: ['src/resources/extensions/gsd/tools/plan-milestone.ts'],
+      expectedOutput: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+    }, base);
+    assert.ok(!('error' in taskResult), `unexpected error: ${'error' in taskResult ? taskResult.error : ''}`);
+
+    // The first incremental task materializes the canonical slice PLAN.md with
+    // the task present, and clears the sketch flag now that a plan exists.
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(existsSync(planPath), 'slice PLAN.md should exist after the first task is planned');
+    const parsedPlan = parsePlan(readFileSync(planPath, 'utf-8'));
+    assert.equal(parsedPlan.goal, 'Incrementally planned slice.');
+    assert.equal(parsedPlan.tasks.length, 1);
+    assert.equal(parsedPlan.tasks[0]?.id, 'T01');
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 0, 'sketch flag must clear once the first task renders a plan');
+
+    invalidateStateCache();
+    const after = await deriveState(base);
+    assert.notEqual(after.phase, 'refining', 'a planned slice leaves refining');
   } finally {
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/plan-task.test.ts

@@ -4,7 +4,7 @@ import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, writeFileSync
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getTask } from '../gsd-db.ts';
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getSlice, getTask, getGateResults } from '../gsd-db.ts';
 import { handlePlanTask } from '../tools/plan-task.ts';
 import { parseTaskPlanFile } from '../files.ts';
 
@@ -65,6 +65,25 @@ test('handlePlanTask writes planning state and renders task plan', async () => {
   }
 });
 
+test('handlePlanTask seeds execute-task gate rows for incremental planning', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const result = await handlePlanTask(validParams(), base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const gateIds = getGateResults('M001', 'S02', 'task')
+      .filter((gate) => gate.task_id === 'T02')
+      .map((gate) => gate.gate_id)
+      .sort();
+    assert.deepEqual(gateIds, ['Q5', 'Q6', 'Q7']);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('handlePlanTask rejects invalid payloads', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));
@@ -170,6 +189,30 @@ test('handlePlanTask surfaces render failures without changing parse-visible tas
   }
 });
 
+test('handlePlanTask keeps the sketch flag set when the flat-phase slice plan sync fails (#1083)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    // The per-task render writes T02-PLAN.md and succeeds, but the flat-phase
+    // slice re-render (the canonical PLAN.md that embeds task checkboxes) targets
+    // phases/01-test/01-02-PLAN.md. Pre-creating that path as a directory forces
+    // EISDIR on the slice sync, so the canonical slice plan never reflects the
+    // task. The sketch flag must therefore stay set — the slice keeps refining —
+    // instead of leaving the slice out of refining over a stale plan.
+    mkdirSync(join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md'), { recursive: true });
+
+    const result = await handlePlanTask(validParams(), base);
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 1, 'sketch flag must stay set when the canonical slice plan could not sync');
+    assert.ok(getTask('M001', 'S02', 'T02'), 'the task itself is still persisted so the slice can re-sync on retry');
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('handlePlanTask reruns idempotently and refreshes parse-visible state', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));

package/src/resources/extensions/gsd/tests/post-mutation-hook.test.ts

@@ -10,7 +10,7 @@ import * as os from 'node:os';
 import { openDatabase, closeDatabase } from '../gsd-db.ts';
 import { handleCompleteTask } from '../tools/complete-task.ts';
 import { readEvents } from '../workflow-events.ts';
-import { readManifest } from '../workflow-manifest.ts';
+import { flushManifest, readManifest } from '../workflow-manifest.ts';
 
 function tempDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-post-hook-'));
@@ -115,8 +115,9 @@ test('post-mutation-hook: state-manifest.json exists after handleCompleteTask',
     const result = await handleCompleteTask(makeCompleteTaskParams(), base);
     assert.ok(!('error' in result), `handler should succeed, got: ${JSON.stringify(result)}`);
 
+    await flushManifest(base);
     const manifestPath = path.join(base, '.gsd', 'state-manifest.json');
-    assert.ok(fs.existsSync(manifestPath), 'state-manifest.json should exist after handler completes');
+    assert.ok(fs.existsSync(manifestPath), 'state-manifest.json should exist after manifest flush');
   } finally {
     closeDatabase();
     cleanupDir(base);
@@ -131,6 +132,7 @@ test('post-mutation-hook: manifest has version 1 and includes completed task', a
 
   try {
     await handleCompleteTask(makeCompleteTaskParams(), base);
+    await flushManifest(base);
 
     const manifest = readManifest(base);
     assert.ok(manifest !== null, 'manifest should be readable');

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 {

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

@@ -533,6 +533,7 @@ test("plan-milestone prompt references DB-backed planning tool and explicitly fo
   assert.match(prompt, /Do \*\*not\*\* write `?\{\{outputPath\}\}`?, `?ROADMAP\.md`?, or other planning artifacts manually/i);
   assert.match(prompt, /NEVER call `gsd_plan_milestone` with only `milestoneId` and `sliceId`/);
   assert.match(prompt, /gsd_plan_slice/);
+  assert.match(prompt, /gsd_plan_task/);
 });
 
 test("discuss prompts forbid gsd_plan_milestone slice-only tool args", () => {
@@ -548,12 +549,12 @@ test("plan-slice prompt no longer frames direct PLAN writes as the source of tru
   assert.match(prompt, /Do \*\*not\*\* rely on direct `PLAN\.md` writes as the source of truth/i);
 });
 
-test("plan-slice prompt explicitly names gsd_plan_slice as DB-backed planning tool", () => {
+test("plan-slice prompt explicitly names incremental DB-backed planning tools", () => {
   const prompt = readPrompt("plan-slice");
   assert.match(prompt, /gsd_plan_slice/);
   assert.match(prompt, /gsd_plan_task/);
-  // The prompt should describe the DB-backed tool as the canonical write path
-  assert.match(prompt, /DB-backed tool is the canonical write path/i);
+  assert.match(prompt, /Persist incrementally through DB-backed tools/i);
+  assert.match(prompt, /DB-backed tools are the canonical write path/i);
 });
 
 test("plan-slice prompt does not instruct direct file writes as a primary step", () => {
@@ -562,11 +563,12 @@ test("plan-slice prompt does not instruct direct file writes as a primary step",
   assert.doesNotMatch(prompt, /^\d+\.\s+Write `?\{\{outputPath\}\}`?\s*$/m);
 });
 
-test("plan-slice prompt clarifies gsd_plan_slice handles task persistence", () => {
+test("plan-slice prompt requires per-task incremental persistence", () => {
   const prompt = readPrompt("plan-slice");
-  // gsd_plan_slice persists tasks in its transaction — no separate gsd_plan_task calls needed
   assert.match(prompt, /gsd_plan_task/);
-  assert.match(prompt, /gsd_plan_slice` handles task persistence/i);
+  assert.match(prompt, /omit `tasks` for this metadata call/i);
+  assert.match(prompt, /call `gsd_plan_task` once per task/i);
+  assert.doesNotMatch(prompt, /do not call `gsd_plan_task`/i);
 });
 
 test("plan-slice prompt references web app UAT guidance when planning browser work", () => {