@opengsd/gsd-pi 1.4.0 → 1.5.0

package/src/resources/extensions/gsd/discussion-handoff.ts

@@ -82,7 +82,13 @@ function ensureMilestoneRowForAcceptedHandoff(
   entry: PendingAutoStartEntry,
   contextFile: string | null,
 ): boolean {
-  if (!isDbAvailable()) return true;
+  if (!isDbAvailable()) {
+    logWarning(
+      "guided",
+      `R3b: milestone ${entry.milestoneId} DB-row recovery skipped because DB is unavailable`,
+    );
+    return false;
+  }
 
   const { basePath, milestoneId } = entry;
   const milestoneRow = getMilestone(milestoneId);
@@ -122,12 +128,14 @@ function ensureMilestoneRowForAcceptedHandoff(
     `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`,
   );
 
+  let inserted = false;
   try {
-    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+    inserted = insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
   } catch (e) {
     logWarning("guided", `R3b: insertMilestone failed: ${(e as Error).message}`);
   }
 
+  if (inserted) return true;
   if (getMilestone(milestoneId)) return true;
 
   noteDbRowRecoveryMiss(entry);

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

@@ -163,7 +163,7 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - **Deprecated:** `merge_to_main` — no longer valid; milestone-level merge is always used. Remove this setting.
 
 - `workspace`: configures multi-repository parent workspaces. Keys:
-  - `mode`: `"project"` (default single-repo behavior) or `"parent"` (one `.gsd` controlling child repos).
+  - `mode`: `"project"` (default single-repo behavior) or `"parent"` (one `.gsd` controlling child repos). In `"parent"` mode at least one child repository must be declared under `repositories`, otherwise the setting is rejected at validation time.
   - `repositories`: object map of repository IDs to config.
     - Repository ID format: `^[A-Za-z0-9][A-Za-z0-9._-]*$`.
     - Reserved ID: `project` is implicit and always maps to the project root; user-defined `workspace.repositories.project` is rejected.
@@ -171,6 +171,8 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
     - `role`: optional short description of what the repo owns.
     - `verification`: optional array of verification commands for that repo.
     - `commit_policy`: optional `"auto"` or `"skip"` to include or skip commit actions per repo.
+  - Planning tools consume repository IDs through `targetRepositories`: `gsd_plan_slice.targetRepositories` sets a slice-wide default, and `gsd_plan_task.targetRepositories` records the repositories an individual task touches. Values must be declared IDs or the implicit `project`; omit these fields in single-repo projects.
+  - In parent mode with declared child repositories, `/gsd codebase generate` and automatic `.gsd/CODEBASE.md` refreshes enumerate `project` plus each child repository, render repo-labeled sections, and store repository IDs in map metadata.
 
 ## Workspace Example
 
@@ -198,6 +200,8 @@ workspace:
 
 This config sets a parent workspace with two child repositories. The implicit `project` repository is always created for the project root and cannot be user-defined.
 
+In `"parent"` mode, slice/task `targetRepositories` default to the declared child repositories (here `frontend` and `backend`) rather than the root `project` repo. In `"project"` mode (the default), `targetRepositories` defaults to `["project"]`.
+
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 
 - `budget_ceiling`: number — maximum dollar amount to spend on auto-mode. When reached, behavior is controlled by `budget_enforcement`. Default: no limit.
@@ -303,7 +307,9 @@ This config sets a parent workspace with two child repositories. The implicit `p
     - `verification`: string[] (optional) — repository-specific verification commands used when global `verification_commands` is not set.
     - `commit_policy`: `"auto"` | `"skip"` (optional) — per-repository closeout commit behavior.
   - `project` is always an implicit repository target mapped to the project root for backward compatibility.
-  - Plan/task `targetRepositories` defaults to `["project"]` when omitted.
+  - `targetRepositories` on `gsd_plan_slice` sets the slice-wide default. `targetRepositories` on `gsd_plan_task` records or overrides the repository IDs for an individual task.
+  - Values must match declared repository IDs or the implicit `project`; omitted plan/task `targetRepositories` defaults to `["project"]`.
+  - `/gsd codebase` is workspace-aware in parent mode with declared child repositories: generated `.gsd/CODEBASE.md` uses workspace-relative paths, groups files under `## [repo-id]` headings, and refreshes when repository registry metadata changes.
 
 - `verification_commands`: string[] — shell commands to run as verification after task execution (e.g., `["npm test", "npm run lint"]`). Commands run in order; if any fails, the task is marked as needing fixes.
 

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

@@ -1,13 +1,15 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { isAbsolute, join, relative, sep } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
 import {
+  deleteArtifactByPath,
   getAllMilestones,
   getMilestoneSlices,
   getSliceTasks,
   isDbAvailable,
   isMemoriesFtsAvailable,
+  repairTaskCompletionFromSummary,
   _getAdapter,
 } from "./gsd-db.js";
 import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
@@ -20,11 +22,47 @@ import { readEvents } from "./workflow-events.js";
 import { flushWorkflowProjections } from "./projection-flush.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { parsePlan } from "./parsers-legacy.js";
+import { parseSummary } from "./files.js";
+
+const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 function relativeFile(basePath: string, filePath: string): string {
   return relative(basePath, filePath).split("\\").join("/");
 }
 
+function normalizedArtifactType(artifactType: string): string {
+  return artifactType.trim().toUpperCase();
+}
+
+function isUserAuthoredArtifactType(artifactType: string): boolean {
+  return USER_AUTHORED_ARTIFACT_TYPES.has(normalizedArtifactType(artifactType));
+}
+
+function userContentRecoveryCommand(artifactType: string): string {
+  return normalizedArtifactType(artifactType) === "CONTEXT" ? "/gsd discuss" : "/gsd auto";
+}
+
+function userContentMissingMessage(path: string, artifactType: string): string {
+  const type = normalizedArtifactType(artifactType) || "UNKNOWN";
+  return `Artifact \`${path}\` is a user-authored ${type} file recorded in the database but missing from disk. Re-run \`${userContentRecoveryCommand(type)}\` in this milestone to regenerate it.`;
+}
+
+function artifactPathRelativeToGsd(artifactPath: string): string {
+  const parts = artifactPath.split(/[\\/]+/);
+  const gsdIndex = parts.lastIndexOf(".gsd");
+  if (gsdIndex < 0 || gsdIndex === parts.length - 1) return artifactPath;
+  return parts.slice(gsdIndex + 1).join("/");
+}
+
+function isPathInside(basePath: string, candidatePath: string): boolean {
+  const rel = relative(basePath, candidatePath);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
 function reportCheckboxDbStatusDivergence(
   issues: DoctorIssue[],
   basePath: string,
@@ -123,11 +161,137 @@ function isClearedByMilestoneShellProjectionFlush(
 }
 
 function artifactExistsOnDisk(basePath: string, artifactPath: string): boolean {
-  if (isAbsolute(artifactPath)) return existsSync(artifactPath);
-  return [
-    join(gsdProjectionRoot(basePath), artifactPath),
-    join(gsdRoot(basePath), artifactPath),
-  ].some((candidate) => existsSync(candidate));
+  return resolveArtifactDiskPath(basePath, artifactPath) !== null;
+}
+
+function resolveArtifactDiskPath(basePath: string, artifactPath: string): string | null {
+  const relativeArtifactPath = artifactPathRelativeToGsd(artifactPath);
+  if (isAbsolute(relativeArtifactPath)) {
+    return existsSync(relativeArtifactPath) ? relativeArtifactPath : null;
+  }
+  for (const root of [gsdProjectionRoot(basePath), gsdRoot(basePath)]) {
+    const candidate = join(root, relativeArtifactPath);
+    if (isPathInside(root, candidate) && existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function taskExistsInPlan(basePath: string, milestoneId: string, sliceId: string, taskId: string): boolean {
+  const planPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  if (!planPath || !existsSync(planPath)) return false;
+  try {
+    return parsePlan(readFileSync(planPath, "utf-8")).tasks.some((task) => task.id === taskId);
+  } catch {
+    return false;
+  }
+}
+
+function isPassingVerificationResult(value: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return false;
+  if (/\b(fail(?:ed|ing)?|error|blocked|mixed|untested)\b/.test(normalized)) return false;
+  if (
+    /\b(?:not|never|no|didn't|did\s+not|cannot|can't|won't|couldn't)\s+(?:\w+\s+){0,3}?(?:pass(?:ed|ing)?|success(?:ful)?|succeeded)\b/.test(
+      normalized,
+    )
+  ) {
+    return false;
+  }
+  return /\b(pass(?:ed|ing)?|success(?:ful)?|succeeded)\b/.test(normalized) || normalized === "all-pass";
+}
+
+function readTaskCompletionEvidenceFromSummary(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): {
+  completedAt: string;
+  verificationResult: string;
+  title: string;
+  oneLiner: string;
+  narrative: string;
+  duration: string;
+  blockerDiscovered: boolean;
+  deviations: string;
+  knownIssues: string;
+  keyFiles: string[];
+  keyDecisions: string[];
+  fullSummaryMd: string;
+} | null {
+  if (!row.slice_id || !row.task_id) return null;
+  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);
+  if (!diskPath) return null;
+  try {
+    const fullSummaryMd = readFileSync(diskPath, "utf-8");
+    const summary = parseSummary(fullSummaryMd);
+    const fm = summary.frontmatter;
+    if (fm.id !== row.task_id || fm.parent !== row.slice_id || fm.milestone !== row.milestone_id) return null;
+    if (fm.blocker_discovered) return null;
+    if (!isPassingVerificationResult(fm.verification_result)) return null;
+    const completedAt = fm.completed_at.trim();
+    if (!completedAt || !Number.isFinite(Date.parse(completedAt))) return null;
+    return {
+      completedAt,
+      verificationResult: fm.verification_result.trim(),
+      title: summary.title.replace(new RegExp(`^${escapeRegExp(row.task_id)}:\\s*`), "").trim(),
+      oneLiner: summary.oneLiner,
+      narrative: summary.whatHappened,
+      duration: fm.duration,
+      blockerDiscovered: fm.blocker_discovered,
+      deviations: summary.deviations,
+      knownIssues: summary.knownLimitations,
+      keyFiles: fm.key_files.filter((file) => file !== "(none)"),
+      keyDecisions: fm.key_decisions.filter((decision) => decision !== "(none)"),
+      fullSummaryMd,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function repairTaskArtifactDbStatusDivergence(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): boolean {
+  const evidence = readTaskCompletionEvidenceFromSummary(basePath, row);
+  if (!evidence || !row.slice_id || !row.task_id) return false;
+  repairTaskCompletionFromSummary({
+    milestoneId: row.milestone_id,
+    sliceId: row.slice_id,
+    taskId: row.task_id,
+    ...evidence,
+  });
+  return true;
+}
+
+function artifactDbStatusDivergenceFixable(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): boolean {
+  return readTaskCompletionEvidenceFromSummary(basePath, row) !== null;
 }
 
 function artifactUnitId(row: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): string {
@@ -144,10 +308,56 @@ function artifactScope(row: { milestone_id: string | null; slice_id: string | nu
   return "project";
 }
 
+type ArtifactRow = {
+  path: string;
+  artifact_type: string;
+  milestone_id: string | null;
+  slice_id: string | null;
+  task_id: string | null;
+};
+
+function sameArtifactIdentity(left: ArtifactRow, right: ArtifactRow): boolean {
+  return left.artifact_type === right.artifact_type &&
+    left.milestone_id === right.milestone_id &&
+    left.slice_id === right.slice_id &&
+    left.task_id === right.task_id;
+}
+
+function isMilestonesArtifactPath(artifactPath: string): boolean {
+  return artifactPathRelativeToGsd(artifactPath).startsWith("milestones/");
+}
+
+function expectedMilestonesArtifactPath(row: ArtifactRow): string | null {
+  if (!row.milestone_id) return null;
+  const artifactType = normalizedArtifactType(row.artifact_type);
+  if (!artifactType) return null;
+  if (row.slice_id && row.task_id) {
+    return `milestones/${row.milestone_id}/slices/${row.slice_id}/tasks/${row.task_id}-${artifactType}.md`;
+  }
+  if (row.slice_id) {
+    return `milestones/${row.milestone_id}/slices/${row.slice_id}/${row.slice_id}-${artifactType}.md`;
+  }
+  return `milestones/${row.milestone_id}/${row.milestone_id}-${artifactType}.md`;
+}
+
+function hasPresentMilestonesReplacement(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  const expectedPath = expectedMilestonesArtifactPath(row);
+  if (expectedPath && artifactExistsOnDisk(basePath, expectedPath)) return true;
+
+  return artifactRows.some(
+    (other) =>
+      other.path !== row.path &&
+      isMilestonesArtifactPath(other.path) &&
+      sameArtifactIdentity(row, other) &&
+      artifactExistsOnDisk(basePath, other.path),
+  );
+}
+
 export async function checkEngineHealth(
   basePath: string,
   issues: DoctorIssue[],
   fixesApplied: string[],
+  options?: { repair?: boolean },
 ): Promise<void> {
   const dbPath = resolveGsdPathContract(basePath).projectDb;
 
@@ -357,6 +567,7 @@ export async function checkEngineHealth(
       }
 
       // f. Artifact rows reference files that no longer exist on disk.
+      const missingUserContentArtifacts: Array<{ path: string; artifactType: string }> = [];
       try {
         const artifactRows = adapter
           .prepare(
@@ -365,30 +576,54 @@ export async function checkEngineHealth(
              WHERE path != ''
              ORDER BY path`,
           )
-          .all() as Array<{
-            path: string;
-            artifact_type: string;
-            milestone_id: string | null;
-            slice_id: string | null;
-            task_id: string | null;
-          }>;
+          .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)) {
+            // 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}`);
+            continue;
+          }
+          if (isUserAuthoredArtifactType(row.artifact_type)) {
+            const artifactType = normalizedArtifactType(row.artifact_type);
+            missingUserContentArtifacts.push({ path: issuePath, artifactType });
+            issues.push({
+              severity: "warning",
+              code: "artifact_user_content_missing",
+              scope: artifactScope(row),
+              unitId,
+              message: userContentMissingMessage(issuePath, artifactType),
+              file: issuePath,
+              fixable: false,
+            });
+            continue;
+          }
           issues.push({
             severity: "error",
             code: "artifact_file_missing",
             scope: artifactScope(row),
             unitId,
-            message: `Artifact ${row.path} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
-            file: row.path,
-            fixable: false,
+            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),
           });
         }
       } catch {
         // Non-fatal — artifact file existence check failed
       }
+      if (options?.repair) {
+        for (const artifact of missingUserContentArtifacts) {
+          fixesApplied.push(
+            `skipped user-authored ${artifact.artifactType} artifact ${artifact.path} (content cannot be regenerated from the database)`,
+          );
+        }
+      }
 
       // g. Completion artifacts disagree with open DB hierarchy rows.
       try {
@@ -434,13 +669,29 @@ export async function checkEngineHealth(
               : row.milestone_id;
           if (seen.has(unitId)) continue;
           seen.add(unitId);
+          const fixable = artifactDbStatusDivergenceFixable(basePath, row);
+          let repairFailed = false;
+          if (options?.repair && fixable) {
+            try {
+              if (repairTaskArtifactDbStatusDivergence(basePath, row)) {
+                fixesApplied.push(`repaired task completion from SUMMARY artifact for ${unitId}`);
+                continue;
+              }
+            } catch {
+              repairFailed = true;
+            }
+          }
           issues.push({
             severity: "error",
             code: "artifact_db_status_divergence",
             scope: row.task_id ? "task" : row.slice_id ? "slice" : "milestone",
             unitId,
-            message: `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Runtime will not import it silently; run explicit recovery/repair after review.`,
-            fixable: false,
+            message: repairFailed
+              ? `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Doctor found valid SUMMARY completion evidence but could not repair the database state.`
+              : fixable
+              ? `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Doctor can repair this from the SUMMARY completion evidence.`
+              : `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Runtime will not import it silently; run explicit recovery/repair after review.`,
+            fixable,
           });
         }
       } catch {

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

@@ -13,12 +13,13 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { access, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
+import { isCursorAgentReadyUncached } from "../cursor-cli/readiness.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, supportsBrowserOAuth, type ProviderCategory } from "./key-manager.js";
-import { homedir } from "node:os";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -49,6 +50,7 @@ const CLI_AUTH_PROVIDERS = new Set([
   "claude-code",
   "google-gemini-cli",
   "google-antigravity",
+  "cursor-agent",
 ]);
 
 /**
@@ -57,9 +59,9 @@ const CLI_AUTH_PROVIDERS = new Set([
  * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
  */
 const PROVIDER_ROUTES: Record<string, string[]> = {
-  anthropic: ["github-copilot", "claude-code"],
-  openai: ["github-copilot", "openai-codex"],
-  google: ["google-antigravity", "google-gemini-cli"],
+  anthropic: ["github-copilot", "claude-code", "cursor-agent"],
+  openai: ["github-copilot", "openai-codex", "cursor-agent"],
+  google: ["google-antigravity", "google-gemini-cli", "cursor-agent"],
 };
 
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
@@ -86,6 +88,7 @@ function modelToProviderId(model: string): string | null {
       anthropic: "anthropic",
       openai: "openai",
       "github-copilot": "github-copilot",
+      "cursor-agent": "cursor-agent",
     };
     if (prefixMap[prefix]) return prefixMap[prefix];
     return rawPrefix;
@@ -95,6 +98,7 @@ function modelToProviderId(model: string): string | null {
   if (lower.startsWith("claude"))        return "anthropic";
   if (lower.startsWith("gpt-") || lower.startsWith("o1") || lower.startsWith("o3")) return "openai";
   if (lower.startsWith("gemini"))        return "google";
+  if (lower.startsWith("composer"))      return "cursor-agent";
   if (lower.startsWith("llama") || lower.startsWith("mixtral")) return "groq";
   if (lower.startsWith("grok"))          return "xai";
   if (lower.startsWith("mistral") || lower.startsWith("codestral")) return "mistral";
@@ -160,11 +164,13 @@ const CLI_BINARY_MAP: Record<string, string[]> = {
   "claude-code": ["claude", "claude-code"],
   "google-gemini-cli": ["gemini"],
   "google-antigravity": ["agy"],
+  "cursor-agent": ["cursor-agent"],
 };
 
 const CLI_AUTH_PATH_CHECK_PROVIDERS = new Set([
   "google-gemini-cli",
   "google-antigravity",
+  "cursor-agent",
 ]);
 
 let asyncCliBinaryPathCache: Map<string, boolean> | null = null;
@@ -212,6 +218,18 @@ function isCliBinaryInPath(providerId: string): boolean {
   return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
 
+function isExternalCliProviderReady(providerId: string): boolean {
+  if (providerId === "cursor-agent") return isCursorAgentReadyUncached();
+  return isCliBinaryInPath(providerId);
+}
+
+function cursorAgentFailureDetail(): string {
+  if (!isCliBinaryInPath("cursor-agent")) {
+    return "Install Cursor Agent and ensure `cursor-agent` is on PATH";
+  }
+  return "Run `cursor-agent login` or set CURSOR_API_KEY";
+}
+
 async function isCliBinaryInPathAsync(providerId: string): Promise<boolean> {
   const executableNames = cliExecutableNames(providerId);
   if (executableNames.length === 0) return false;
@@ -345,6 +363,12 @@ function resolveKeyFromAuthOrEnv(providerId: string): KeyLookup | null {
 }
 
 function resolveKey(providerId: string): KeyLookup {
+  if (providerId === "cursor-agent") {
+    return isExternalCliProviderReady(providerId)
+      ? { found: true, source: "env", backedOff: false }
+      : { found: false, source: "none", backedOff: false };
+  }
+
   const direct = resolveKeyFromAuthOrEnv(providerId);
   if (direct) return direct;
 
@@ -354,7 +378,7 @@ function resolveKey(providerId: string): KeyLookup {
 
   // Cross-provider routes can use a local CLI when it is installed. Explicit
   // external CLI provider selections are handled in checkLlmProviders() below.
-  if (CLI_AUTH_PROVIDERS.has(providerId) && isCliBinaryInPath(providerId)) {
+  if (CLI_AUTH_PROVIDERS.has(providerId) && isExternalCliProviderReady(providerId)) {
     return { found: true, source: "env", backedOff: false };
   }
 
@@ -373,17 +397,22 @@ function checkLlmProviders(): ProviderCheckResult[] {
     if (CLI_AUTH_PROVIDERS.has(providerId)) {
       const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
       const label = info?.label ?? providerId;
-      if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isCliBinaryInPath(providerId)) {
+      if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isExternalCliProviderReady(providerId)) {
         const binaries = CLI_BINARY_MAP[providerId]?.map(binary => `\`${binary}\``).join(" or ");
+        const detail = providerId === "cursor-agent"
+          ? cursorAgentFailureDetail()
+          : binaries
+          ? `Install ${label} and ensure ${binaries} is on PATH`
+          : `Install ${label} and ensure its CLI is on PATH`;
         results.push({
           name: providerId,
           label,
           category: "llm",
           status: "error",
-          message: `${label} — CLI not found`,
-          detail: binaries
-            ? `Install ${label} and ensure ${binaries} is on PATH`
-            : `Install ${label} and ensure its CLI is on PATH`,
+          message: providerId === "cursor-agent" && isCliBinaryInPath(providerId)
+            ? `${label} — CLI not authenticated`
+            : `${label} — CLI not found`,
+          detail,
           required: true,
         });
         continue;

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

@@ -85,6 +85,7 @@ export type DoctorIssueCode =
   | "db_orphaned_slice"
   | "db_done_task_no_summary"
   | "artifact_file_missing"
+  | "artifact_user_content_missing"
   | "artifact_db_status_divergence"
   | "checkbox_db_status_divergence"
   | "completed_milestone_reopened"
@@ -94,7 +95,10 @@ export type DoctorIssueCode =
   | "projection_drift"
   // Milestone filesystem/DB drift (#4996)
   | "orphan_milestone_dir"
-  | "orphan_milestone_db";
+  | "orphan_milestone_db"
+  // Parent-workspace declared repository checks (#818)
+  | "workspace_repo_path_missing"
+  | "workspace_repo_not_a_repo";
 
 /**
  * Issue codes that represent global or completion-critical state.