@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

package/dist/resources/extensions/gsd/guided-flow-queue.js

@@ -12,7 +12,7 @@ import { loadFile } from "./files.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
-import { gsdRoot, resolveMilestoneFile, resolveGsdRootFile, relGsdRootFile, } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
@@ -20,6 +20,9 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { saveQueueOrder } from "./queue-order.js";
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 import { isFutureMilestoneStatus } from "./status-guards.js";
+const QUEUE_ARTIFACT_EXCERPT_MAX_CHARS = 20_000;
+const QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS = 120_000;
+const QUEUE_CONTEXT_SECTION_SEPARATOR = "\n\n---\n\n";
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 /**
  * Queue future milestones via conversational intake.
@@ -215,7 +218,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
         if (contextFile) {
             const content = await loadFile(contextFile);
             if (content) {
-                parts.push(`\n**Context:**\n${content.trim()}`);
+                parts.push(`\n**Context:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "CONTEXT"))}`);
             }
         }
         else {
@@ -224,7 +227,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             if (draftFile) {
                 const draftContent = await loadFile(draftFile);
                 if (draftContent) {
-                    parts.push(`\n**Draft context available:**\n${draftContent.trim()}`);
+                    parts.push(`\n**Draft context available:**\n${summarizeArtifactForQueue(draftContent, relMilestoneFile(basePath, mid, "CONTEXT-DRAFT"))}`);
                 }
             }
         }
@@ -235,7 +238,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             if (roadmapFile) {
                 const content = await loadFile(roadmapFile);
                 if (content) {
-                    parts.push(`\n**Roadmap:**\n${content.trim()}`);
+                    parts.push(`\n**Roadmap:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "ROADMAP"))}`);
                 }
             }
         }
@@ -249,7 +252,65 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             sections.push(`### Previous Queue Entries\nSource: \`${relGsdRootFile("QUEUE")}\`\n\n${queueContent.trim()}`);
         }
     }
-    return sections.join("\n\n---\n\n");
+    return capExistingMilestonesContext(sections);
+}
+function summarizeArtifactForQueue(content, sourcePath, cap = QUEUE_ARTIFACT_EXCERPT_MAX_CHARS) {
+    const trimmed = content.trim();
+    if (trimmed.length <= cap) {
+        return `Source: \`${sourcePath}\`\n\n${trimmed}`;
+    }
+    const excerpt = trimmed.slice(0, cap).trimEnd();
+    const omittedChars = trimmed.length - excerpt.length;
+    return [
+        `Source: \`${sourcePath}\``,
+        "",
+        excerpt,
+        "",
+        `[Truncated ${omittedChars} chars. Read \`${sourcePath}\` for full content.]`,
+    ].join("\n");
+}
+function capExistingMilestonesContext(sections, cap = QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS) {
+    const fullContext = sections.join(QUEUE_CONTEXT_SECTION_SEPARATOR);
+    if (fullContext.length <= cap)
+        return fullContext;
+    const notice = `[Existing milestones context truncated to ${cap} chars. Read source paths in this prompt or the corresponding .gsd artifacts for full details.]`;
+    const noticeSuffix = `${QUEUE_CONTEXT_SECTION_SEPARATOR}${notice}`;
+    const selected = [];
+    for (const section of sections) {
+        const candidate = [...selected, section].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+        if (candidate.length <= cap) {
+            selected.push(section);
+            continue;
+        }
+        break;
+    }
+    if (selected.length === sections.length) {
+        return selected.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    }
+    const compactTail = sections.slice(selected.length).map(compactSectionForQueueBudget);
+    const hybrid = [...selected, ...compactTail].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (hybrid.length <= cap)
+        return hybrid;
+    const compact = sections.map(compactSectionForQueueBudget);
+    const compactContext = compact.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (compactContext.length <= cap)
+        return compactContext;
+    return `${compactContext.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
+}
+function compactSectionForQueueBudget(section) {
+    const lines = section.split("\n");
+    const compact = [];
+    if (lines[0])
+        compact.push(lines[0]);
+    const statusLine = lines.find(line => line.startsWith("**Status:**"));
+    if (statusLine)
+        compact.push(statusLine);
+    const sourceLines = lines.filter(line => line.startsWith("Source: `"));
+    if (sourceLines.length > 0) {
+        compact.push("", "**Sources:**", ...sourceLines);
+        compact.push("", "[Artifact excerpts omitted due to total queue/rethink context budget.]");
+    }
+    return compact.join("\n");
 }
 // ─── Internal Helpers ───────────────────────────────────────────────────────
 /**

package/dist/resources/extensions/gsd/guided-flow.js

@@ -20,7 +20,7 @@ import { assessInterruptedSession, formatInterruptedSessionRunningMessage, forma
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
-import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
@@ -53,6 +53,7 @@ import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
 import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
+import { countPlanMilestoneRoadmapSlices } from "./artifact-verification.js";
 import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
@@ -78,20 +79,57 @@ 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.
  * Uses scope.workspace.projectRoot as the authoritative base path, making
  * the check immune to cwd-drift and worktree-path divergence.
  */
 export function verifyExpectedArtifactForScope(scope, unitType, unitId) {
+    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, unitType, unitId) {
+    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.
  */
 export function resolveExpectedArtifactPathForScope(scope, unitType, unitId) {
+    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);
 }
 async function runQuickTaskChoice(ctx, pi) {
@@ -211,8 +249,11 @@ function hasNestedFileOrSymlink(dir) {
     }
     return false;
 }
