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

package/src/resources/extensions/gsd/guided-flow.ts

@@ -40,9 +40,9 @@ import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
 import {
-  gsdRoot, milestonesDir, resolveMilestoneFile,
+  gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
-  relMilestoneFile, relSliceFile,
+  relMilestoneFile, relSliceFile, clearPathCache,
 } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
@@ -101,6 +101,7 @@ import {
   formatPriorContextBrief,
 } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
+import { countPlanMilestoneRoadmapSlices } from "./artifact-verification.js";
 import type { MilestoneScope } from "./workspace.js";
 import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import {
@@ -164,7 +165,7 @@ export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
 // These thin wrappers accept a MilestoneScope so callers that already hold a
 // pinned scope never have to re-derive (basePath, milestoneId) separately.
 // The underlying implementations in auto-recovery.ts / auto-artifact-paths.ts /
-// state.ts are unchanged — only the call surface in guided-flow.ts is migrated.
+// state.ts remain the default for non-scope-specific units.
 
 /**
  * Scope-based overload of verifyExpectedArtifact.
@@ -176,9 +177,47 @@ export function verifyExpectedArtifactForScope(
   unitType: string,
   unitId: string,
 ): boolean {
+  if (
+    unitId === scope.milestoneId &&
+    (unitType === "discuss-milestone" || unitType === "plan-milestone")
+  ) {
+    // Layout-aware scope paths use resolveMilestoneFile; clear stale dir listings
+    // primed before discuss/plan wrote CONTEXT.md or ROADMAP.md (see checkAutoStartAfterDiscuss).
+    clearPathCache();
+  }
+  if (
+    unitId === scope.milestoneId &&
+    unitType === "discuss-milestone"
+  ) {
+    const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+    return path ? existsSync(path) : false;
+  }
+  if (unitId === scope.milestoneId && unitType === "plan-milestone") {
+    const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+    return verifyScopedPlanMilestoneArtifact(path, unitType, unitId);
+  }
   return verifyExpectedArtifact(unitType, unitId, scope.workspace.projectRoot);
 }
 
+function verifyScopedPlanMilestoneArtifact(
+  path: string | null,
+  unitType: string,
+  unitId: string,
+): boolean {
+  if (!path || !existsSync(path)) return false;
+  try {
+    const roadmapContent = readFileSync(path, "utf-8");
+    if (countPlanMilestoneRoadmapSlices(roadmapContent) === 0) {
+      logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${path}`);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    logWarning("recovery", `plan-milestone roadmap verification failed: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+
 /**
  * Scope-based overload of resolveExpectedArtifactPath.
  * Returns the canonical absolute path (or null) using the scope's projectRoot.
@@ -188,6 +227,10 @@ export function resolveExpectedArtifactPathForScope(
   unitType: string,
   unitId: string,
 ): string | null {
+  if (unitId === scope.milestoneId) {
+    if (unitType === "discuss-milestone") return scope.contextFile();
+    if (unitType === "plan-milestone") return scope.roadmapFile();
+  }
   return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
 
@@ -366,8 +409,11 @@ function hasNestedFileOrSymlink(dir: string): boolean {
   return false;
 }
 
-function clearEmptyLegacyDeepSetupPseudoMilestones(basePath: string, entries: string[]): string[] {
-  const mDir = milestonesDir(basePath);
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath: string, entries: string[], dir?: string): string[] {
+  // These are LEGACY pseudo-milestone dirs — prefer legacyMilestonesDir (milestones/)
+  // when it exists; caller may also supply the dir directly.
+  const legacyDir = legacyMilestonesDir(basePath);
+  const mDir = dir ?? (existsSync(legacyDir) ? legacyDir : milestonesDir(basePath));
   const remaining: string[] = [];
   for (const entry of entries) {
     if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
@@ -1041,7 +1087,6 @@ function bootstrapGsdProject(basePath: string): void {
   }
 
   const root = gsdRoot(basePath);
-  mkdirSync(join(root, "milestones"), { recursive: true });
   mkdirSync(join(root, "runtime"), { recursive: true });
 
   const gitPrefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
@@ -2106,9 +2151,12 @@ export async function showSmartEntry(
     // cwd, etc). Warn instead of silently starting a new-project flow.
     if (milestoneIds.length === 0) {
       const mDir = milestonesDir(basePath);
-      if (existsSync(mDir)) {
+      const legDir = legacyMilestonesDir(basePath);
+      // Check flat-phase dir first; fall back to legacy milestones/ dir
+      const checkDir = existsSync(mDir) ? mDir : existsSync(legDir) ? legDir : null;
+      if (checkDir) {
         try {
-          const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(mDir));
+          const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(checkDir), checkDir);
           if (entries.length > 0) {
             ctx.ui.notify(
               `Milestone directory has ${entries.length} entries but none were recognized as milestones. ` +

package/src/resources/extensions/gsd/health-widget.ts

@@ -2,11 +2,12 @@
 // File Purpose: Always-on ambient health signal rendered below the editor.
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
+import { execFile } from "node:child_process";
 import type { GSDState } from "./types.js";
-import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
+import { runProviderChecks, runProviderChecksAsync, summariseProviderIssues } from "./doctor-providers.js";
 import { runEnvironmentChecks, runEnvironmentChecksAsync } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeCommitSubject } from "./native-git-bridge.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
 import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
 import { projectRoot } from "./commands/context.js";
@@ -15,32 +16,75 @@ import {
   buildHealthLines,
   detectHealthWidgetProjectState,
   type HealthWidgetData,
+  type HealthWidgetProjectState,
 } from "./health-widget-core.js";
 
 export const HEALTH_WIDGET_ACTIVE_HINTS =
   "  /gsd auto to run  ·  /gsd status to inspect  ·  /gsd report for snapshots  ·  /gsd notifications for history  ·  /gsd help";
 
+const LAST_COMMIT_LOOKUP_TIMEOUT_MS = 3_000;
+const REFRESH_INTERVAL_MS = 60_000;
+const PROJECT_STATE_CACHE_TTL_MS = REFRESH_INTERVAL_MS;
+
 // ── Data loader ────────────────────────────────────────────────────────────────
 
-// Last-commit lookup is subprocess-backed (native-git-bridge → git spawns),
-// so it is treated like the other expensive checks: skipped on first paint,
-// run only by the background refresh.
-function loadLastCommitInfo(basePath: string): { epoch: number | null; message: string | null } {
+const projectStateCache = new Map<string, { state: HealthWidgetProjectState; computedAt: number }>();
+
+export function getCachedProjectState(basePath: string, force?: boolean): HealthWidgetProjectState {
+  const now = Date.now();
+  const cached = projectStateCache.get(basePath);
+  if (!force && cached && now - cached.computedAt <= PROJECT_STATE_CACHE_TTL_MS) {
+    return cached.state;
+  }
+
+  const state = detectHealthWidgetProjectState(basePath);
+  projectStateCache.set(basePath, { state, computedAt: now });
+  return state;
+}
+
+function runHealthWidgetGit(basePath: string, args: string[]): Promise<string | null> {
+  return new Promise((resolve) => {
+    const child = execFile(
+      "git",
+      args,
+      {
+        cwd: basePath,
+        timeout: LAST_COMMIT_LOOKUP_TIMEOUT_MS,
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      },
+      (err, stdout) => resolve(err ? null : String(stdout).trimEnd()),
+    );
+    child.on("error", () => resolve(null));
+  });
+}
+
+async function loadLastCommitInfoAsync(basePath: string): Promise<{ epoch: number | null; message: string | null }> {
   try {
-    if (nativeIsRepo(basePath)) {
-      const branch = nativeGetCurrentBranch(basePath);
-      const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
-      if (epoch > 0) {
-        return { epoch, message: nativeCommitSubject(basePath, branch || "HEAD") || null };
-      }
+    if ((await runHealthWidgetGit(basePath, ["rev-parse", "--git-dir"])) === null) {
+      return { epoch: null, message: null };
     }
-  } catch { /* non-fatal */ }
-  return { epoch: null, message: null };
+
+    const branch = await runHealthWidgetGit(basePath, ["branch", "--show-current"]);
+    const ref = branch || "HEAD";
+    const raw = await runHealthWidgetGit(basePath, ["log", "-1", "--format=%ct%x00%s", ref]);
+    if (!raw) return { epoch: null, message: null };
+
+    const separator = raw.indexOf("\0");
+    const epochText = separator >= 0 ? raw.slice(0, separator) : raw;
+    const epoch = parseInt(epochText.trim(), 10) || 0;
+    if (epoch <= 0) return { epoch: null, message: null };
+
+    const message = separator >= 0 ? raw.slice(separator + 1).trim() : "";
+    return { epoch, message: message || null };
+  } catch {
+    return { epoch: null, message: null };
+  }
 }
 
 function loadHealthWidgetData(
   basePath: string,
-  options?: { includeChecks?: boolean },
+  options?: { includeChecks?: boolean; forceProjectState?: boolean },
 ): HealthWidgetData {
   // `includeChecks` gates the expensive subprocess-backed checks (provider +
   // environment doctor: `lsof`, `docker`, `node --version`, ...). The initial
@@ -55,7 +99,7 @@ function loadHealthWidgetData(
   let lastCommitEpoch: number | null = null;
   let lastCommitMessage: string | null = null;
 
-  const projectState = detectHealthWidgetProjectState(basePath);
+  const projectState = getCachedProjectState(basePath, options?.forceProjectState);
 
   try {
     const prefs = loadEffectiveGSDPreferences();
@@ -83,13 +127,6 @@ function loadHealthWidgetData(
     } catch { /* non-fatal */ }
   }
 
-  // ── Last commit info ── (git spawns — gated like the other expensive checks)
-  if (includeChecks) {
-    const commit = loadLastCommitInfo(basePath);
-    lastCommitEpoch = commit.epoch;
-    lastCommitMessage = commit.message;
-  }
-
   return {
     projectState,
     budgetCeiling,
@@ -104,10 +141,8 @@ function loadHealthWidgetData(
 }
 
 // Non-blocking variant used by the widget's background refresh: the cheap fields
-// come from the synchronous snapshot, then provider + environment checks are
-// layered in off the event-loop critical path (env checks run concurrently via
-// runEnvironmentChecksAsync). Keeps the always-on widget from stalling the UI on
-// its initial enrichment or its 60s refresh.
+// come from the synchronous snapshot, then provider, environment, and last-commit
+// checks are layered in off the event-loop critical path.
 async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidgetData> {
   const data = loadHealthWidgetData(basePath, { includeChecks: false });
   let providerIssue = data.providerIssue;
@@ -115,7 +150,7 @@ async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidget
   let environmentWarningCount = 0;
 
   try {
-    providerIssue = summariseProviderIssues(runProviderChecks());
+    providerIssue = summariseProviderIssues(await runProviderChecksAsync());
   } catch { /* non-fatal */ }
 
   try {
@@ -126,7 +161,7 @@ async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidget
     }
   } catch { /* non-fatal */ }
 
-  const commit = loadLastCommitInfo(basePath);
+  const commit = await loadLastCommitInfoAsync(basePath);
 
   return {
     ...data,
@@ -141,8 +176,6 @@ async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidget
 
 // ── Widget init ────────────────────────────────────────────────────────────────
 
-const REFRESH_INTERVAL_MS = 60_000;
-
 /**
  * Initialize the always-on gsd-health widget (belowEditor).
  * Call once from the extension entry point after context is available.
@@ -152,13 +185,17 @@ export function initHealthWidget(ctx: ExtensionContext): void {
 
   const basePath = projectRoot();
 
+  // Re-init must reflect filesystem changes immediately; the TTL cache is for
+  // interval refreshes, not this one-off synchronous paint.
+  projectStateCache.delete(basePath);
+
   // String-array fallback — used in RPC mode (factory is a no-op there).
   // Skip the expensive provider/environment doctor checks here: this runs
   // synchronously on the interactive-startup path, where running them would
   // block first paint by ~0.9s (lsof/docker probes, otherwise run again
   // immediately by the factory below). The factory's async refresh fills in
   // real health once the screen is up.
-  const initialData = loadHealthWidgetData(basePath, { includeChecks: false });
+  const initialData = loadHealthWidgetData(basePath, { includeChecks: false, forceProjectState: true });
   ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
 
   // Factory-based widget for TUI mode — replaces the string-array above

package/src/resources/extensions/gsd/json-persistence.ts

@@ -62,6 +62,26 @@ export function saveJsonFile<T>(filePath: string, data: T): void {
   }
 }
 
+/**
+ * Save a JSON file atomically using compact serialization.
+ *
+ * Intended for machine-only ledgers where pretty-printing has no consumer.
+ * Keeps the same write-tmp-rename safety and non-fatal error behavior as
+ * saveJsonFile.
+ */
+export function saveJsonFileCompact<T>(filePath: string, data: T): void {
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    // Use randomized tmp suffix to prevent concurrent-write data loss
+    const tmp = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify(data) + "\n", "utf-8");
+    renameSync(tmp, filePath);
+    // No cleanup needed — renameSync atomically removes tmp on success
+  } catch {
+    // Non-fatal — don't let persistence failures break operation
+  }
+}
+
 /**
  * Write a JSON file atomically (write to .tmp, then rename).
  * Creates parent directories as needed. Non-fatal on error.

package/src/resources/extensions/gsd/key-manager.ts

@@ -43,6 +43,7 @@ export const PROVIDER_REGISTRY: ProviderInfo[] = [
   // must be in the canonical registry so all consumers see the same catalog.
   // See: https://github.com/open-gsd/gsd-pi/issues/4541
   { id: "claude-code",      label: "Claude Code CLI",         category: "llm",                                   authMode: "externalCli" },
+  { id: "cursor-agent",     label: "Cursor Agent",            category: "llm", envVar: "CURSOR_API_KEY",         authMode: "externalCli" },
   { id: "openai",           label: "OpenAI",                  category: "llm", envVar: "OPENAI_API_KEY",         prefixes: ["sk-"],     dashboardUrl: "platform.openai.com/api-keys" },
   { id: "github-copilot",   label: "GitHub Copilot",          category: "llm", envVar: "GITHUB_TOKEN",           authMode: "browserOAuth" },
   { id: "openai-codex",     label: "ChatGPT Plus/Pro (Codex)",category: "llm",                                   authMode: "browserOAuth" },

package/src/resources/extensions/gsd/knowledge-backfill.ts

@@ -35,8 +35,8 @@ interface SynthesizedRow {
  * - Idempotent (per-row): each migrated memory carries
  *   `structured_fields.sourceKnowledgeId = "<P|L>NNN"`. Rows whose ID is
  *   already present in the memory store are skipped.
- * - Best-effort: never throws. Logs and returns 0 on failure so a broken
- *   backfill cannot block agent startup.
+ * - Best-effort: never throws. Failed memory inserts are logged and skipped;
+ *   setup/read failures log and return 0 so backfill cannot block startup.
  * - Rules (K###) are intentionally skipped — they remain manually maintained
  *   in `KNOWLEDGE.md` per ADR-013.
  *
@@ -69,14 +69,20 @@ export function backfillKnowledgeToMemories(basePath: string): number {
       const matchPattern = `%"sourceKnowledgeId":"${synth.id}"%`;
       if (checkExisting.get({ ":pattern": matchPattern })) continue;
 
-      const id = createMemory({
-        category: synth.category,
-        content: synth.content,
-        scope: synth.scope,
-        confidence: 0.85,
-        structuredFields: synth.structuredFields,
-      });
-      if (id) written += 1;
+      try {
+        const id = createMemory({
+          category: synth.category,
+          content: synth.content,
+          scope: synth.scope,
+          confidence: 0.85,
+          structuredFields: synth.structuredFields,
+        });
+        if (id) written += 1;
+      } catch (rowErr) {
+        const message = rowErr instanceof Error ? rowErr.message : String(rowErr);
+        logWarning("knowledge-backfill", `KNOWLEDGE.md -> memories backfill skipped ${synth.id}: ${message}`);
+        continue;
+      }
     }
 
     return written;

package/src/resources/extensions/gsd/layout-policy.ts

@@ -0,0 +1,86 @@
+// Project/App: gsd-pi
+// File Purpose: Single source of truth for the on-disk layout inside .gsd/.
+// Adopted gsd-core's flat-phase structure so both tools read/write the same
+// shape. The 17 path resolvers in paths.ts delegate here; the renderer and
+// importer route through them.
+//
+// DB table/column names (milestones/slices/tasks, milestone_id, etc.) stay
+// unchanged — those are internal identifiers. Only the on-disk segment names
+// and file-naming change.
+
+/** Root directory name. Both gsd-core (Stage 2) and gsd-pi standardize here. */
+export const LAYOUT_ROOT = ".gsd";
+
+/** Segment names inside the root. */
+export const LAYOUT_SEGMENTS = {
+  /** Was "milestones". A phase = one unit of work (gsd-core vocabulary). */
+  level1: "phases",
+} as const;
+
+function pad(n: number, width = 2): string {
+  return String(n).padStart(width, "0");
+}
+
+/**
+ * Phase directory name: `NN-slug` (e.g. "01-foundation").
+ * Matches gsd-core's `phases/NN-name/` convention.
+ */
+export function phaseDirName(phaseNum: number, slug: string): string {
+  return `${pad(phaseNum)}-${slug}`;
+}
+
+/**
+ * Plan file name: `NN-MM-SUFFIX.md` (e.g. "01-01-PLAN.md").
+ * Matches gsd-core's per-plan file convention.
+ */
+export function planFileName(phaseNum: number, planNum: number, suffix: string): string {
+  return `${pad(phaseNum)}-${pad(planNum)}-${suffix}.md`;
+}
+
+/** DB path: `.gsd/gsd.db`. gsd-core ignores this file. */
+export function dbPath(basePath: string): string {
+  return `${basePath}/${LAYOUT_ROOT}/gsd.db`.replaceAll(/\/+/g, "/");
+}
+
+/**
+ * Extract the numeric portion of a milestone id (M001 → 1).
+ * Used by the renderer to derive the phase number from the DB's milestone_id.
+ */
+export function milestoneIdToPhaseNum(milestoneId: string): number {
+  // No $ anchor: accepts bare (M012), team-suffixed (M012-abc123), and legacy numeric IDs.
+  const m = milestoneId.match(/^M0*(\d+)/i);
+  if (!m && /^\d+$/.test(milestoneId)) return Number.parseInt(milestoneId, 10);
+  return m ? Number.parseInt(m[1]!, 10) : 1;
+}
+
+/** Team-mode suffix from milestone ids like M001-abc123. */
+export function milestoneIdUniqueSuffix(milestoneId: string): string | undefined {
+  const m = milestoneId.match(/^M(\d{3})(?:-([a-z0-9]{6}))?$/);
+  return m?.[2];
+}
+
+/**
+ * Extract the numeric portion of a slice id (S01 → 1).
+ * Used by the renderer to derive the plan number from the DB's slice_id.
+ */
+export function sliceIdToPlanNum(sliceId: string): number {
+  const m = sliceId.match(/^S0*(\d+)$/i);
+  return m ? Number.parseInt(m[1]!, 10) : 1;
+}
+
+/**
+ * Derive a stable, deterministic, filesystem-safe slug from a milestone title.
+ * Used for the phase directory name so the layout is human-readable.
+ *
+ * Stability is load-bearing: the renderer must produce the same slug for the
+ * same title on every run, or the directory churns on every projection.
+ */
+export function derivePhaseSlug(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/g, "");
+  return slug || "phase";
+}