@opengsd/gsd-pi 1.4.0-dev.c18009cd → 1.5.0-dev.553dc518

package/src/resources/extensions/gsd/auto.ts

@@ -177,24 +177,18 @@ import {
 import { GitServiceImpl } from "./git-service.js";
 import { nativeCheckoutBranch } from "./native-git-bridge.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
-import {
-  createAutoWorktree,
-  enterAutoWorktree,
-  enterBranchModeForMilestone,
-  teardownAutoWorktree,
-  isInAutoWorktree,
-  getAutoWorktreePath,
-  getAutoWorktreeOriginalBase,
-  mergeMilestoneToMain,
-  autoWorktreeBranch,
-  syncWorktreeStateBack,
-  readResourceVersion,
-  checkResourcesStale,
-  escapeStaleWorktree,
-} from "./auto-worktree.js";
+import { autoWorktreeBranch, enterBranchModeForMilestone } from "./auto-worktree-branch-lifecycle.js";
+import { createAutoWorktree } from "./auto-worktree-creation.js";
+import { enterAutoWorktree, isInAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
+import { checkResourcesStale, readResourceVersion } from "./auto-worktree-resource-version.js";
+import { escapeStaleWorktree } from "./auto-worktree-runtime-cleanup.js";
+import { getAutoWorktreeOriginalBase } from "./auto-worktree-session-registry.js";
+import { syncWorktreeStateBack } from "./auto-worktree-sync.js";
+import { teardownAutoWorktree } from "./auto-worktree-teardown.js";
 import { pruneQueueOrder } from "./queue-order.js";
 import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
-import { createMilestoneMergeTransaction } from "./milestone-merge-transaction.js";
+import { createDefaultMilestoneMergeTransaction } from "./milestone-merge-transaction.js";
 
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import {
@@ -2326,7 +2320,7 @@ export function buildWorktreeLifecycleDeps(): WorktreeLifecycleDeps {
       return new GitServiceImpl(basePath, gitConfig);
     },
     worktreeProjection: new WorktreeStateProjection(),
-    mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
+    mergeMilestone: createDefaultMilestoneMergeTransaction(),
   };
 }
 

package/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -14,7 +14,7 @@ import {
   type WorkflowDatabaseOpenResult,
   type WorkflowDatabaseStatus,
 } from "../db-workspace.js";
-import { getAutoWorktreePath } from "../auto-worktree.js";
+import { getAutoWorktreePath } from "../auto-worktree-path-resolution.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
 

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -40,7 +40,7 @@ import {
 } from "../auto-tool-tracking.js";
 import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
 
-import { checkToolCallLoop, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { checkToolCallLoop, configureToolCallLoopGuard, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
 import { saveActivityLog } from "../activity-log.js";
@@ -594,6 +594,22 @@ async function applyCompactionThresholdOverride(ctx: ExtensionContext): Promise<
   }
 }
 
+/**
+ * Apply user-tunable tool-call loop guard thresholds (#1198) from GSD
+ * preferences plus GSD_TOOL_LOOP_* env overrides. Runs at session boundaries
+ * so both interactive sessions and `/gsd auto` pick up the configuration.
+ * Non-fatal: falls back to built-in defaults when preferences cannot be loaded.
+ */
+async function applyToolCallLoopGuardConfig(basePath: string): Promise<void> {
+  try {
+    const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+    const prefs = loadEffectiveGSDPreferences(basePath);
+    configureToolCallLoopGuard(prefs?.preferences.tool_call_loop_guard);
+  } catch {
+    configureToolCallLoopGuard(null);
+  }
+}
+
 function clearDeferredApprovalGate(basePath?: string): void {
   if (!basePath) {
     deferredApprovalGates.clear();
@@ -996,6 +1012,7 @@ export function registerHooks(
     }
     resetWriteGateState(basePath);
     resetToolCallLoopGuard();
+    await applyToolCallLoopGuardConfig(basePath);
     approvalQuestionAbortInFlight = false;
     clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
@@ -1087,6 +1104,7 @@ export function registerHooks(
     initSessionNotifications(ctx);
     resetWriteGateState(basePath);
     resetToolCallLoopGuard();
+    await applyToolCallLoopGuardConfig(basePath);
     clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
     clearDiscussionFlowState(basePath);

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -14,7 +14,7 @@ import { resolveModelWithFallbacksForUnit } from "../preferences-models.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
 import { extractIntroAndRules } from "../knowledge-parser.js";
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
-import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
+import { getActiveAutoWorktreeContext } from "../auto-worktree-session-registry.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-session-state.js";
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -21,6 +21,11 @@
  * signature, so the identical-args streak never trips, while allowing
  * tool-heavy turns that are making file-mutation progress. Whichever guard
  * trips first blocks.
+ *
+ * Thresholds, exempt tools, and enable flags are user-tunable (#1198) via the
+ * `tool_call_loop_guard` key in `.gsd/PREFERENCES.md` and `GSD_TOOL_LOOP_*`
+ * environment variables, applied through {@link configureToolCallLoopGuard}.
+ * Defaults preserve the original hardcoded behavior.
  */
 
 import { createHash } from "node:crypto";
@@ -28,26 +33,143 @@ import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
 import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
 import { canonicalToolName } from "../engine-hook-contract.js";
 
-const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
+/** Built-in defaults. Preserved when preferences/env do not override them. */
+const DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
+const DEFAULT_PER_TOOL_DEFAULT_CAP = 6;
+const DEFAULT_PER_TOOL_REPEATABLE_CAP = 15;
+const DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS = ["find", "glob", "grep", "ls", "read", "search_and_read"] as const;
 
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
 
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+
 /**
- * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ * User-tunable configuration shape for the loop guard (#1198).
  *
- * General-purpose execution tools are routinely called many times per turn
- * (touching multiple files, running several commands), so they get a higher
- * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
- * and any non-allowlisted tool — gets the default cap. The default is generous
- * enough to absorb legitimate retries but catches the reported improvisation
- * loop (~51 calls) well before a cost spike.
+ * Mirrors the `tool_call_loop_guard` key in `.gsd/PREFERENCES.md`. All fields
+ * are optional; anything omitted falls back to the built-in defaults so that
+ * existing installs keep their current behavior.
  */
-const PER_TOOL_DEFAULT_CAP = 6;
-const PER_TOOL_REPEATABLE_CAP = 15;
-const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
-const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+export interface ToolCallLoopGuardConfig {
+  enabled?: boolean;
+  identical_args?: {
+    enabled?: boolean;
+    max_consecutive_calls?: number;
+  };
+  repeated_tool?: {
+    enabled?: boolean;
+    default_cap?: number;
+    repeatable_cap?: number;
+    exempt_tools?: string[];
+  };
+}
+
+/**
+ * Active, resolved configuration. Set by {@link configureToolCallLoopGuard}
+ * from preferences + environment overrides, and deliberately NOT touched by
+ * {@link resetToolCallLoopGuard} so a session's tuning survives turn
+ * boundaries.
+ */
+interface ResolvedGuardConfig {
+  /** Master switch for both guards. */
+  guardEnabled: boolean;
+  identicalEnabled: boolean;
+  maxConsecutiveIdentical: number;
+  repeatedEnabled: boolean;
+  perToolDefaultCap: number;
+  perToolRepeatableCap: number;
+  /** Tool names exempt from Guard 2 (per-tool-name cap). */
+  perToolExempt: Set<string>;
+}
+
+function defaultGuardConfig(): ResolvedGuardConfig {
+  return {
+    guardEnabled: true,
+    identicalEnabled: true,
+    maxConsecutiveIdentical: DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS,
+    repeatedEnabled: true,
+    perToolDefaultCap: DEFAULT_PER_TOOL_DEFAULT_CAP,
+    perToolRepeatableCap: DEFAULT_PER_TOOL_REPEATABLE_CAP,
+    perToolExempt: new Set<string>(DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS),
+  };
+}
+
+let config: ResolvedGuardConfig = defaultGuardConfig();
+
+/** Parse a positive-integer env var, returning undefined when unset/invalid. */
+function envPositiveInt(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+}
+
+/** Parse a boolean env var (`true`/`1` vs `false`/`0`), undefined when unset. */
+function envBool(name: string): boolean | undefined {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return undefined;
+  const v = raw.trim().toLowerCase();
+  if (v === "true" || v === "1" || v === "yes" || v === "on") return true;
+  if (v === "false" || v === "0" || v === "no" || v === "off") return false;
+  return undefined;
+}
+
+/** Parse a comma-separated tool-name list env var. */
+function envToolList(name: string): string[] {
+  const raw = process.env[name];
+  if (!raw) return [];
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Resolve preferences + environment overrides into the active configuration.
+ * Environment variables win over preferences; preferences win over built-in
+ * defaults. User-supplied exempt tools are additive to the built-in exempt
+ * set so defaults are always preserved.
+ *
+ * Applied to both interactive sessions and `/gsd auto` (called from the
+ * session_start / session_switch hooks).
+ */
+export function configureToolCallLoopGuard(prefs?: ToolCallLoopGuardConfig | null): void {
+  const next = defaultGuardConfig();
+
+  if (prefs) {
+    if (typeof prefs.enabled === "boolean") next.guardEnabled = prefs.enabled;
+    if (prefs.identical_args) {
+      if (typeof prefs.identical_args.enabled === "boolean") next.identicalEnabled = prefs.identical_args.enabled;
+      if (typeof prefs.identical_args.max_consecutive_calls === "number" && prefs.identical_args.max_consecutive_calls >= 1) {
+        next.maxConsecutiveIdentical = Math.floor(prefs.identical_args.max_consecutive_calls);
+      }
+    }
+    if (prefs.repeated_tool) {
+      if (typeof prefs.repeated_tool.enabled === "boolean") next.repeatedEnabled = prefs.repeated_tool.enabled;
+      if (typeof prefs.repeated_tool.default_cap === "number" && prefs.repeated_tool.default_cap >= 1) {
+        next.perToolDefaultCap = Math.floor(prefs.repeated_tool.default_cap);
+      }
+      if (typeof prefs.repeated_tool.repeatable_cap === "number" && prefs.repeated_tool.repeatable_cap >= 1) {
+        next.perToolRepeatableCap = Math.floor(prefs.repeated_tool.repeatable_cap);
+      }
+      for (const tool of prefs.repeated_tool.exempt_tools ?? []) {
+        if (typeof tool === "string" && tool.trim()) next.perToolExempt.add(tool.trim());
+      }
+    }
+  }
+
+  // Environment overrides (win over preferences).
+  const envEnabled = envBool("GSD_TOOL_LOOP_GUARD_ENABLED");
+  if (envEnabled !== undefined) next.guardEnabled = envEnabled;
+  const envIdenticalMax = envPositiveInt("GSD_TOOL_LOOP_IDENTICAL_MAX");
+  if (envIdenticalMax !== undefined) next.maxConsecutiveIdentical = envIdenticalMax;
+  const envDefaultCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_DEFAULT_CAP");
+  if (envDefaultCap !== undefined) next.perToolDefaultCap = envDefaultCap;
+  const envRepeatableCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_REPEATABLE_CAP");
+  if (envRepeatableCap !== undefined) next.perToolRepeatableCap = envRepeatableCap;
+  for (const tool of envToolList("GSD_TOOL_LOOP_EXEMPT_TOOLS")) next.perToolExempt.add(tool);
+
+  config = next;
+}
 
 let consecutiveCount = 0;
 let lastSignature = "";
@@ -82,17 +204,20 @@ function hashToolCall(toolName: string, args: Record<string, unknown>): string {
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
  *
  * Two independent guards run; whichever trips first blocks:
- *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *  1. Identical-signature streak (config.maxConsecutiveIdentical, strict for
  *     ask_user_questions).
- *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *  2. Per-tool-name cap (config.perToolDefaultCap / config.perToolRepeatableCap),
  *     independent of args, reset after file-mutation progress — catches
  *     improvisation loops (#783).
+ *
+ * Both guards, their thresholds, and the per-tool exempt set are user-tunable
+ * via {@link configureToolCallLoopGuard} (#1198).
  */
 export function checkToolCallLoop(
   toolName: string,
   args: Record<string, unknown>,
 ): { block: boolean; reason?: string; count?: number } {
-  if (!enabled) return { block: false, count: 0 };
+  if (!enabled || !config.guardEnabled) return { block: false, count: 0 };
 
   const sig = hashToolCall(toolName, args);
 
@@ -107,14 +232,16 @@ export function checkToolCallLoop(
   // ── Guard 1: identical-signature streak ──
   const threshold = STRICT_LOOP_TOOLS.has(toolName)
     ? MAX_CONSECUTIVE_STRICT
-    : MAX_CONSECUTIVE_IDENTICAL_CALLS;
+    : config.maxConsecutiveIdentical;
 
-  if (consecutiveCount > threshold) {
+  if (config.identicalEnabled && consecutiveCount > threshold) {
     return {
       block: true,
       reason:
         `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
-        `with identical arguments. Blocking to prevent infinite loop. ` +
+        `with identical arguments (max ${threshold}). Blocking to prevent infinite loop. ` +
+        `Raise tool_call_loop_guard.identical_args.max_consecutive_calls in .gsd/PREFERENCES.md ` +
+        `(or GSD_TOOL_LOOP_IDENTICAL_MAX) if this is expected. ` +
         `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
       count: consecutiveCount,
     };
@@ -139,15 +266,16 @@ export function checkToolCallLoop(
   // Guard 1's identical-signature streak still catches a genuinely stuck
   // browser loop.
   if (
-    PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName) ||
+    !config.repeatedEnabled ||
+    config.perToolExempt.has(toolName) ||
     hasBrowserContractPrefix(canonicalToolName(toolName))
   ) {
     return { block: false, count: consecutiveCount };
   }
 
   const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
-    ? PER_TOOL_REPEATABLE_CAP
-    : PER_TOOL_DEFAULT_CAP;
+    ? config.perToolRepeatableCap
+    : config.perToolDefaultCap;
 
   if (perToolCount > perToolCap) {
     return {
@@ -156,6 +284,9 @@ export function checkToolCallLoop(
         `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
         `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
         `The tool may be unavailable or failing repeatedly. ` +
+        `Raise tool_call_loop_guard.repeated_tool.default_cap/repeatable_cap or add "${toolName}" ` +
+        `to tool_call_loop_guard.repeated_tool.exempt_tools in .gsd/PREFERENCES.md ` +
+        `(or GSD_TOOL_LOOP_REPEATED_* / GSD_TOOL_LOOP_EXEMPT_TOOLS) if this is expected. ` +
         `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
       count: perToolCount,
     };

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/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/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);