-function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
-    const mDir = milestonesDir(basePath);
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries, dir) {
+    // 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 = [];
     for (const entry of entries) {
         if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
@@ -732,7 +773,6 @@ function bootstrapGsdProject(basePath) {
         nativeInit(basePath, mainBranch);
     }
     const root = gsdRoot(basePath);
-    mkdirSync(join(root, "milestones"), { recursive: true });
     mkdirSync(join(root, "runtime"), { recursive: true });
     const gitPrefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     const manageGitignore = gitPrefs?.manage_gitignore;
@@ -1643,9 +1683,12 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // 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. ` +
                             `This may indicate a corrupted state or wrong working directory. Run \`/gsd doctor\` to diagnose.`, "warning");

package/dist/resources/extensions/gsd/health-widget.js

@@ -1,29 +1,61 @@
 // Project/App: gsd-pi
 // File Purpose: Always-on ambient health signal rendered below the editor.
-import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
+import { execFile } from "node:child_process";
+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 { projectRoot } from "./commands/context.js";
 import { buildHealthLines, detectHealthWidgetProjectState, } 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) {
+const projectStateCache = new Map();
+export function getCachedProjectState(basePath, force) {
+    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, args) {
+    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) {
     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 };
         }
+        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 };
     }
-    catch { /* non-fatal */ }
-    return { epoch: null, message: null };
 }
 function loadHealthWidgetData(basePath, options) {
     // `includeChecks` gates the expensive subprocess-backed checks (provider +
@@ -38,7 +70,7 @@ function loadHealthWidgetData(basePath, options) {
     let environmentWarningCount = 0;
     let lastCommitEpoch = null;
     let lastCommitMessage = null;
-    const projectState = detectHealthWidgetProjectState(basePath);
+    const projectState = getCachedProjectState(basePath, options?.forceProjectState);
     try {
         const prefs = loadEffectiveGSDPreferences();
         budgetCeiling = prefs?.preferences?.budget_ceiling;
@@ -66,12 +98,6 @@ function loadHealthWidgetData(basePath, options) {
         }
         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,
@@ -85,17 +111,15 @@ function loadHealthWidgetData(basePath, options) {
     };
 }
 // 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) {
     const data = loadHealthWidgetData(basePath, { includeChecks: false });
     let providerIssue = data.providerIssue;
     let environmentErrorCount = 0;
     let environmentWarningCount = 0;
     try {
-        providerIssue = summariseProviderIssues(runProviderChecks());
+        providerIssue = summariseProviderIssues(await runProviderChecksAsync());
     }
     catch { /* non-fatal */ }
     try {
@@ -108,7 +132,7 @@ async function loadHealthWidgetDataAsync(basePath) {
         }
     }
     catch { /* non-fatal */ }
-    const commit = loadLastCommitInfo(basePath);
+    const commit = await loadLastCommitInfoAsync(basePath);
     return {
         ...data,
         providerIssue,
@@ -120,7 +144,6 @@ async function loadHealthWidgetDataAsync(basePath) {
     };
 }
 // ── 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.
@@ -129,13 +152,16 @@ export function initHealthWidget(ctx) {
     if (!ctx.hasUI)
         return;
     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
     ctx.ui.setWidget("gsd-health", (_tui, _theme) => {

package/dist/resources/extensions/gsd/json-persistence.js

@@ -56,6 +56,26 @@ export function saveJsonFile(filePath, data) {
         // Non-fatal — don't let persistence failures break operation
     }
 }
+/**
+ * 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(filePath, data) {
+    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/dist/resources/extensions/gsd/key-manager.js

@@ -19,6 +19,7 @@ export const PROVIDER_REGISTRY = [
     // 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/dist/resources/extensions/gsd/knowledge-backfill.js

@@ -24,8 +24,8 @@ import { logWarning } from "./workflow-logger.js";
  * - 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.
  *
@@ -56,15 +56,22 @@ export function backfillKnowledgeToMemories(basePath) {
             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/dist/resources/extensions/gsd/layout-policy.js

@@ -0,0 +1,77 @@
+// 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",
+};
+function pad(n, width = 2) {
+    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, slug) {
+    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, planNum, suffix) {
+    return `${pad(phaseNum)}-${pad(planNum)}-${suffix}.md`;
+}
+/** DB path: `.gsd/gsd.db`. gsd-core ignores this file. */
+export function dbPath(basePath) {
+    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) {
+    // 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) {
+    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) {
+    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) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return slug || "phase";
+}