@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/src/resources/extensions/gsd/browser-daemon-auto-prep.ts

@@ -9,10 +9,19 @@ import {
 import {
   resolveGsdBrowserCliAvailability,
   resolveGsdBrowserDaemonStartInvocation,
+  resolveGsdBrowserDaemonStopInvocation,
 } from "../shared/gsd-browser-cli.js";
 import { uatTypeIncludesBrowser, type UatType } from "./uat-policy.js";
 
 const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+const DEFAULT_DAEMON_STOP_TIMEOUT_MS = 15_000;
+
+/**
+ * Project roots whose gsd-browser daemon this process warmed via
+ * {@link prepareBrowserDaemonForUat}. Teardown only stops daemons we actually
+ * started, so non-browser auto-mode sessions never spawn a stray `daemon stop`.
+ */
+const warmedDaemonProjectRoots = new Set<string>();
 
 function isEnvDisabled(value: string | undefined): boolean {
   if (!value) return false;
@@ -102,7 +111,74 @@ export function prepareBrowserDaemonForUat(ctx: BrowserDaemonWarmContext): strin
   if (!shouldWarmBrowserDaemonForUat(ctx)) return null;
 
   const result = ensureBrowserDaemonStarted(ctx.projectRoot, { env: ctx.env });
-  if (result.ok) return null;
+  if (result.ok) {
+    warmedDaemonProjectRoots.add(resolve(ctx.projectRoot));
+    return null;
+  }
 
   return `Cannot dispatch browser-backed run-uat: gsd-browser daemon failed to start (${result.error}). Ensure Chrome/Chromium is installed, run \`gsd-browser daemon health\` with the project session flags from .mcp.json, or set GSD_BROWSER_PATH to a Chromium binary.`;
 }
+
+/**
+ * Best-effort stop of a gsd-browser session daemon warmed for browser UAT.
+ * Mirrors {@link ensureBrowserDaemonStarted}; returns the failure detail rather
+ * than throwing so teardown can stay non-fatal.
+ */
+export function stopBrowserDaemon(
+  projectRoot: string,
+  options: { env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): { ok: true } | { ok: false; error: string } {
+  const env = options.env ?? process.env;
+  const availability = resolveGsdBrowserCliAvailability(env);
+  if (!availability.available) {
+    return { ok: false, error: availability.detail };
+  }
+
+  let invocation: ReturnType<typeof resolveGsdBrowserDaemonStopInvocation>;
+  try {
+    invocation = resolveGsdBrowserDaemonStopInvocation(projectRoot, env);
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  try {
+    execFileSync(invocation.command, invocation.args, {
+      cwd: invocation.cwd,
+      env: { ...process.env, ...env, ...(invocation.env ?? {}) },
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: options.timeoutMs ?? DEFAULT_DAEMON_STOP_TIMEOUT_MS,
+      encoding: "utf-8",
+    });
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Tear down every gsd-browser daemon this process warmed for browser UAT,
+ * clearing the tracked set. Called on auto-mode loop exit so the Chrome process
+ * does not survive session/task completion (mirrors the warm-up preflight).
+ * Best-effort: returns the project roots whose stop failed for logging.
+ */
+export function teardownWarmedBrowserDaemons(
+  options: { env?: NodeJS.ProcessEnv } = {},
+): { projectRoot: string; error: string }[] {
+  if (warmedDaemonProjectRoots.size === 0) return [];
+
+  const failures: { projectRoot: string; error: string }[] = [];
+  for (const projectRoot of warmedDaemonProjectRoots) {
+    const result = stopBrowserDaemon(projectRoot, { env: options.env });
+    if (!result.ok) {
+      failures.push({ projectRoot, error: result.error });
+    }
+  }
+  warmedDaemonProjectRoots.clear();
+  return failures;
+}

package/src/resources/extensions/gsd/codebase-generator.ts

@@ -675,10 +675,16 @@ export function ensureCodebaseMapFresh(
 
   const metadata = parseCodebaseMapMetadata(existing);
   const existingDescriptions = parseCodebaseMap(existing);
+  // Compare against the truncated count: when the repository has more tracked
+  // files than maxFiles, the map only lists the first maxFiles entries, so a
+  // stored fileCount above the cap (e.g. from an older map that recorded the
+  // full count) still matches the current truncated listing. Comparing raw
+  // values would flag "file-count-changed" on every turn, rewriting the
+  // timestamp and invalidating the provider KV cache prefix.
   const staleReason =
     !metadata ? "missing-metadata"
     : metadata.fingerprint !== fingerprint ? "files-changed"
-    : metadata.fileCount !== listed.files.length ? "file-count-changed"
+    : Math.min(metadata.fileCount, resolved.maxFiles) !== listed.files.length ? "file-count-changed"
     : metadata.truncated !== listed.truncated ? "truncation-changed"
     : undefined;
 

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -25,7 +25,7 @@ import {
   filterDoctorIssues,
 } from "./doctor.js";
 import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { buildClaudeRuntimeFloorAdvisory } from "../../shared/claude-runtime-floor.js";

package/src/resources/extensions/gsd/commands-workflow-templates.ts

@@ -23,7 +23,7 @@ import {
 } from "./workflow-templates.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { createGitService, runGit } from "./git-service.js";
+import { createGitService, runGit, taskBranchArgs } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin, type WorkflowPlugin } from "./workflow-plugins.js";
@@ -464,7 +464,7 @@ export async function handleStart(
         try {
           git.autoCommit("workflow-template", templateId, []);
         } catch { /* nothing to commit */ }
-        runGit(basePath, ["checkout", "-b", branchName]);
+        runGit(basePath, taskBranchArgs(basePath, branchName, current, git.getMainBranch()));
         branchCreated = true;
       }
     } catch (err) {
@@ -636,7 +636,7 @@ export function dispatchMarkdownPhasePlugin(
       const current = git.getCurrentBranch();
       if (current !== branchName) {
         try { git.autoCommit("workflow-template", templateId, []); } catch { /* nothing to commit */ }
-        runGit(basePath, ["checkout", "-b", branchName]);
+        runGit(basePath, taskBranchArgs(basePath, branchName, current, git.getMainBranch()));
         branchCreated = true;
       }
     } catch (err) {

package/src/resources/extensions/gsd/compat/compat-marker.ts

@@ -148,6 +148,53 @@ export function writeCompatMarker(basePath: string, marker: CompatMarker): void
   renameSync(tmp, path);
 }
 
+/**
+ * Remove projection entries whose backing file no longer exists on disk.
+ *
+ * gsd-pi never deletes marker entries on its own: both drift detectors skip
+ * files missing from disk (`if (!existsSync(abs)) continue;`) and the write-time
+ * flush only ever adds or refreshes entries. So when a phase directory is
+ * renamed or removed (e.g. `phases/29-new-milestone-m029/` →
+ * `phases/29-frontend-code-debt-cleanup/`), the old projection paths linger in
+ * `.compat.json` forever as phantom entries pointing at directories that no
+ * longer exist (#1257). They never reconcile, and `.compat.json` keeps drifting
+ * from disk reality so `git status` stops being a reliable proxy for "did the
+ * engine touch my plans?".
+ *
+ * This prunes those orphaned entries across the `.gsd/` projections and the
+ * `.planning/` projections/passthrough maps. It is safe: a missing-file entry is
+ * inert (every detector already ignores it), and if the file is later
+ * re-projected the write-time flush / unseeded-file detection re-seeds an
+ * accurate baseline.
+ *
+ * Returns the number of entries removed; when nothing is orphaned the marker is
+ * left untouched (no needless write, no `lastProjectedAt` churn).
+ */
+export function pruneOrphanedProjectionEntries(basePath: string): number {
+  if (!existsSync(compatMarkerPath(basePath))) return 0;
+
+  const marker = readCompatMarker(basePath);
+  let removed = 0;
+
+  const pruneMap = (map: Record<string, ProjectionEntry>, root: string): void => {
+    for (const relPath of Object.keys(map)) {
+      if (!existsSync(join(basePath, root, relPath))) {
+        delete map[relPath];
+        removed++;
+      }
+    }
+  };
+
+  pruneMap(marker.projections, ".gsd");
+  if (marker.planning) {
+    pruneMap(marker.planning.projections, ".planning");
+    pruneMap(marker.planning.passthrough, ".planning");
+  }
+
+  if (removed > 0) writeCompatMarker(basePath, marker);
+  return removed;
+}
+
 function quarantine(basePath: string, raw: string): void {
   const path = compatMarkerPath(basePath);
   const badPath = `${path}.bad-${Date.now()}`;

package/src/resources/extensions/gsd/config-overlay.ts

@@ -150,7 +150,13 @@ function collectConfigSections(options?: CollectConfigOptions): ConfigSection[]
   if (prefs?.auto_supervisor) {
     const sup = resolveAutoSupervisorConfig();
     const supRows: ConfigSection["rows"] = [];
-    if (sup.model) supRows.push({ label: "Model", value: sup.model });
+    if (sup.model) {
+      let modelVal = sup.model;
+      if (sup.modelFallbacks && sup.modelFallbacks.length > 0) {
+        modelVal += ` \u2192 ${sup.modelFallbacks.join(" \u2192 ")}`;
+      }
+      supRows.push({ label: "Model", value: modelVal });
+    }
     supRows.push({ label: "Soft timeout", value: `${sup.soft_timeout_minutes}m` });
     supRows.push({ label: "Idle timeout", value: `${sup.idle_timeout_minutes}m` });
     supRows.push({ label: "Stalled tool timeout", value: `${sup.stalled_tool_timeout_minutes}m` });

package/src/resources/extensions/gsd/db/engine.ts

@@ -860,3 +860,39 @@ export function getDb(): DbAdapter {
 export function getDbOrNull(): DbAdapter | null {
   return currentDb;
 }
+
+export interface DbWritableProbeResult {
+  ok: boolean;
+  detail?: string;
+}
+
+/**
+ * Confirm the open handle can actually write, not just that it opened.
+ *
+ * A schema-current database performs zero writes during open, so a handle that
+ * opened successfully but is not writable (read-only file, WAL/SHM permission
+ * mismatch, or a stale/moved handle → SQLITE_READONLY_DBMOVED) otherwise passes
+ * the open-only availability check and only fails much later at the first real
+ * write. The probe forces a genuine page write by re-writing the current
+ * `PRAGMA user_version` value back inside an IMMEDIATE transaction: a bare
+ * `BEGIN IMMEDIATE; ROLLBACK` is not sufficient because a moved handle does not
+ * fail until a page is actually dirtied. The value is unchanged, so the probe
+ * is idempotent, and the transaction is rolled back so nothing persists.
+ */
+export function probeDbWritable(): DbWritableProbeResult {
+  const db = currentDb;
+  if (!db) return { ok: false, detail: "No database is open." };
+  try {
+    const row = db.prepare("PRAGMA user_version").get() as { user_version?: number } | undefined;
+    const current = typeof row?.user_version === "number" ? row.user_version : 0;
+    db.exec("BEGIN IMMEDIATE");
+    try {
+      db.exec(`PRAGMA user_version = ${current}`);
+    } finally {
+      db.exec("ROLLBACK");
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, detail: (err as Error).message };
+  }
+}

package/src/resources/extensions/gsd/db/queries.ts

@@ -281,7 +281,7 @@ export function getMilestone(id: string): MilestoneRow | null {
 export function getActiveMilestoneFromDb(): MilestoneRow | null {
   if (!getDbOrNull()!) return null;
   const row = getDbOrNull()!.prepare(
-    "SELECT * FROM milestones WHERE status NOT IN ('complete', 'done', 'skipped', 'closed', 'parked') ORDER BY id LIMIT 1",
+    `SELECT * FROM milestones WHERE status NOT IN (${TERMINAL_STATUS_SQL}, 'parked') ORDER BY id LIMIT 1`,
   ).get();
   if (!row) return null;
   return rowToMilestone(row);
@@ -295,11 +295,11 @@ export function getActiveSliceFromDb(milestoneId: string): SliceRow | null {
   const row = getDbOrNull()!.prepare(
     `SELECT s.* FROM slices s
      WHERE s.milestone_id = :mid
-       AND s.status NOT IN ('complete', 'done', 'skipped')
+       AND s.status NOT IN (${TERMINAL_STATUS_SQL})
        AND NOT EXISTS (
          SELECT 1 FROM json_each(s.depends) AS dep
          WHERE dep.value NOT IN (
-           SELECT id FROM slices WHERE milestone_id = :mid AND status IN ('complete', 'done', 'skipped')
+           SELECT id FROM slices WHERE milestone_id = :mid AND status IN (${TERMINAL_STATUS_SQL})
          )
        )
      ORDER BY s.sequence, s.id
@@ -312,7 +312,7 @@ export function getActiveSliceFromDb(milestoneId: string): SliceRow | null {
 export function getActiveTaskFromDb(milestoneId: string, sliceId: string): TaskRow | null {
   if (!getDbOrNull()!) return null;
   const row = getDbOrNull()!.prepare(
-    "SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN ('complete', 'done') ORDER BY sequence, id LIMIT 1",
+    `SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN (${TERMINAL_STATUS_SQL}) ORDER BY sequence, id LIMIT 1`,
   ).get({ ":mid": milestoneId, ":sid": sliceId });
   if (!row) return null;
   return rowToTask(row);
@@ -339,7 +339,7 @@ export function getParallelMonitorSliceProgress(milestoneId: string): ParallelMo
        s.id AS id,
        s.status AS status,
        COUNT(t.id) AS total,
-       COALESCE(SUM(CASE WHEN t.status='complete' THEN 1 ELSE 0 END), 0) AS done
+       COALESCE(SUM(CASE WHEN t.status IN (${TERMINAL_STATUS_SQL}) THEN 1 ELSE 0 END), 0) AS done
      FROM slices s
      LEFT JOIN tasks t ON s.milestone_id=t.milestone_id AND s.id=t.slice_id
      WHERE s.milestone_id=:mid
@@ -518,7 +518,7 @@ export function getSliceScopedArtifacts(milestoneId: string, sliceId: string): A
 export function getActiveMilestoneIdFromDb(): IdStatusSummary | null {
   if (!getDbOrNull()!) return null;
   const row = getDbOrNull()!.prepare(
-    "SELECT id, status FROM milestones WHERE status NOT IN ('complete', 'done', 'skipped', 'closed', 'parked') ORDER BY id LIMIT 1",
+    `SELECT id, status FROM milestones WHERE status NOT IN (${TERMINAL_STATUS_SQL}, 'parked') ORDER BY id LIMIT 1`,
   ).get();
   if (!row) return null;
   return rowToIdStatusSummary(row);
@@ -536,7 +536,7 @@ export function getSliceStatusSummary(milestoneId: string): IdStatusSummary[] {
 export function getActiveTaskIdFromDb(milestoneId: string, sliceId: string): ActiveTaskSummary | null {
   if (!getDbOrNull()!) return null;
   const row = getDbOrNull()!.prepare(
-    "SELECT id, status, title FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN ('complete', 'done') ORDER BY sequence, id LIMIT 1",
+    `SELECT id, status, title FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN (${TERMINAL_STATUS_SQL}) ORDER BY sequence, id LIMIT 1`,
   ).get({ ":mid": milestoneId, ":sid": sliceId });
   if (!row) return null;
   return rowToActiveTaskSummary(row);
@@ -548,8 +548,8 @@ export function getSliceTaskCounts(milestoneId: string, sliceId: string): TaskSt
   const row = getDbOrNull()!.prepare(
     `SELECT
        COUNT(*) as total,
-       SUM(CASE WHEN status IN ('complete', 'done') THEN 1 ELSE 0 END) as done,
-       SUM(CASE WHEN status NOT IN ('complete', 'done') THEN 1 ELSE 0 END) as pending
+       SUM(CASE WHEN status IN (${TERMINAL_STATUS_SQL}) THEN 1 ELSE 0 END) as done,
+       SUM(CASE WHEN status NOT IN (${TERMINAL_STATUS_SQL}) THEN 1 ELSE 0 END) as pending
      FROM tasks WHERE milestone_id = :mid AND slice_id = :sid`,
   ).get({ ":mid": milestoneId, ":sid": sliceId });
   return rowToTaskStatusCounts(row);

package/src/resources/extensions/gsd/db/writers/cascades.ts

@@ -38,6 +38,17 @@ export type ReopenSliceOutcome =
  * completion timestamps cleared, in one commit. Folds the hand-rolled
  * transaction-plus-cascade previously in tools/reopen-slice.ts. Guards run
  * inside the transaction (TOCTOU-safe).
+ *
+ * A closed slice is always reopenable. An open slice is only reopenable when it
+ * carries a completed-task state desync (#1205): a UAT→planning fallback can
+ * leave the slice "pending" while *all* its tasks stay "complete", which
+ * deadlocks every recovery path (plan-slice/replan-slice/complete-task all
+ * reject the still-closed tasks, and slice_reopen historically rejected the
+ * still-open slice). Resetting those tasks to pending gives the planner the
+ * clean slate it needs. An open slice that still has any unfinished
+ * (pending/in-progress) task is a normal in-flight slice, not the desync, and
+ * stays rejected as "slice-not-complete" so a full reset can't wipe its
+ * legitimate progress.
  */
 export function reopenSliceCascade(milestoneId: string, sliceId: string): ReopenSliceOutcome {
   requireDb();
@@ -48,9 +59,20 @@ export function reopenSliceCascade(milestoneId: string, sliceId: string): Reopen
     if (isClosedStatus(milestone.status)) { outcome = { ok: false, reason: "milestone-closed", status: milestone.status }; return; }
     const slice = getSlice(milestoneId, sliceId);
     if (!slice) { outcome = { ok: false, reason: "slice-not-found" }; return; }
-    if (!isClosedStatus(slice.status)) { outcome = { ok: false, reason: "slice-not-complete", status: slice.status }; return; }
 
     const tasks = getSliceTasks(milestoneId, sliceId);
+    // A closed slice is always reopenable. An open slice is only the #1205
+    // desync when EVERY task is already closed (a UAT→planning fallback left the
+    // slice open with all tasks still "complete"). Requiring *all* tasks closed
+    // (not merely one) means a normal in-flight slice — which keeps at least one
+    // pending/in-progress task — is rejected, so a full reset can't wipe its
+    // legitimate progress.
+    const allTasksClosed = tasks.length > 0 && tasks.every((t) => isClosedStatus(t.status));
+    if (!isClosedStatus(slice.status) && !allTasksClosed) {
+      outcome = { ok: false, reason: "slice-not-complete", status: slice.status };
+      return;
+    }
+
     getDbOrNull()!.prepare(
       `UPDATE slices SET status = 'in_progress', completed_at = NULL WHERE milestone_id = :mid AND id = :sid`,
     ).run({ ":mid": milestoneId, ":sid": sliceId });

package/src/resources/extensions/gsd/db-adapter.ts

@@ -25,6 +25,32 @@ export function normalizeDbRows(rows: unknown[]): Record<string, unknown>[] {
   return rows.map((row) => normalizeDbRow(row)!);
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+// node:sqlite accepts binding-object keys with or without the ':'/'@'/'$'
+// prefix, but better-sqlite3 accepts only bare keys — strip the prefix so
+// call sites written against node:sqlite also work on the fallback provider.
+function normalizeBindParams(params: unknown[]): unknown[] {
+  return params.map((param) => {
+    if (!isPlainObject(param)) return param;
+    let changed = false;
+    const normalized: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(param)) {
+      if (key.length > 1 && (key[0] === ":" || key[0] === "@" || key[0] === "$")) {
+        normalized[key.slice(1)] = value;
+        changed = true;
+      } else {
+        normalized[key] = value;
+      }
+    }
+    return changed ? normalized : param;
+  });
+}
+
 export function createDbAdapter(rawDb: unknown): DbAdapter {
   const db = rawDb as {
     exec(sql: string): void;
@@ -45,13 +71,13 @@ export function createDbAdapter(rawDb: unknown): DbAdapter {
   }): DbStatement {
     return {
       run(...params: unknown[]): unknown {
-        return raw.run(...params);
+        return raw.run(...normalizeBindParams(params));
       },
       get(...params: unknown[]): Record<string, unknown> | undefined {
-        return normalizeDbRow(raw.get(...params));
+        return normalizeDbRow(raw.get(...normalizeBindParams(params)));
       },
       all(...params: unknown[]): Record<string, unknown>[] {
-        return normalizeDbRows(raw.all(...params));
+        return normalizeDbRows(raw.all(...normalizeBindParams(params)));
       },
     };
   }

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -138,7 +138,7 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - `off` — skill discovery is disabled entirely.
 
 - `auto_supervisor`: configures the auto-mode supervisor that monitors agent progress and enforces timeouts. Keys:
-  - `model`: model ID to use for the supervisor process (defaults to the currently active model).
+  - `model`: model to use for the supervisor process (defaults to the currently active model). Accepts a bare model ID **or** the same `{ model, provider?, fallbacks? }` object form as `models.<phase>`, so it honors `fallbacks[]` on a transient provider trip.
   - `soft_timeout_minutes`: minutes before the supervisor issues a soft warning (default: 20).
   - `idle_timeout_minutes`: minutes of inactivity before the supervisor intervenes (default: 10).
   - `hard_timeout_minutes`: minutes before the supervisor forces termination (default: 30).
@@ -228,7 +228,7 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `enabled`: boolean — set `false` to force sequential task execution. Default: `true`.
   - `max_parallel`: number — maximum tasks to dispatch in one batch, range `1`-`8`. Default: `2`.
   - `isolation_mode`: `"same-tree"` — currently the only supported value.
-  - `subagent_model`: string — optional model override for reactive task subagents. Falls back to the `models.subagent` routing when omitted.
+  - `subagent_model`: optional model override for reactive task subagents. Accepts a bare model ID **or** the `{ model, provider?, fallbacks? }` object form (parity with `models.<phase>`). Falls back to the `models.subagent` routing when omitted.
 
 - `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
   - `channel`: `"slack"` or `"discord"` — channel type.
@@ -326,7 +326,7 @@ In `"parent"` mode, slice/task `targetRepositories` default to the declared chil
   - `after`: string[] — unit types that trigger this hook (e.g., `["execute-task"]`).
   - `prompt`: string — prompt sent to the LLM. Supports `{milestoneId}`, `{sliceId}`, `{taskId}` substitutions.
   - `max_cycles`: number — max times this hook fires per trigger (default: 1, max: 10).
-  - `model`: string — optional model override.
+  - `model`: optional model override. Accepts a bare model ID **or** the same `{ model, provider?, fallbacks? }` object form as `models.<phase>`. With `fallbacks[]`, a transient trip of the primary provider falls back to the next entry instead of hard-failing the hook — which, for a `blocking` hook with `on_block: { action: pause }`, would otherwise pause the whole run.
   - `artifact`: string — expected output file name (relative to task/slice dir). Hook is skipped if file already exists (idempotent).
   - `criticality`: `"advisory"` or `"blocking"` — advisory preserves current best-effort behavior; blocking requires clean hook completion plus a valid outcome verdict before auto-mode advances. Default: `"advisory"`.
   - `retry_on`: string — if this file is produced instead of the artifact, re-run the trigger unit then re-run hooks.

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -14,7 +14,15 @@ import {
 } from "./gsd-db.js";
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
+import {
+  buildTaskFileName,
+  gsdProjectionRoot,
+  gsdRoot,
+  resolveGsdPathContract,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+  resolveSliceFile,
+} from "./paths.js";
 import { deriveState } from "./state.js";
 import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
@@ -23,6 +31,7 @@ import { flushWorkflowProjections } from "./projection-flush.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { parsePlan } from "./parsers-legacy.js";
 import { parseSummary } from "./files.js";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
 
 const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
 
@@ -160,11 +169,11 @@ function isClearedByMilestoneShellProjectionFlush(
   return issue.file === relativeFile(basePath, roadmapPath);
 }
 
-function artifactExistsOnDisk(basePath: string, artifactPath: string): boolean {
-  return resolveArtifactDiskPath(basePath, artifactPath) !== null;
+function artifactExistsOnDisk(basePath: string, artifactPath: string, row?: ArtifactRow): boolean {
+  return resolveArtifactDiskPath(basePath, artifactPath, row) !== null;
 }
 
-function resolveArtifactDiskPath(basePath: string, artifactPath: string): string | null {
+function resolveLiteralArtifactDiskPath(basePath: string, artifactPath: string): string | null {
   const relativeArtifactPath = artifactPathRelativeToGsd(artifactPath);
   if (isAbsolute(relativeArtifactPath)) {
     return existsSync(relativeArtifactPath) ? relativeArtifactPath : null;
@@ -176,6 +185,50 @@ function resolveArtifactDiskPath(basePath: string, artifactPath: string): string
   return null;
 }
 
+function relativeToGsdRoot(basePath: string, diskPath: string): string | null {
+  for (const root of [gsdProjectionRoot(basePath), gsdRoot(basePath)]) {
+    if (!isPathInside(root, diskPath)) continue;
+    return relative(root, diskPath).split("\\").join("/");
+  }
+  return null;
+}
+
+function isFlatPhaseDiskPath(basePath: string, diskPath: string): boolean {
+  return relativeToGsdRoot(basePath, diskPath)?.startsWith(`${LAYOUT_SEGMENTS.level1}/`) ?? false;
+}
+
+function hasFlatPhaseLayout(basePath: string): boolean {
+  return existsSync(join(gsdProjectionRoot(basePath), LAYOUT_SEGMENTS.level1));
+}
+
+function resolveFlatPhaseArtifactDiskPath(basePath: string, row: ArtifactRow): string | null {
+  if (!hasFlatPhaseLayout(basePath)) return null;
+  if (!row.milestone_id) return null;
+  const artifactType = normalizedArtifactType(row.artifact_type);
+  if (!artifactType) return null;
+
+  if (row.slice_id && row.task_id) {
+    const phaseDir = resolveMilestonePath(basePath, row.milestone_id);
+    if (!phaseDir || !isFlatPhaseDiskPath(basePath, phaseDir)) return null;
+    const candidate = join(phaseDir, buildTaskFileName(row.task_id, artifactType));
+    return existsSync(candidate) ? candidate : null;
+  }
+
+  const candidate = row.slice_id
+    ? resolveSliceFile(basePath, row.milestone_id, row.slice_id, artifactType)
+    : resolveMilestoneFile(basePath, row.milestone_id, artifactType);
+
+  return candidate && isFlatPhaseDiskPath(basePath, candidate) ? candidate : null;
+}
+
+function resolveArtifactDiskPath(basePath: string, artifactPath: string, row?: ArtifactRow): string | null {
+  if (row && isMilestonesArtifactPath(row.path)) {
+    const flatPath = resolveFlatPhaseArtifactDiskPath(basePath, row);
+    if (flatPath) return flatPath;
+  }
+  return resolveLiteralArtifactDiskPath(basePath, artifactPath);
+}
+
 function taskExistsInPlan(basePath: string, milestoneId: string, sliceId: string, taskId: string): boolean {
   const planPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
   if (!planPath || !existsSync(planPath)) return false;
@@ -228,7 +281,7 @@ function readTaskCompletionEvidenceFromSummary(
   if (!row.task_status && Number(row.task_count) > 0 && !taskExistsInPlan(basePath, row.milestone_id, row.slice_id, row.task_id)) {
     return null;
   }
-  const diskPath = resolveArtifactDiskPath(basePath, row.path);
+  const diskPath = resolveArtifactDiskPath(basePath, row.path, { ...row, artifact_type: "SUMMARY" });
   if (!diskPath) return null;
   try {
     const fullSummaryMd = readFileSync(diskPath, "utf-8");
@@ -262,6 +315,7 @@ function repairTaskArtifactDbStatusDivergence(
   basePath: string,
   row: {
     path: string;
+    artifact_type?: string;
     milestone_id: string;
     slice_id: string | null;
     task_id: string | null;
@@ -353,6 +407,49 @@ function hasPresentMilestonesReplacement(basePath: string, row: ArtifactRow, art
   );
 }
 
+function hasPresentFlatPhaseReplacement(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  if (resolveFlatPhaseArtifactDiskPath(basePath, row)) return true;
+
+  return artifactRows.some(
+    (other) =>
+      other.path !== row.path &&
+      !isMilestonesArtifactPath(other.path) &&
+      sameArtifactIdentity(row, other) &&
+      artifactExistsOnDisk(basePath, other.path, other),
+  );
+}
+
+function hasNoFlatPhaseFileEquivalent(row: ArtifactRow): boolean {
+  const artifactType = normalizedArtifactType(row.artifact_type);
+  if (row.slice_id && row.task_id) {
+    return artifactType === "PLAN" || artifactType === "SUMMARY";
+  }
+  return Boolean(row.slice_id && !row.task_id && artifactType === "SUMMARY");
+}
+
+function staleMilestonesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  if (!isMilestonesArtifactPath(row.path)) return false;
+  if (!hasFlatPhaseLayout(basePath)) return false;
+  if (hasPresentFlatPhaseReplacement(basePath, row, artifactRows)) return true;
+  return hasNoFlatPhaseFileEquivalent(row) && !resolveLiteralArtifactDiskPath(basePath, row.path);
+}
+
+function stalePhasesArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  const issuePath = artifactPathRelativeToGsd(row.path);
+  return issuePath.startsWith(`${LAYOUT_SEGMENTS.level1}/`) && hasPresentMilestonesReplacement(basePath, row, artifactRows);
+}
+
+function staleArtifactRowFixable(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  return staleMilestonesArtifactRowFixable(basePath, row, artifactRows) ||
+    stalePhasesArtifactRowFixable(basePath, row, artifactRows);
+}
+
+function staleArtifactPruneMessage(row: ArtifactRow): string {
+  return isMilestonesArtifactPath(row.path)
+    ? `pruned stale legacy artifact row ${row.path}`
+    : `pruned stale flat-phase artifact row ${row.path}`;
+}
+
 export async function checkEngineHealth(
   basePath: string,
   issues: DoctorIssue[],
@@ -579,17 +676,18 @@ export async function checkEngineHealth(
           .all() as ArtifactRow[];
 
         for (const row of artifactRows) {
-          if (artifactExistsOnDisk(basePath, row.path)) continue;
           const unitId = artifactUnitId(row);
           const issuePath = artifactPathRelativeToGsd(row.path);
-          if (options?.repair && issuePath.startsWith("phases/") && hasPresentMilestonesReplacement(basePath, row, artifactRows)) {
+          if (artifactExistsOnDisk(basePath, row.path)) continue;
+          if (options?.repair && staleArtifactRowFixable(basePath, row, artifactRows)) {
             // Route the write through the Single Writer owner (gsd-db.ts) instead
             // of issuing raw DELETE SQL here — doctor is a read-only consumer and
             // the single-writer invariant forbids write SQL outside the allowlist.
             deleteArtifactByPath(row.path);
-            fixesApplied.push(`pruned stale flat-phase artifact row ${row.path}`);
+            fixesApplied.push(staleArtifactPruneMessage(row));
             continue;
           }
+          if (artifactExistsOnDisk(basePath, row.path, row)) continue;
           if (isUserAuthoredArtifactType(row.artifact_type)) {
             const artifactType = normalizedArtifactType(row.artifact_type);
             missingUserContentArtifacts.push({ path: issuePath, artifactType });
@@ -611,7 +709,7 @@ export async function checkEngineHealth(
             unitId,
             message: `Artifact ${issuePath} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
             file: issuePath,
-            fixable: issuePath.startsWith("phases/") && hasPresentMilestonesReplacement(basePath, row, artifactRows),
+            fixable: staleArtifactRowFixable(basePath, row, artifactRows),
           });
         }
       } catch {
@@ -643,6 +741,7 @@ export async function checkEngineHealth(
           )
           .all() as Array<{
             path: string;
+            artifact_type: string;
             milestone_id: string;
             slice_id: string | null;
             task_id: string | null;
@@ -654,7 +753,7 @@ export async function checkEngineHealth(
 
         const seen = new Set<string>();
         for (const row of rows) {
-          if (!artifactExistsOnDisk(basePath, row.path)) continue;
+          if (!artifactExistsOnDisk(basePath, row.path, row)) continue;
           const reopenAt = latestExplicitReopenAt(basePath, row.milestone_id);
           if (!isAfter(row.imported_at, reopenAt)) continue;
           const isSliceSummary = row.slice_id && !row.task_id && row.slice_status && !["complete", "done", "skipped", "closed"].includes(row.slice_status);