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

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

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
 
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
@@ -16,6 +17,8 @@ import { isClosedStatus } from "./status-guards.js";
 import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
 import type { RoadmapSliceEntry } from "./types.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
 import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
@@ -308,6 +311,94 @@ export async function readDoctorHistory(basePath: string, lastN = 50): Promise<D
   } catch { return []; }
 }
 
+/**
+ * Resolve the git working-tree root for a path, or null if it is not a repo.
+ * Used by the workspace-repository probe to check that a declared child path is
+ * itself a git repository (not merely nested inside the parent's repo).
+ */
+function resolveGitToplevel(cwd: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    }).trim();
+    return out ? resolve(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** realpath that falls back to the resolved path if the link cannot be read. */
+function realpathSafe(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/**
+ * Parent-workspace probe (#818): validate that every declared child repository
+ * exists on disk and is a git repository at its own root. The registry only
+ * checks paths stay inside the project root; it never checks existence or
+ * git-ness, so a typo'd path (e.g. `frontned`) would otherwise build cleanly
+ * and silently produce "no problems found." No-op for single-repo projects.
+ */
+function checkWorkspaceRepositoryHealth(
+  basePath: string,
+  prefs: GSDPreferences | undefined,
+  issues: DoctorIssue[],
+): void {
+  if (prefs?.workspace?.mode !== "parent") return;
+  let registry;
+  try {
+    registry = createRepositoryRegistryFromPreferences(basePath, prefs);
+  } catch (err) {
+    issues.push({
+      severity: "error",
+      code: "invalid_preferences",
+      scope: "project",
+      unitId: "workspace",
+      message: `workspace registry failed to build: ${err instanceof Error ? err.message : String(err)}`,
+      fixable: false,
+    });
+    return;
+  }
+  for (const repo of registry.repositories) {
+    if (repo.id === "project") continue;
+    if (!existsSync(repo.root)) {
+      issues.push({
+        severity: "error",
+        code: "workspace_repo_path_missing",
+        scope: "project",
+        unitId: `workspace.repositories.${repo.id}`,
+        message: `declared repository "${repo.id}" path does not exist on disk: ${repo.root}`,
+        fixable: false,
+      });
+      continue;
+    }
+    // Must be a repo at its OWN root — a plain dir nested in the parent repo
+    // would otherwise pass a bare `nativeIsRepo` check via the enclosing
+    // parent's .git. Compare on realpath so symlinked temp roots (macOS
+    // /var vs /private/var) don't cause a false mismatch.
+    const toplevel = resolveGitToplevel(repo.root);
+    const declaredReal = realpathSafe(repo.root);
+    const toplevelReal = toplevel ? realpathSafe(toplevel) : null;
+    if (toplevelReal !== declaredReal) {
+      issues.push({
+        severity: "warning",
+        code: "workspace_repo_not_a_repo",
+        scope: "project",
+        unitId: `workspace.repositories.${repo.id}`,
+        message: `declared repository "${repo.id}" path is not a git repository at its own root: ${repo.root}`,
+        fixable: false,
+      });
+    }
+  }
+}
+
 export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; dryRun?: boolean; scope?: string; fixLevel?: "task" | "all"; isolationMode?: "none" | "worktree" | "branch"; includeBuild?: boolean; includeTests?: boolean }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
@@ -366,6 +457,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
     prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
   await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode, dryRun);
+  checkWorkspaceRepositoryHealth(basePath, prefs?.preferences, issues);
   const gitMs = Date.now() - t0git;
 
   // Runtime health checks — timed
@@ -386,7 +478,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   const envMs = Date.now() - t0env;
 
   // Engine health checks — DB constraints and projection drift
