gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/gsd/commands-scan.ts

@@ -0,0 +1,125 @@
+/**
+ * GSD Command — /gsd scan
+ *
+ * Rapid codebase assessment — lightweight alternative to /gsd map-codebase.
+ * Spawns one focused AI analysis pass and writes structured documents to
+ * .gsd/codebase/ for use by planning and execution phases.
+ *
+ * Usage:
+ *   /gsd scan                   — tech+arch focus (default)
+ *   /gsd scan --focus tech      — technology stack + integrations only
+ *   /gsd scan --focus arch      — architecture + structure only
+ *   /gsd scan --focus quality   — conventions + testing patterns only
+ *   /gsd scan --focus concerns  — technical debt + concerns only
+ *   /gsd scan --focus tech+arch — explicit default (same as no flag)
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { loadPrompt } from "./prompt-loader.js";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+export const DEFAULT_FOCUS = "tech+arch";
+
+export const VALID_FOCUS_AREAS = ["tech", "arch", "quality", "concerns", "tech+arch"] as const;
+export type FocusArea = (typeof VALID_FOCUS_AREAS)[number];
+
+const FOCUS_DOCUMENTS: Record<FocusArea, string[]> = {
+  tech: ["STACK", "INTEGRATIONS"],
+  arch: ["ARCHITECTURE", "STRUCTURE"],
+  quality: ["CONVENTIONS", "TESTING"],
+  concerns: ["CONCERNS"],
+  "tech+arch": ["STACK", "INTEGRATIONS", "ARCHITECTURE", "STRUCTURE"],
+};
+
+// ─── Exported functions (exported for testing) ───────────────────────────────
+// Note: checkExistingDocuments reads the filesystem and is not purely functional.
+
+/**
+ * Parse --focus flag from raw args string.
+ * Returns default focus when flag is missing or the value is invalid.
+ * Shell-injection safe: only well-known values are accepted.
+ */
+export function parseScanArgs(args: string): { focus: string } {
+  const match = args.match(/--focus\s+([^\s]+)/i);
+  if (!match) return { focus: DEFAULT_FOCUS };
+
+  const raw = match[1].toLowerCase();
+  if ((VALID_FOCUS_AREAS as readonly string[]).includes(raw)) {
+    return { focus: raw };
+  }
+  return { focus: DEFAULT_FOCUS };
+}
+
+/**
+ * Return the list of document names (without extension) to generate for a focus.
+ * Falls back to the default focus documents for unknown values.
+ */
+export function resolveScanDocuments(focus: string): string[] {
+  return FOCUS_DOCUMENTS[focus as FocusArea] ?? FOCUS_DOCUMENTS[DEFAULT_FOCUS];
+}
+
+/**
+ * Build absolute output paths for the documents produced by a scan focus.
+ * All documents live under <basePath>/.gsd/codebase/
+ */
+export function buildScanOutputPaths(focus: string, basePath: string): string[] {
+  const docs = resolveScanDocuments(focus);
+  return docs.map((doc) => join(basePath, ".gsd", "codebase", `${doc}.md`));
+}
+
+/**
+ * Return the subset of paths that already exist on disk.
+ */
+export function checkExistingDocuments(paths: string[]): string[] {
+  return paths.filter((p) => existsSync(p));
+}
+
+// ─── Command handler ──────────────────────────────────────────────────────────
+
+export async function handleScan(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const basePath = process.cwd();
+  const { focus } = parseScanArgs(args);
+  const outputDir = join(basePath, ".gsd", "codebase");
+  const outputPaths = buildScanOutputPaths(focus, basePath);
+  const existing = checkExistingDocuments(outputPaths);
+
+  if (existing.length > 0) {
+    const names = existing.map((p) => relative(outputDir, p)).join(", ");
+    ctx.ui.notify(
+      `Existing documents will be overwritten: ${names}\nContinuing scan with focus: ${focus}`,
+      "warning",
+    );
+  }
+
+  mkdirSync(outputDir, { recursive: true });
+
+  const documents = resolveScanDocuments(focus);
+
+  ctx.ui.notify(`Running codebase scan (focus: ${focus})…`, "info");
+
+  try {
+    const prompt = loadPrompt("scan", {
+      focus,
+      documents: documents.join(", "),
+      outputDir: outputDir.replaceAll("\\", "/"),
+      workingDirectory: basePath,
+    });
+
+    pi.sendMessage(
+      { customType: "gsd-scan", content: prompt, display: false },
+      { triggerTurn: true },
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to dispatch scan: ${msg}`, "error");
+  }
+}

package/src/resources/extensions/gsd/commands-workflow-templates.ts

@@ -22,6 +22,7 @@ import { gsdRoot } from "./paths.js";
 import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
+import { resolvePlugin, type WorkflowPlugin } from "./workflow-plugins.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -348,8 +349,18 @@ export async function handleStart(
   const basePath = process.cwd();
   const date = new Date().toISOString().split("T")[0];
 
-  // Load the workflow template content
-  const workflowContent = loadWorkflowTemplate(templateId);
+  // Load the workflow template content — prefer a project/global plugin
+  // override if one exists (same name, .md format).
+  let workflowContent: string | null = null;
+  const pluginOverride = resolvePlugin(basePath, templateId);
+  if (pluginOverride && pluginOverride.source !== "bundled" && pluginOverride.format === "md") {
+    try {
+      workflowContent = readFileSync(pluginOverride.path, "utf-8");
+    } catch { /* fall through to bundled */ }
+  }
+  if (workflowContent == null) {
+    workflowContent = loadWorkflowTemplate(templateId);
+  }
   if (!workflowContent) {
     ctx.ui.notify(
       `Template "${templateId}" is registered but its workflow file (${template.file}) hasn't been created yet.`,
@@ -541,3 +552,119 @@ export function getTemplateCompletions(prefix: string): Array<{ value: string; l
     return [];
   }
 }
+
+// ─── Shared markdown-phase dispatcher (used by /gsd workflow <name>) ────────
+
+/**
+ * Dispatch a markdown-phase workflow plugin. Mirrors `handleStart`'s execution
+ * branch for resolved templates, but accepts a pre-resolved plugin (from the
+ * unified plugin resolver).
+ *
+ * Writes STATE.json into an artifact dir, creates a git branch, and dispatches
+ * the `workflow-start` prompt.
+ */
+export function dispatchMarkdownPhasePlugin(
+  plugin: WorkflowPlugin,
+  description: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): void {
+  if (plugin.meta.mode !== "markdown-phase") return;
+
+  if (isAutoActive()) {
+    ctx.ui.notify(
+      "Cannot start a markdown-phase workflow while auto-mode is running.\n" +
+      "Run /gsd pause first.",
+      "warning",
+    );
+    return;
+  }
+
+  const templateId = plugin.name;
+  const basePath = process.cwd();
+  const date = new Date().toISOString().split("T")[0];
+  let workflowContent: string;
+  try {
+    workflowContent = readFileSync(plugin.path, "utf-8");
+  } catch (err) {
+    ctx.ui.notify(
+      `Failed to read template: ${err instanceof Error ? err.message : String(err)}`,
+      "error",
+    );
+    return;
+  }
+
+  // Create artifact directory.
+  let artifactDir = "";
+  if (plugin.meta.artifactDir) {
+    const slug = slugify(description || templateId);
+    const prefix = datePrefix();
+    const num = getNextWorkflowNum(join(basePath, plugin.meta.artifactDir));
+    artifactDir = `${plugin.meta.artifactDir}${prefix}-${num}-${slug}`;
+    mkdirSync(join(basePath, artifactDir), { recursive: true });
+  }
+
+  // Create git branch unless isolation: none.
+  const git = createGitService(basePath);
+  const skipBranch = git.prefs.isolation === "none";
+  const slug = slugify(description || templateId);
+  const branchName = `gsd/${templateId}/${slug}`;
+  let branchCreated = false;
+
+  if (!skipBranch) {
+    try {
+      const current = git.getCurrentBranch();
+      if (current !== branchName) {
+        try { git.autoCommit("workflow-template", templateId, []); } catch { /* nothing to commit */ }
+        runGit(basePath, ["checkout", "-b", branchName]);
+        branchCreated = true;
+      }
+    } catch (err) {
+      ctx.ui.notify(
+        `Could not create branch ${branchName}: ${getErrorMessage(err)}. Working on current branch.`,
+        "warning",
+      );
+    }
+  }
+
+  const actualBranch = branchCreated ? branchName : git.getCurrentBranch();
+
+  // Write STATE.json.
+  if (artifactDir && plugin.meta.phases && plugin.meta.phases.length > 0) {
+    writeWorkflowState(
+      join(basePath, artifactDir),
+      templateId,
+      plugin.meta.displayName,
+      plugin.meta.phases,
+      description,
+      actualBranch,
+    );
+  }
+
+  const infoLines = [
+    `Starting workflow: ${plugin.meta.displayName}`,
+    `Phases: ${(plugin.meta.phases ?? []).join(" → ")}`,
+  ];
+  if (artifactDir) infoLines.push(`Artifacts: ${artifactDir}`);
+  infoLines.push(`Branch: ${actualBranch}`);
+  ctx.ui.notify(infoLines.join("\n"), "info");
+
+  const prompt = loadPrompt("workflow-start", {
+    templateId,
+    templateName: plugin.meta.displayName,
+    templateDescription: plugin.meta.description ?? "",
+    phases: (plugin.meta.phases ?? []).join(" → "),
+    complexity: plugin.meta.complexity ?? "medium",
+    artifactDir: artifactDir || "(none)",
+    branch: actualBranch,
+    description: description || "(none provided)",
+    issueRef: "(none)",
+    date,
+    workflowContent,
+  });
+
+  pi.sendMessage(
+    { customType: "gsd-workflow-template", content: prompt, display: false },
+    { triggerTurn: true },
+  );
+}

package/src/resources/extensions/gsd/custom-workflow-engine.ts

@@ -26,6 +26,7 @@ import {
   readGraph,
   writeGraph,
   getNextPendingStep,
+  markStepActive,
   markStepComplete,
   expandIteration,
   type WorkflowGraph,
@@ -90,78 +91,102 @@ export class CustomWorkflowEngine implements WorkflowEngine {
     state: EngineState,
     _context: { basePath: string },
   ): Promise<EngineDispatchAction> {
-    let graph = state.raw as WorkflowGraph;
-    let next = getNextPendingStep(graph);
-
-    if (!next) {
-      return {
-        action: "stop",
-        reason: "All steps complete",
-        level: "info",
-      };
-    }
-
-    // Check frozen DEFINITION.yaml for iterate config on this step
-    const def = readFrozenDefinition(this.runDir);
-    const stepDef = def.steps.find((s: StepDefinition) => s.id === next!.id);
-
-    if (stepDef?.iterate) {
-      const iterate = stepDef.iterate;
-
-      // Read source artifact
-      const sourcePath = join(this.runDir, iterate.source);
-      let sourceContent: string;
-      try {
-        sourceContent = readFileSync(sourcePath, "utf-8");
-      } catch {
-        throw new Error(
-          `Iterate source artifact not found: ${sourcePath} (step "${next.id}", source: "${iterate.source}")`,
-        );
-      }
+    const graphPath = join(this.runDir, "GRAPH.yaml");
 
-      // Extract items via regex with global+multiline flags.
-      // Guard against ReDoS: if matching takes too long on large inputs, bail.
-      const regex = new RegExp(iterate.pattern, "gm");
-      const items: string[] = [];
-      const matchStart = Date.now();
-      let match: RegExpExecArray | null;
-      while ((match = regex.exec(sourceContent)) !== null) {
-        if (match[1] !== undefined) items.push(match[1]);
-        if (Date.now() - matchStart > 5_000) {
-          throw new Error(
-            `Iterate pattern "${iterate.pattern}" exceeded 5s timeout on step "${next.id}" — possible ReDoS`,
-          );
-        }
+    return await withFileLock(graphPath, () => {
+      let graph = readGraph(this.runDir);
+      const active = graph.steps.find((step) => step.status === "active");
+      if (active) {
+        return {
+          action: "dispatch" as const,
+          step: {
+            unitType: "custom-step",
+            unitId: `${graph.metadata.name}/${active.id}`,
+            prompt: injectContext(this.runDir, active.id, active.prompt),
+          },
+        };
       }
 
-      // Expand the graph
-      const expandedGraph = expandIteration(graph, next.id, items, next.prompt);
-      writeGraph(this.runDir, expandedGraph);
-      graph = expandedGraph;
-
-      // Re-query for first instance step
-      next = getNextPendingStep(expandedGraph);
+      let next = getNextPendingStep(graph);
 
       if (!next) {
         return {
           action: "stop",
-          reason: "Iterate expansion produced no instances",
+          reason: "All steps complete",
           level: "info",
         };
       }
-    }
 
-    // Enrich prompt with context from prior step artifacts
-    const enrichedPrompt = injectContext(this.runDir, next.id, next.prompt);
+      // Check frozen DEFINITION.yaml for iterate config on this step
+      const def = readFrozenDefinition(this.runDir);
+      const stepDef = def.steps.find((s: StepDefinition) => s.id === next!.id);
 
-    return {
-      action: "dispatch",
-      step: {
-        unitType: "custom-step",
-        unitId: `${graph.metadata.name}/${next.id}`,
-        prompt: enrichedPrompt,
-      },
-    };
+      if (stepDef?.iterate) {
+        const iterate = stepDef.iterate;
+
+        // Read source artifact
+        const sourcePath = join(this.runDir, iterate.source);
+        let sourceContent: string;
+        try {
+          sourceContent = readFileSync(sourcePath, "utf-8");
+        } catch {
+          throw new Error(
+            `Iterate source artifact not found: ${sourcePath} (step "${next.id}", source: "${iterate.source}")`,
+          );
+        }
+
+        // Extract items via regex with global+multiline flags.
+        // Guard against ReDoS: if matching takes too long on large inputs, bail.
+        const regex = new RegExp(iterate.pattern, "gm");
+        const items: string[] = [];
+        const matchStart = Date.now();
+        let match: RegExpExecArray | null;
+        while ((match = regex.exec(sourceContent)) !== null) {
+          if (match[1] !== undefined) items.push(match[1]);
+          if (Date.now() - matchStart > 5_000) {
+            throw new Error(
+              `Iterate pattern "${iterate.pattern}" exceeded 5s timeout on step "${next.id}" — possible ReDoS`,
+            );
+          }
+        }
+
+        // Expand the graph
+        const expandedGraph = expandIteration(graph, next.id, items, next.prompt);
+        writeGraph(this.runDir, expandedGraph);
+        graph = expandedGraph;
+
+        // Re-query for first instance step
+        next = getNextPendingStep(expandedGraph);
+
+        if (!next) {
+          return {
+            action: "stop",
+            reason: "Iterate expansion produced no instances",
+            level: "info",
+          };
+        }
+      }
+
+      const activeGraph = markStepActive(graph, next.id);
+      writeGraph(this.runDir, activeGraph);
+
+      const activeStep = activeGraph.steps.find((s) => s.id === next.id);
+      if (!activeStep) {
+        throw new Error(`Active step not found after GRAPH.yaml update: ${next.id}`);
+      }
+
+      // Enrich prompt with context from prior step artifacts
+      const enrichedPrompt = injectContext(this.runDir, activeStep.id, activeStep.prompt);
+
+      return {
+        action: "dispatch" as const,
+        step: {
+          unitType: "custom-step",
+          unitId: `${activeGraph.metadata.name}/${activeStep.id}`,
+          prompt: enrichedPrompt,
+        },
+      };
+    });
   }
 
   /**

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

@@ -227,6 +227,18 @@ export async function nextDecisionId(): Promise<string> {
   }
 }
 
+/** Synchronous variant for use inside db.transaction(). */
+function nextDecisionIdSync(adapter: ReturnType<typeof import('./gsd-db.js')._getAdapter>): string {
+  if (!adapter) return 'D001';
+  const row = adapter
+    .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
+    .get();
+  const maxNum = row ? (row['max_num'] as number | null) : null;
+  if (maxNum == null || isNaN(maxNum)) return 'D001';
+  const next = maxNum + 1;
+  return `D${String(next).padStart(3, '0')}`;
+}
+
 // ─── Next Requirement ID ─────────────────────────────────────────────────
 
 /**
@@ -363,6 +375,18 @@ export async function saveRequirementToDb(
   }
 }
 
+// ─── Async Mutex for Decision Saves ───────────────────────────────────────
+//
+// Serializes the entire saveDecisionToDb operation (ID generation + DB upsert
+// + file read + markdown regeneration + file write) so that parallel callers
+// cannot interleave and produce a last-writer-wins race on DECISIONS.md.
+let _decisionSaveLock: Promise<unknown> = Promise.resolve();
+
+/** Reset the mutex — only for tests. */
+export function _resetDecisionSaveLock(): void {
+  _decisionSaveLock = Promise.resolve();
+}
+
 // ─── Save Decision to DB + Regenerate Markdown ────────────────────────────
 
 export interface SaveDecisionFields {
@@ -373,15 +397,18 @@ export interface SaveDecisionFields {
   revisable?: string;
   when_context?: string;
   made_by?: import('./types.js').DecisionMadeBy;
+  /** ADR-011 Phase 2: origin of the decision — "discussion" (default), "planning", "escalation". */
+  source?: string;
 }
 
 /**
  * Save a new decision to DB and regenerate DECISIONS.md.
  * Auto-assigns the next ID via nextDecisionId().
  *
- * The ID computation (SELECT MAX) and insert are wrapped in a single
- * transaction to prevent parallel tool calls from computing the same ID
- * and silently overwriting each other (#3326, #3339, #3459).
+ * Concurrency: uses an async mutex (promise chain) to serialize the entire
+ * operation — ID generation, DB upsert, file read, markdown regeneration,
+ * and file write — preventing parallel callers from overwriting each other's
+ * output (last-writer-wins race condition).
  *
  * Returns the assigned ID.
  */
@@ -389,23 +416,25 @@ export async function saveDecisionToDb(
   fields: SaveDecisionFields,
   basePath: string,
 ): Promise<{ id: string }> {
+  // Serialize via async mutex: each call waits for the previous one to
+  // complete before starting, preventing interleaved DB + file writes.
+  let release: () => void;
+  const prev = _decisionSaveLock;
+  _decisionSaveLock = new Promise<void>(r => { release = r; });
+
   try {
-    const db = await import('./gsd-db.js');
+    await prev;
+  } catch {
+    // Previous call failed — proceed regardless; the lock chain must continue.
+  }
 
-    // Atomic ID assignment + insert inside a transaction to prevent
-    // parallel calls from racing on the same MAX(id) value.
-    const id = db.transaction(() => {
-      const adapter = db._getAdapter();
-      if (!adapter) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  try {
+    const db = await import('./gsd-db.js');
 
-      const row = adapter
-        .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
-        .get();
-      const maxNum = row ? (row['max_num'] as number | null) : null;
-      const nextId = (maxNum == null || isNaN(maxNum))
-        ? 'D001'
-        : `D${String(maxNum + 1).padStart(3, '0')}`;
+    const adapter = db._getAdapter();
 
+    const id = db.transaction(() => {
+      const nextId = nextDecisionIdSync(adapter);
       db.upsertDecision({
         id: nextId,
         when_context: fields.when_context ?? '',
@@ -415,14 +444,15 @@ export async function saveDecisionToDb(
         rationale: fields.rationale,
         revisable: fields.revisable ?? 'Yes',
         made_by: fields.made_by ?? 'agent',
+        source: fields.source ?? 'discussion',
         superseded_by: null,
       });
 
+
       return nextId;
     });
 
     // Fetch all decisions (including superseded for the full register)
-    const adapter = db._getAdapter();
     let allDecisions: Decision[] = [];
     if (adapter) {
       const rows = adapter.prepare('SELECT * FROM decisions ORDER BY seq').all();
@@ -499,10 +529,54 @@ export async function saveDecisionToDb(
     clearPathCache();
     clearParseCache();
 
+    // ADR-013 dual-write: keep the memory store in sync with every decision
+    // persisted via the legacy gsd_save_decision path. Without this, prompts
+    // that still call gsd_save_decision (discuss.md, plan-milestone.md,
+    // guided-plan-slice.md, et al. during the deprecation window) would
+    // create decisions rows invisible to memory_query and loadMemoryBlock.
+    // Best-effort — never throw, never roll back the decision on failure.
+    try {
+      const { createMemory } = await import('./memory-store.js');
+      const decisionText = (fields.decision ?? '').trim();
+      const choiceText = (fields.choice ?? '').trim();
+      const rationaleText = (fields.rationale ?? '').trim();
+      const contentParts: string[] = [];
+      if (decisionText) contentParts.push(decisionText);
+      if (choiceText) contentParts.push(`Chose: ${choiceText}.`);
+      if (rationaleText) contentParts.push(`Rationale: ${rationaleText}.`);
+      const content = contentParts.join(' ').slice(0, 600);
+      if (content) {
+        createMemory({
+          category: 'architecture',
+          content,
+          scope: fields.scope || 'project',
+          confidence: 0.85,
+          structuredFields: {
+            sourceDecisionId: id,
+            when_context: fields.when_context ?? '',
+            scope: fields.scope,
+            decision: fields.decision,
+            choice: fields.choice,
+            rationale: fields.rationale,
+            made_by: fields.made_by ?? 'agent',
+            revisable: fields.revisable ?? '',
+          },
+        });
+      }
+    } catch (mirrorErr) {
+      logError('manifest', 'memory-store mirror write failed (non-fatal)', {
+        fn: 'saveDecisionToDb',
+        decisionId: id,
+        error: String((mirrorErr as Error).message),
+      });
+    }
+
     return { id };
   } catch (err) {
     logError('manifest', 'saveDecisionToDb failed', { fn: 'saveDecisionToDb', error: String((err as Error).message) });
     throw err;
+  } finally {
+    release!();
   }
 }