@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.72e3af2a

package/src/resources/extensions/gsd/memory-consolidation-scanner.ts

@@ -142,23 +142,53 @@ function getActiveDecisions(): DecisionRow[] {
 }
 
 /**
- * True when a memory row has a `structured_fields` JSON payload containing
- * the given `markerKey: "value"` pair. Matches the LIKE pattern used by
- * `backfillDecisionsToMemories` so the scanner is consistent with the
- * backfill's idempotency check.
+ * Source IDs already present in memory `structured_fields`. Collected with one
+ * pass over the memories table so the scanner does not perform a non-indexable
+ * LIKE probe for every decision and KNOWLEDGE.md row.
  */
-function memoryHasSourceMarker(markerKey: string, value: string): boolean {
-  if (!isDbAvailable()) return false;
+interface MemorySourceMarkers {
+  decisionIds: Set<string>;
+  knowledgeIds: Set<string>;
+}
+
+function emptyMemorySourceMarkers(): MemorySourceMarkers {
+  return { decisionIds: new Set(), knowledgeIds: new Set() };
+}
+
+function getMemorySourceMarkers(): MemorySourceMarkers {
+  const markers = emptyMemorySourceMarkers();
+  if (!isDbAvailable()) return markers;
   const adapter = _getAdapter();
-  if (!adapter) return false;
+  if (!adapter) return markers;
+  try {
+    const rows = adapter
+      .prepare("SELECT structured_fields FROM memories WHERE structured_fields IS NOT NULL")
+      .all() as Array<Record<string, unknown>>;
+    for (const row of rows) {
+      collectMemorySourceMarker(markers, row["structured_fields"]);
+    }
+  } catch {
+    return markers;
+  }
+  return markers;
+}
+
+function collectMemorySourceMarker(markers: MemorySourceMarkers, raw: unknown): void {
+  if (typeof raw !== "string" || raw.length === 0) return;
   try {
-    const pattern = `%"${markerKey}":"${value}"%`;
-    const row = adapter
-      .prepare("SELECT 1 FROM memories WHERE structured_fields LIKE :pattern LIMIT 1")
-      .get({ ":pattern": pattern });
-    return row !== undefined;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    const fields = parsed as Record<string, unknown>;
+    const decisionId = fields["sourceDecisionId"];
+    if (typeof decisionId === "string" && decisionId.length > 0) {
+      markers.decisionIds.add(decisionId);
+    }
+    const knowledgeId = fields["sourceKnowledgeId"];
+    if (typeof knowledgeId === "string" && knowledgeId.length > 0) {
+      markers.knowledgeIds.add(knowledgeId);
+    }
   } catch {
-    return false;
+    return;
   }
 }
 
@@ -174,10 +204,14 @@ const SAMPLE_LIMIT = 5;
 export function scanConsolidationGaps(basePath: string): ConsolidationGapReport {
   // ── Decisions ────────────────────────────────────────────────────────
   const decisions = getActiveDecisions();
+  const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
+  const memorySourceMarkers = decisions.length > 0 || knowledgeRows.length > 0
+    ? getMemorySourceMarkers()
+    : emptyMemorySourceMarkers();
   const decisionSamples: DecisionsSurfaceReport["samples"] = [];
   let decisionMigrated = 0;
   for (const decision of decisions) {
-    if (memoryHasSourceMarker("sourceDecisionId", decision.id)) {
+    if (memorySourceMarkers.decisionIds.has(decision.id)) {
       decisionMigrated += 1;
       continue;
     }
@@ -190,16 +224,14 @@ export function scanConsolidationGaps(basePath: string): ConsolidationGapReport
   }
 
   // ── KNOWLEDGE.md ─────────────────────────────────────────────────────
-  const knowledgeRows = parseKnowledgeRows(knowledgeMdContent(basePath));
   const knowledgeByTable = { rules: 0, patterns: 0, lessons: 0 };
   const knowledgeSamples: KnowledgeSurfaceReport["samples"] = [];
   let knowledgeMigrated = 0;
   for (const row of knowledgeRows) {
     knowledgeByTable[row.table] += 1;
-    // Phase 6 will introduce a `sourceKnowledgeId` marker as part of the
-    // KNOWLEDGE.md backfill. Until that path ships, this check returns
-    // false for every row, which is the honest state of the consolidation.
-    if (memoryHasSourceMarker("sourceKnowledgeId", row.id)) {
+    // KNOWLEDGE.md backfill writes `sourceKnowledgeId`; rows without that
+    // marker are still reported as consolidation gaps.
+    if (memorySourceMarkers.knowledgeIds.has(row.id)) {
       knowledgeMigrated += 1;
       continue;
     }

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -90,6 +90,28 @@ function scanHasExtraIdentities(a: HierarchyScan, b: HierarchyScan): boolean {
   );
 }
 
+function paddedMilestoneId(id: string): string | null {
+  return /^\d+$/.test(id) ? `M${id.padStart(3, "0")}` : null;
+}
+
+function replaceSetPrefix(values: Set<string>, from: string, to: string): void {
+  for (const value of [...values]) {
+    if (value !== from && !value.startsWith(`${from}/`)) continue;
+    values.delete(value);
+    values.add(`${to}${value.slice(from.length)}`);
+  }
+}
+
+function alignNumericMarkdownIdsWithDb(markdownScan: HierarchyScan, dbScan: HierarchyScan): void {
+  for (const dbId of dbScan.milestones) {
+    const paddedId = paddedMilestoneId(dbId);
+    if (!paddedId || dbScan.milestones.has(paddedId) || !markdownScan.milestones.has(paddedId)) continue;
+    replaceSetPrefix(markdownScan.milestones, paddedId, dbId);
+    replaceSetPrefix(markdownScan.slices, paddedId, dbId);
+    replaceSetPrefix(markdownScan.tasks, paddedId, dbId);
+  }
+}
+
 /**
  * True when the DB holds any milestone/slice/task identity the markdown lacks —
  * i.e. a `/gsd recover --confirm` (markdown → DB) would DELETE authoritative DB
@@ -185,6 +207,7 @@ export async function checkMarkdownHierarchyAgainstDb(
 
   const dbScan = scanDbHierarchy();
   const beforeDb = dbScan.counts;
+  alignNumericMarkdownIdsWithDb(markdownScan, dbScan);
 
   // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
   // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the

package/src/resources/extensions/gsd/milestone-ids.ts

@@ -141,7 +141,8 @@ export function clearReservedMilestoneIds(): void {
 
 // ─── Discovery ──────────────────────────────────────────────────────────────
 
-function scanMilestoneIdsFromDir(dir: string): string[] {
+function scanMilestoneIdsFromDir(basePath: string, dir: string): string[] {
+  const legacyNumericIds = idsWithLegacyNumericDirs(basePath);
   return readdirSync(dir, { withFileTypes: true })
     .filter((d) => d.isDirectory())
     .map((d) => {
@@ -149,6 +150,12 @@ function scanMilestoneIdsFromDir(dir: string): string[] {
       if (MILESTONE_ID_RE.test(d.name)) {
         return d.name;
       }
+      // Legacy recovery/imports may contain bare numeric milestone directories
+      // (for example `milestones/15/15-ROADMAP.md`). The DB can preserve that
+      // id, and rebuild renders it, so drift scans must see it too.
+      if (/^\d+$/.test(d.name)) {
+        return d.name;
+      }
       // Legacy layout: M001-abcdef-slug descriptor directories
       const legacyMatch = d.name.match(/^(M\d{3}(?:-[a-z0-9]{6})?)-/);
       if (legacyMatch) {
@@ -162,6 +169,10 @@ function scanMilestoneIdsFromDir(dir: string): string[] {
         if (MILESTONE_ID_RE.test(fromSlug)) {
           return fromSlug;
         }
+        const numericId = String(phaseNum);
+        if (legacyNumericIds.has(numericId)) {
+          return numericId;
+        }
         return `M${String(phaseNum).padStart(3, "0")}`;
       }
       return null;
@@ -169,6 +180,24 @@ function scanMilestoneIdsFromDir(dir: string): string[] {
     .filter((id): id is string => id !== null);
 }
 
+function idsWithLegacyNumericDirs(basePath: string): Set<string> {
+  const legacyDir = join(gsdProjectionRoot(basePath), "milestones");
+  const ids = new Set<string>();
+  try {
+    for (const entry of readdirSync(legacyDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && /^\d+$/.test(entry.name)) ids.add(entry.name);
+    }
+  } catch (err) {
+    // A missing legacy directory is the common, benign case (nothing to
+    // consult). Only surface a real failure when the directory exists but
+    // could not be read.
+    if (existsSync(legacyDir)) {
+      logWarning("engine", `idsWithLegacyNumericDirs: ${legacyDir} exists but readdirSync failed — ${getErrorMessage(err)}`);
+    }
+  }
+  return ids;
+}
+
 /** Scan the milestones directory and return IDs sorted by queue order (or numeric fallback). */
 export function findMilestoneIds(basePath: string): string[] {
   const root = gsdProjectionRoot(basePath);
@@ -181,7 +210,7 @@ export function findMilestoneIds(basePath: string): string[] {
   const ids = new Set<string>();
   for (const dir of dirs) {
     try {
-      for (const id of scanMilestoneIdsFromDir(dir)) ids.add(id);
+      for (const id of scanMilestoneIdsFromDir(basePath, dir)) ids.add(id);
     } catch (err) {
       if (existsSync(dir)) {
         logWarning("engine", `findMilestoneIds: ${dir} exists but readdirSync failed — ${getErrorMessage(err)}`);

package/src/resources/extensions/gsd/milestone-implementation-evidence.ts

@@ -19,6 +19,16 @@ import { resolveTasksDir } from "./paths.js";
 
 /** Large enough for unbounded milestone-history git log scans in big repos. */
 const GIT_LOG_MAX_BUFFER = 16 * 1024 * 1024;
+const LOG_FIELD_SEPARATOR = "\x1f";
+const LOG_RECORD_SEPARATOR = "\x1e";
+
+type CommitRecord = {
+  hash: string;
+  parents: string;
+  committedAt: string;
+  message: string;
+  files: string[];
+};
 
 /**
  * Check whether a milestone produced implementation artifacts (non-`.gsd/`
@@ -198,7 +208,7 @@ function getChangedFilesFromMilestoneTaggedCommits(
   // Primary: path-scoped log against .gsd/milestones/<id>. Fast and unbounded
   // by depth when .gsd/ is tracked in git.
   const scoped = scanGsdTaggedCommits(basePath, milestoneId, [
-    "log", "--format=%H%x1f%B%x1e", "HEAD", "--", `.gsd/milestones/${milestoneId}`,
+    "log", "--full-diff", "--name-only", "--format=%x1e%H%x1f%B%x1f", "HEAD", "--", `.gsd/milestones/${milestoneId}`,
   ]);
   if (!scoped.ok) return scoped;
   if (scoped.matched && classifyImplementationFiles(scoped.files) === "present") return scoped;
@@ -213,7 +223,7 @@ function getChangedFilesFromMilestoneTaggedCommits(
   // reintroducing the rolling-depth failure class removed in #4699 where
   // milestone evidence aged out behind unrelated activity.
   const unscoped = scanGsdTaggedCommits(basePath, milestoneId, [
-    "log", "--format=%H%x1f%B%x1e", "HEAD",
+    "log", "--name-only", "--format=%x1e%H%x1f%B%x1f", "HEAD",
   ]);
   if (!unscoped.ok) return scoped.matched ? scoped : unscoped;
   if (!unscoped.matched) return scoped;
@@ -299,8 +309,7 @@ function backfillChangedFilesFromUntaggedMilestoneCommits(
       if (record.parents.trim().split(/\s+/).filter(Boolean).length > 1) continue;
       if (commitMessageHasGsdTrailer(record.message)) continue;
 
-      const commitFiles = getChangedFilesForCommit(basePath, record.hash);
-      const implementationFiles = commitFiles.map(normalizeRepoPath).filter(isImplementationPath);
+      const implementationFiles = record.files.map(normalizeRepoPath).filter(isImplementationPath);
       if (implementationFiles.length === 0) continue;
       if (!implementationFiles.some((file) => hintSet.has(file))) continue;
 
@@ -323,25 +332,30 @@ function backfillChangedFilesFromUntaggedMilestoneCommits(
   }
 }
 
-function getCommitRecords(basePath: string): Array<{ hash: string; parents: string; committedAt: string; message: string }> {
-  const logOutput = execFileSync("git", ["log", "--format=%H%x1f%P%x1f%cI%x1f%B%x1e", "HEAD"], {
+function getCommitRecords(basePath: string): CommitRecord[] {
+  const logOutput = execFileSync("git", ["log", "--name-only", "--format=%x1e%H%x1f%P%x1f%cI%x1f%B%x1f", "HEAD"], {
     cwd: basePath,
     stdio: ["ignore", "pipe", "pipe"],
     encoding: "utf-8",
     maxBuffer: GIT_LOG_MAX_BUFFER,
   });
   return logOutput
-    .split("\x1e")
-    .map((record) => record.trim())
+    .split(LOG_RECORD_SEPARATOR)
     .filter(Boolean)
     .flatMap((record) => {
-      const parts = record.split("\x1f");
-      if (parts.length < 4) return [];
-      const [hash, parents, committedAt, ...messageParts] = parts;
-      return [{ hash: hash.trim(), parents: parents.trim(), committedAt: committedAt.trim(), message: messageParts.join("\x1f") }];
+      const parts = record.split(LOG_FIELD_SEPARATOR);
+      if (parts.length < 5) return [];
+      const [hash, parents, committedAt] = parts;
+      const files = parseNameOnlyFiles(parts.at(-1) ?? "");
+      const message = parts.slice(3, -1).join(LOG_FIELD_SEPARATOR);
+      return [{ hash: hash.trim(), parents: parents.trim(), committedAt: committedAt.trim(), message, files }];
     });
 }
 
+function parseNameOnlyFiles(rawFiles: string): string[] {
+  return rawFiles.split(/\r?\n/).map((file) => file.trim()).filter(Boolean);
+}
+
 function isFullCommitSha(value: string): boolean {
   return /^[0-9a-f]{40}$/i.test(value);
 }
@@ -359,23 +373,23 @@ function scanGsdTaggedCommits(
       maxBuffer: GIT_LOG_MAX_BUFFER,
     });
     const records = logOutput
-      .split("\x1e")
-      .map((record) => record.trim())
+      .split(LOG_RECORD_SEPARATOR)
       .filter(Boolean)
       .flatMap((record) => {
-        const sep = record.indexOf("\x1f");
-        if (sep === -1) return [];
-        const hash = record.slice(0, sep).trim();
-        const message = record.slice(sep + 1);
-        return [{ hash, message }];
+        const parts = record.split(LOG_FIELD_SEPARATOR);
+        if (parts.length < 3) return [];
+        const hash = parts[0].trim();
+        if (!hash) return [];
+        const files = parseNameOnlyFiles(parts.at(-1) ?? "");
+        const message = parts.slice(1, -1).join(LOG_FIELD_SEPARATOR);
+        return [{ message, files }];
       });
 
     const files = new Set<string>();
     let matched = false;
-    for (const { hash, message } of records) {
+    for (const { message, files: commitFiles } of records) {
       if (!commitMessageHasGsdTrailer(message)) continue;
 
-      const commitFiles = getChangedFilesForCommit(basePath, hash);
       if (!commitMatchesMilestone(basePath, message, milestoneId, commitFiles)) continue;
 
       matched = true;

package/src/resources/extensions/gsd/prompts/code-review.md

@@ -16,18 +16,20 @@ You are running the GSD **code-review** workflow — review source files changed
 
 1. **Determine the file set.** Use the explicit `--files` list if provided. Otherwise derive the changed source files from the active slice's recent commits / SUMMARY, or fall back to the git diff against the base branch. Exclude `.gsd/`, lockfiles, generated/vendored code, and docs unless `--files` names them.
 
-2. **Review each file** at the requested depth:
+2. **Gather diff-first context.** Run `git diff` for the file set (or the relevant commit range) and use that as the primary review evidence. Use `read` only when the diff is insufficient — new/untracked files, truncated hunks, or missing surrounding context needed for a finding. Do **not** read every changed file when the diff already covers the edits. If the Tool Call Loop Guard blocks a tool, stop calling tools for the rest of this turn and continue in text.
+
+3. **Review at the requested depth:**
    - **quick** — bugs, security, and correctness only.
    - **standard** (default) — quick + maintainability, error handling, edge cases.
    - **deep** — standard + performance, concurrency, API design, test coverage gaps.
 
    Ground every finding in the actual code with file path + line reference. Categorize each by severity (critical / warning / nit) and type (bug, security, quality, performance).
 
-3. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
+4. **Write the review.** Produce `.gsd/reviews/{{reviewId}}-REVIEW.md` with the findings table and per-finding detail (location, issue, suggested fix).
 
-4. **Present results.** Summarize counts by severity and list the critical findings first.
+5. **Present results.** Summarize counts by severity and list the critical findings first.
 
-5. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
+6. **Fix mode** (only when `--fix` is set): for each finding that is safely auto-fixable (deterministic, no behavior change beyond the fix), apply it. After each fix batch, run the project's tests. Commit atomically with the finding IDs referenced in the message. Do not auto-apply findings that are ambiguous or that change public behavior — surface those for a human decision instead.
 
 ## Success criteria
 

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

@@ -10,8 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { QUICK_BRANCH_RE } from "./branch-patterns.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
@@ -31,6 +31,7 @@ interface QuickReturnState {
 }
 
 let pendingQuickReturn: QuickReturnState | null = null;
+const pendingQuickReturnMisses = new Map<string, string>();
 
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 
@@ -189,12 +190,35 @@ export function buildQuickCommitInstruction(basePath: string, root: string): str
   ].join("\n");
 }
 
+function readHeadBranchName(basePath: string): string | null {
+  try {
+    const gitPath = join(basePath, ".git");
+    if (!existsSync(gitPath)) return null;
+
+    let headPath: string;
+    if (lstatSync(gitPath).isDirectory()) {
+      headPath = join(gitPath, "HEAD");
+    } else {
+      const gitFile = readFileSync(gitPath, "utf-8").trim();
+      if (!gitFile.startsWith("gitdir: ")) return null;
+      headPath = join(resolve(basePath, gitFile.slice("gitdir: ".length)), "HEAD");
+    }
+
+    const head = readFileSync(headPath, "utf-8").trim();
+    if (!head.startsWith("ref: refs/heads/")) return null;
+    return head.slice("ref: refs/heads/".length);
+  } catch {
+    return null;
+  }
+}
+
 function quickReturnStatePath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
 
 function persistPendingReturn(state: QuickReturnState): void {
   pendingQuickReturn = state;
+  pendingQuickReturnMisses.delete(state.basePath);
   mkdirSync(join(gsdRoot(state.basePath), "runtime"), { recursive: true });
   writeFileSync(quickReturnStatePath(state.basePath), JSON.stringify(state) + "\n", "utf-8");
 }
@@ -203,6 +227,13 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   if (pendingQuickReturn && pendingQuickReturn.basePath === basePath) {
     return pendingQuickReturn;
   }
+  if (pendingQuickReturnMisses.has(basePath)) {
+    const statePath = quickReturnStatePath(basePath);
+    if (!existsSync(statePath) && readHeadBranchName(basePath) === pendingQuickReturnMisses.get(basePath)) {
+      return null;
+    }
+    pendingQuickReturnMisses.delete(basePath);
+  }
 
   try {
     const raw = readFileSync(quickReturnStatePath(basePath), "utf-8");
@@ -216,6 +247,7 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
       && typeof parsed.description === "string"
     ) {
       pendingQuickReturn = parsed as QuickReturnState;
+      pendingQuickReturnMisses.delete(basePath);
       return pendingQuickReturn;
     }
   } catch {
@@ -225,9 +257,14 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   const inferred = inferQuickReturnFromBranch(basePath);
   if (inferred) {
     pendingQuickReturn = inferred;
+    pendingQuickReturnMisses.delete(basePath);
     return inferred;
   }
 
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   return null;
 }
 
@@ -235,6 +272,10 @@ function clearPendingReturn(basePath: string): void {
   if (pendingQuickReturn?.basePath === basePath) {
     pendingQuickReturn = null;
   }
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   rmSync(quickReturnStatePath(basePath), { force: true });
 }
 

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

@@ -223,11 +223,21 @@ export function extractTrace(entries: unknown[]): ExecutionTrace {
 
   // Flush any pending tool calls that never got results (crash mid-tool)
   for (const [, pending] of pendingTools) {
+    const missingResultError = `Tool call ${pending.name} started but no toolResult was recorded`;
     toolCalls.push({
       name: pending.name,
       input: redactInput(pending.name, pending.input),
-      isError: false,
+      result: "missing tool result (stream/tool-call abort before execution)",
+      isError: true,
     });
+    errors.push(missingResultError);
+
+    // Mark the matching commandsRun entry as failed so it is consistent with
+    // the isError: true on the tool call above (bash/bg_shell only).
+    if (pending.name === "bash" || pending.name === "bg_shell") {
+      const lastCmd = findLast(commandsRun, c => c.command === String(pending.input.command));
+      if (lastCmd) lastCmd.failed = true;
+    }
   }
 
   return {

package/src/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -66,7 +66,7 @@ These commands dispatch native GSD prompts adapted to the milestone, slice, and
 | `progress` | Summarize recent work; can route `--next` or `--do "..."` |
 | `health` | Check `.gsd/` integrity (`--repair`, `--context`) |
 | `surface` | Manage surfaced skills and extensions |
-| `code-review` | Review changed source for bugs, security, and quality |
+| `code-review` | Review changed source diff-first for bugs, security, and quality |
 | `review` | Peer-review recent work across reviewer perspectives |
 | `audit-milestone` | Verify a milestone met its definition of done |
 | `audit-uat` | Audit outstanding UAT/verification items |

package/src/resources/extensions/gsd/state/derive/cache.ts

@@ -0,0 +1,46 @@
+// Project/App: gsd-pi
+// File Purpose: deriveState memoization cache and telemetry.
+
+import type { GSDState } from '../../types.js';
+
+interface StateCache {
+  basePath: string;
+  result: GSDState;
+  timestamp: number;
+}
+
+const CACHE_TTL_MS = 100;
+let _stateCache: StateCache | null = null;
+
+let _telemetry = { dbDeriveCount: 0 };
+
+export function getDeriveTelemetry() {
+  return { ..._telemetry };
+}
+
+export function resetDeriveTelemetry() {
+  _telemetry = { dbDeriveCount: 0 };
+}
+
+export function incrementDbDeriveCount(): void {
+  _telemetry.dbDeriveCount++;
+}
+
+export function invalidateStateCache(): void {
+  _stateCache = null;
+}
+
+export function readCachedDeriveState(cacheKey: string): GSDState | null {
+  if (
+    _stateCache &&
+    _stateCache.basePath === cacheKey &&
+    Date.now() - _stateCache.timestamp < CACHE_TTL_MS
+  ) {
+    return _stateCache.result;
+  }
+  return null;
+}
+
+export function writeCachedDeriveState(cacheKey: string, result: GSDState): void {
+  _stateCache = { basePath: cacheKey, result, timestamp: Date.now() };
+}

package/src/resources/extensions/gsd/state/derive/db-open.ts

@@ -0,0 +1,45 @@
+// Project/App: gsd-pi
+// File Purpose: Workflow DB open helpers for state derivation.
+
+import type { GSDState } from '../../types.js';
+import { getAllMilestones, isDbAvailable, setMilestoneQueueOrder } from '../../gsd-db.js';
+import { openExistingWorkflowDatabase } from '../../db-workspace.js';
+import { loadQueueOrder, sortByQueueOrder } from '../../queue-order.js';
+
+export function syncQueueOrderProjectionToDb(basePath: string): void {
+  const queueOrder = loadQueueOrder(basePath);
+  if (!queueOrder) return;
+
+  const currentIds = getAllMilestones().map((m) => m.id);
+  const desiredIds = sortByQueueOrder(currentIds, queueOrder);
+  if (currentIds.length === desiredIds.length && currentIds.every((id, i) => id === desiredIds[i])) return;
+
+  setMilestoneQueueOrder(desiredIds);
+}
+
+export function ensureExistingWorkflowDbOpen(basePath: string): boolean {
+  const opened = isDbAvailable() || openExistingWorkflowDatabase(basePath).ok;
+  if (opened) syncQueueOrderProjectionToDb(basePath);
+  return opened;
+}
+
+export function buildDbUnavailableState(): GSDState {
+  return {
+    activeMilestone: null,
+    activeSlice: null,
+    activeTask: null,
+    phase: "pre-planning",
+    recentDecisions: [],
+    blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
+    nextAction:
+      "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
+    registry: [],
+    requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+    progress: { milestones: { done: 0, total: 0 } },
+  };
+}
+
+export function getRequestedMilestoneLock(): string | undefined {
+  const lock = process.env.GSD_MILESTONE_LOCK?.trim();
+  return lock || undefined;
+}