-  await checkEngineHealth(basePath, issues, fixesApplied);
+  await checkEngineHealth(basePath, issues, fixesApplied, { repair: fix && !dryRun });
 
   const milestonesPath = milestonesDir(basePath);
   const legacyMilestonesPath2 = legacyMilestonesDir(basePath);

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -13,6 +13,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { getShellConfig, killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
+import { redactSecrets } from "./redact-secrets.js";
 
 export interface ExecSandboxRequest {
   /** Interpreter to use. */
@@ -315,8 +316,11 @@ export function runExecSandbox(
       const stderrBuf = Buffer.concat(stderrChunks);
       const stdoutSuffix = stdoutTruncated ? "\n[truncated: stdout cap reached]\n" : "";
       const stderrSuffix = stderrTruncated ? "\n[truncated: stderr cap reached]\n" : "";
-      writeFileSync(stdoutPath, Buffer.concat([stdoutBuf, Buffer.from(stdoutSuffix, "utf-8")]));
-      writeFileSync(stderrPath, Buffer.concat([stderrBuf, Buffer.from(stderrSuffix, "utf-8")]));
+      // Redact secret-shaped substrings before persisting to .gsd/exec/ (skipped by
+      // the secret scanner). The returned digest is derived from the raw buffer
+      // below and is redacted downstream when the session is written to activity/.
+      writeFileSync(stdoutPath, redactSecrets(Buffer.concat([stdoutBuf, Buffer.from(stdoutSuffix, "utf-8")]).toString("utf-8")));
+      writeFileSync(stderrPath, redactSecrets(Buffer.concat([stderrBuf, Buffer.from(stderrSuffix, "utf-8")]).toString("utf-8")));
 
       const digestBody = tail(stdoutBuf, opts.digest_chars);
       const digest =

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -6,23 +6,89 @@ import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSyn
 import { join } from "node:path";
 
 import { renderAllFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
-import { getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
+import { deleteArtifactsByPathPrefix, getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
 import { migrateFromMarkdown } from "./md-importer.js";
 import { countDbHierarchy } from "./migration-auto-check.js";
 import { logWarning } from "./workflow-logger.js";
 import { LAYOUT_SEGMENTS } from "./layout-policy.js";
-import { canonicalPhaseDirName, milestonesDir, resolveMilestonePath } from "./paths.js";
+import {
+  canonicalPhaseDirName,
+  dirIsContentBearingLegacyMilestone,
+  milestonesDir,
+  resolveMilestonePath,
+} from "./paths.js";
 
 const LEGACY_MIGRATING_SEGMENT = "milestones.migrating";
+const RETRYABLE_FS_ERROR_CODES = new Set(["EPERM", "EBUSY", "ENOTEMPTY"]);
+const RM_RETRY_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 100 } as const;
+
+type FlatPhaseMigrationFsOps = {
+  cpSync: typeof cpSync;
+  renameSync: typeof renameSync;
+  rmSync: typeof rmSync;
+};
+
+let fsOps: FlatPhaseMigrationFsOps = { cpSync, renameSync, rmSync };
+
+export function _setFlatPhaseMigrationFsOpsForTest(
+  overrides: Partial<FlatPhaseMigrationFsOps>,
+): () => void {
+  const previous = fsOps;
+  fsOps = { ...fsOps, ...overrides };
+  return () => {
+    fsOps = previous;
+  };
+}
 
 function legacyMigratingPath(basePath: string): string {
   return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
 }
 
+function removePathWithRetries(path: string): void {
+  fsOps.rmSync(path, { recursive: true, force: true, maxRetries: RM_RETRY_OPTIONS.maxRetries, retryDelay: RM_RETRY_OPTIONS.retryDelay });
+}
+
+function isRetryableFsError(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code;
+  return typeof code === "string" && RETRYABLE_FS_ERROR_CODES.has(code);
+}
+
+function movePathWithCopyDeleteFallback(src: string, dst: string): void {
+  try {
+    fsOps.renameSync(src, dst);
+    return;
+  } catch (err) {
+    if (!isRetryableFsError(err)) throw err;
+  }
+
+  try {
+    fsOps.cpSync(src, dst, { recursive: true, force: true });
+    removePathWithRetries(src);
+  } catch (fallbackErr) {
+    if (existsSync(src) && existsSync(dst)) {
+      try {
+        removePathWithRetries(dst);
+      } catch {
+        // Leave the original error intact; the next run can pre-clean dst.
+      }
+    }
+    throw fallbackErr;
+  }
+}
+
+function expectedPhaseDirs(basePath: string): string[] {
+  return getAllMilestones().map((milestone) =>
+    resolveMilestonePath(basePath, milestone.id) ??
+      join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title)),
+  );
+}
+
 function hasLegacyMilestoneSubdirs(dirPath: string): boolean {
   if (!existsSync(dirPath)) return false;
   try {
-    return readdirSync(dirPath).some(e => statSync(join(dirPath, e)).isDirectory());
+    return readdirSync(dirPath).some(
+      (e) => statSync(join(dirPath, e)).isDirectory() && dirIsContentBearingLegacyMilestone(join(dirPath, e)),
+    );
   } catch {
     return false;
   }
@@ -34,19 +100,26 @@ function rollbackPartialMigration(
   migratingPath?: string,
 ): void {
   // Remove the partially-written phases/ dir.
-  rmSync(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1), { recursive: true, force: true });
+  try {
+    removePathWithRetries(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1));
+  } catch (removeErr) {
+    logWarning(
+      "migration",
+      `rollback: could not remove partial ${LAYOUT_SEGMENTS.level1}/: ${(removeErr as Error).message}`,
+    );
+  }
   // Restore milestones/ — prefer renaming the preserved migrating copy back.
   const milestonesPath = join(basePath, ".gsd", "milestones");
   try {
     if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
-      renameSync(migratingPath, milestonesPath);
+      movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
       return;
     }
     if (existsSync(backupDir)) {
       cpSync(backupDir, milestonesPath, { recursive: true });
     }
     if (migratingPath && existsSync(migratingPath)) {
-      rmSync(migratingPath, { recursive: true, force: true });
+      removePathWithRetries(migratingPath);
     }
   } catch (restoreErr) {
     logWarning(
@@ -122,7 +195,8 @@ export function pruneStaleFlatPhaseBackups(basePath: string): number {
  * 2. Rename .gsd/milestones/ aside so path resolvers target phases/
  * 3. Render flat-phase from the DB (which already has the data)
  * 4. Verify counts match
- * 5. Remove the renamed legacy tree
+ * 5. Prune legacy milestones/ artifact rows
+ * 6. Remove the renamed legacy tree
  *
  * Idempotent: if .gsd/milestones/ doesn't exist, returns immediately.
  */
@@ -162,18 +236,29 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       throw err;
     }
 
+    if (existsSync(migratingPath)) {
+      removePathWithRetries(migratingPath);
+    }
+
     // 3. Rename legacy tree aside before rendering so path resolvers target
     // phases/ instead of writing back into the nested milestones/ layout.
     // Keep the full tree on disk until render+verify succeed (unlike rmSync).
     try {
-      renameSync(milestonesPath, migratingPath);
+      movePathWithCopyDeleteFallback(milestonesPath, migratingPath);
     } catch (err) {
       logWarning("migration", `failed to rename legacy milestones/ before render: ${(err as Error).message}`);
       throw err;
     }
-  } else {
-    // Interrupted run: clear any partial phases/ projection before retrying.
-    rmSync(phasesPath, { recursive: true, force: true });
+  }
+
+  // Clear any stale or partially-rendered flat projection before this run
+  // writes. Verification below checks the current DB render, not leftovers.
+  try {
+    removePathWithRetries(phasesPath);
+  } catch (err) {
+    logWarning("migration", `failed to clear stale phases/ before render: ${(err as Error).message}`);
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw err;
   }
 
   // 4. Render flat-phase from DB
@@ -211,22 +296,14 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
   }
 
   const db = countDbHierarchy();
-  let renderedDirCount = 0;
-  try {
-    // /^\d+-/ matches any numeric prefix (01-, 10-, 100-) so M100+ milestones
-    // whose dirs start with "100-slug" are counted correctly.
-    renderedDirCount = readdirSync(phasesPath, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory() && /^\d+-/.test(entry.name)).length;
-  } catch {
-    // phases/ doesn't exist or is unreadable — same as zero dirs
-  }
-  if (db.milestones > 0 && renderedDirCount !== db.milestones) {
+  const missingPhaseDirs = expectedPhaseDirs(basePath).filter((phaseDir) => !existsSync(phaseDir));
+  if (db.milestones > 0 && missingPhaseDirs.length > 0) {
     logWarning(
       "migration",
-      `phases/ dir count mismatch: expected ${db.milestones}, found ${renderedDirCount}`,
+      `flat-phase migration missing ${missingPhaseDirs.length} expected phase dir(s): ${missingPhaseDirs.join(", ")}`,
     );
     rollbackPartialMigration(basePath, backupDir, migratingPath);
-    throw new Error("flat-phase migration verification failed: phases dir milestone count mismatch");
+    throw new Error("flat-phase migration verification failed: missing rendered phase directories");
   }
   if (db.slices > 0 && renderResult.rendered === 0) {
     logWarning(
@@ -237,9 +314,19 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
     throw new Error("flat-phase migration verification failed: no artifacts rendered");
   }
 
-  // 6. Verified — remove the renamed legacy tree (backup already on disk).
+  // 6. Verified — prune legacy artifact rows now that renderAllFromDb has
+  // re-inserted flat-phase rows for artifacts that still have files.
+  try {
+    deleteArtifactsByPathPrefix("milestones/");
+  } catch (err) {
+    logWarning("migration", `flat-phase migration could not prune legacy artifact rows: ${(err as Error).message}`);
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw err;
+  }
+
+  // 7. Remove the renamed legacy tree (backup already on disk).
   try {
-    rmSync(migratingPath, { recursive: true, force: true });
+    removePathWithRetries(migratingPath);
   } catch (err) {
     logWarning(
       "migration",

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

@@ -30,7 +30,7 @@ import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { isDbAvailable, getHierarchyCompletionCounts } from "./gsd-db.js";
 import { formatDuration } from "../shared/format-utils.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import {

package/src/resources/extensions/gsd/git-conflict-resolve.ts

@@ -7,9 +7,9 @@ import {
   nativeCheckoutTheirs,
   nativeRmForce,
 } from "./native-git-bridge.js";
-import { isSafeToAutoResolve } from "./auto-worktree.js";
+import { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
 
-export { isSafeToAutoResolve } from "./auto-worktree.js";
+export { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
 
 export interface AutoResolveSafePathsResult {
   resolved: string[];

package/src/resources/extensions/gsd/git-service.ts

@@ -18,7 +18,7 @@ import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { logWarning } from "./workflow-logger.js";
-import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
+import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets } from "./repository-registry.js";
 import { isGsdGitignored } from "./gitignore.js";
 
 
@@ -704,6 +704,59 @@ export function runGit(basePath: string, args: string[], options: { allowFailure
   }
 }
 
+/**
+ * Arguments for creating a task/workflow branch.
+ *
+ * When the current branch is a leftover GSD task branch (workflow template,
+ * quick task, or slice), the new branch starts from `baseBranch` — the
+ * caller's resolved integration branch, normally `GitServiceImpl.getMainBranch()`
+ * so `main_branch` preference, milestone integration branch, and worktree base
+ * all take priority over repo-default detection. Branching from HEAD there
+ * silently stacks consecutive workflow branches on top of each other, so every
+ * new gsd/* branch (and its eventual PR) drags along the previous workflow's
+ * commits.
+ *
+ * On any other branch (a user's feature branch, a worktree base, the main
+ * branch itself) the legacy branch-from-HEAD behavior is kept: basing new work
+ * on the branch the user chose to stand on is intentional there.
+ *
+ * Falls back to branch-from-HEAD, with a logged warning, when the base branch
+ * has no local ref or the working tree is still dirty (a start point that
+ * changes the tree would abort the checkout or strand in-flight changes).
+ * The base is the local ref — deliberately no fetch, so branch creation stays
+ * offline-safe even if the local base is behind its remote.
+ */
+export function taskBranchArgs(basePath: string, branchName: string, currentBranch: string, baseBranch: string): string[] {
+  const args = ["checkout", "-b", branchName];
+  const onTaskBranch =
+    WORKFLOW_BRANCH_RE.test(currentBranch) ||
+    QUICK_BRANCH_RE.test(currentBranch) ||
+    SLICE_BRANCH_RE.test(currentBranch);
+  if (!onTaskBranch || !baseBranch || baseBranch === currentBranch) return args;
+  try {
+    if (!nativeBranchExists(basePath, baseBranch)) {
+      logWarning(
+        "engine",
+        `taskBranchArgs: base branch "${baseBranch}" has no local ref — branching ${branchName} from HEAD (${currentBranch})`,
+        { file: "git-service.ts" },
+      );
+      return args;
+    }
+    if (nativeHasChanges(basePath)) {
+      logWarning(
+        "engine",
+        `taskBranchArgs: working tree still dirty after auto-commit — branching ${branchName} from HEAD (${currentBranch}) to preserve in-flight changes`,
+        { file: "git-service.ts" },
+      );
+      return args;
+    }
+  } catch {
+    return args;
+  }
+  args.push(baseBranch);
+  return args;
+}
+
 // ─── Commit Type Inference ─────────────────────────────────────────────────
 
 /**
@@ -1266,26 +1319,25 @@ export function handleTurnGitActionError(action: TurnGitActionMode, err: unknown
   };
 }
 
+export function isRepositoryDirty(repoRoot: string): boolean {
+  try {
+    return runGit(repoRoot, ["status", "--porcelain"]).length > 0;
+  } catch {
+    // Fallback preserves legacy behavior if explicit status probing fails.
+    return nativeHasChanges(repoRoot);
+  }
+}
+
 function collectRepositoryDirtyStatus(basePath: string): Record<string, boolean> {
   const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
   const registry = createRepositoryRegistryFromPreferences(basePath, preferences);
   const dirtyByRepository: Record<string, boolean> = {};
   const registeredRoots = new Set(registry.repositories.map((repo) => resolve(repo.root)));
   for (const repo of registry.repositories) {
-    try {
-      dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
-    } catch {
-      // Fallback preserves legacy behavior if explicit status probing fails.
-      dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
-    }
+    dirtyByRepository[repo.id] = isRepositoryDirty(repo.root);
   }
   for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
-    let dirty = false;
-    try {
-      dirty = runGit(repoRoot, ["status", "--porcelain"]).length > 0;
-    } catch {
-      dirty = nativeHasChanges(repoRoot);
-    }
+    const dirty = isRepositoryDirty(repoRoot);
     if (!dirty) continue;
 
     const relPath = relative(registry.projectRoot, repoRoot).split(sep).join("/") || repoRoot;
@@ -1357,7 +1409,7 @@ function runPerRepositoryCommitAction(args: {
 } {
   const preferences = loadEffectiveGSDPreferences(args.basePath)?.preferences;
   const registry = createRepositoryRegistryFromPreferences(args.basePath, preferences);
-  const repoIds = args.targetRepositories?.length ? args.targetRepositories : ["project"];
+  const repoIds = args.targetRepositories?.length ? args.targetRepositories : defaultRepositoryTargets(registry);
   const gitPrefs = preferences?.git ?? {};
   const commitMessages: Record<string, string> = {};
   const commitErrors: Record<string, string> = {};
@@ -1445,9 +1497,7 @@ export function runTurnGitAction(args: {
       };
     }
 
-    const primaryMessage =
-      repoCommitResult.commitMessages[args.targetRepositories?.[0] ?? "project"]
-      ?? Object.values(repoCommitResult.commitMessages)[0];
+    const primaryMessage = Object.values(repoCommitResult.commitMessages)[0];
     return {
       action: args.action,
       status: "ok",

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

@@ -535,6 +535,78 @@ export function updateTaskStatus(milestoneId: string, sliceId: string, taskId: s
   applyStatusTransition({ entity: "task", milestoneId, sliceId, taskId, status, completedAt });
 }
 
+export function repairTaskCompletionFromSummary(t: {
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  title?: string;
+  oneLiner?: string;
+  narrative?: string;
+  verificationResult: string;
+  duration?: string;
+  completedAt: string;
+  blockerDiscovered?: boolean;
+  deviations?: string;
+  knownIssues?: string;
+  keyFiles?: string[];
+  keyDecisions?: string[];
+  fullSummaryMd: string;
+}): void {
+  const db = getDbOrNull();
+  if (!db) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  transaction(() => {
+    const seq = db.prepare(
+      `SELECT COALESCE(MAX(sequence), 0) + 1 AS next_sequence
+       FROM tasks
+       WHERE milestone_id = :mid AND slice_id = :sid`,
+    ).get({ ":mid": t.milestoneId, ":sid": t.sliceId }) as { next_sequence?: number } | undefined;
+    db.prepare(
+      `INSERT INTO tasks (
+        milestone_id, slice_id, id, title, status, one_liner, narrative,
+        verification_result, duration, completed_at, blocker_discovered,
+        deviations, known_issues, key_files, key_decisions, full_summary_md,
+        sequence
+      ) VALUES (
+        :milestone_id, :slice_id, :id, :title, 'complete', :one_liner, :narrative,
+        :verification_result, :duration, :completed_at, :blocker_discovered,
+        :deviations, :known_issues, :key_files, :key_decisions, :full_summary_md,
+        :sequence
+      )
+      ON CONFLICT(milestone_id, slice_id, id) DO UPDATE SET
+        title = CASE WHEN NULLIF(:title, '') IS NOT NULL THEN :title ELSE tasks.title END,
+        status = 'complete',
+        one_liner = CASE WHEN NULLIF(:one_liner, '') IS NOT NULL THEN :one_liner ELSE tasks.one_liner END,
+        narrative = CASE WHEN NULLIF(:narrative, '') IS NOT NULL THEN :narrative ELSE tasks.narrative END,
+        verification_result = :verification_result,
+        duration = CASE WHEN NULLIF(:duration, '') IS NOT NULL THEN :duration ELSE tasks.duration END,
+        completed_at = :completed_at,
+        blocker_discovered = :blocker_discovered,
+        deviations = CASE WHEN NULLIF(:deviations, '') IS NOT NULL THEN :deviations ELSE tasks.deviations END,
+        known_issues = CASE WHEN NULLIF(:known_issues, '') IS NOT NULL THEN :known_issues ELSE tasks.known_issues END,
+        key_files = :key_files,
+        key_decisions = :key_decisions,
+        full_summary_md = :full_summary_md`,
+    ).run({
+      ":milestone_id": t.milestoneId,
+      ":slice_id": t.sliceId,
+      ":id": t.taskId,
+      ":title": t.title ?? "",
+      ":one_liner": t.oneLiner ?? "",
+      ":narrative": t.narrative ?? "",
+      ":verification_result": t.verificationResult,
+      ":duration": t.duration ?? "",
+      ":completed_at": t.completedAt,
+      ":blocker_discovered": t.blockerDiscovered ? 1 : 0,
+      ":deviations": t.deviations ?? "",
+      ":known_issues": t.knownIssues ?? "",
+      ":key_files": JSON.stringify(t.keyFiles ?? []),
+      ":key_decisions": JSON.stringify(t.keyDecisions ?? []),
+      ":full_summary_md": t.fullSummaryMd,
+      ":sequence": seq?.next_sequence ?? 1,
+    });
+  });
+}
+
 export function setTaskBlockerDiscovered(milestoneId: string, sliceId: string, taskId: string, discovered: boolean): void {
   if (!getDbOrNull()!) return;
   getDbOrNull()!.prepare(
@@ -1325,6 +1397,19 @@ export function deleteArtifactByPath(path: string): void {
   getDbOrNull()!.prepare("DELETE FROM artifacts WHERE path = :path").run({ ":path": path });
 }
 
+/** Delete artifact rows whose paths share a DB-relative prefix. */
+export function deleteArtifactsByPathPrefix(prefix: string): number {
+  if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  return transaction(() => {
+    const likePrefix = `${prefix}%`;
+    const countRow = getDbOrNull()!.prepare(
+      "SELECT COUNT(*) AS count FROM artifacts WHERE path LIKE :prefix",
+    ).get({ ":prefix": likePrefix });
+    getDbOrNull()!.prepare("DELETE FROM artifacts WHERE path LIKE :prefix").run({ ":prefix": likePrefix });
+    return Number(countRow?.["count"] ?? 0);
+  });
+}
+
 /**
  * Drop hierarchy rows in dependency order inside a transaction. Used by
  * `gsd recover --confirm` to rebuild engine state from markdown.

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

@@ -209,6 +209,8 @@ const DOCTOR_FIX_HINTS: Partial<Record<DoctorIssueCode, string>> = {
   state_file_stale: "Run `/gsd doctor fix` to rebuild the projection from the database.",
   state_file_missing: "Run `/gsd doctor fix` to rebuild the projection from the database.",
   projection_drift: "Run `/gsd doctor fix` to rebuild markdown projections from the database (DB is the source of truth).",
+  artifact_user_content_missing:
+    "Doctor cannot recreate user-authored content from the database. Re-run `/gsd discuss` for CONTEXT artifacts or `/gsd auto` for RESEARCH artifacts in that milestone.",
   uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
 };