gsd-pi 2.41.0-dev.cac69f9 → 2.42.0-dev.1df898f

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

@@ -0,0 +1,312 @@
+/**
+ * graph.ts — Pure data module for GRAPH.yaml workflow step tracking.
+ *
+ * Provides types and functions for reading, writing, and querying the
+ * step graph that drives CustomWorkflowEngine. Zero engine dependencies.
+ *
+ * GRAPH.yaml lives in a run directory and tracks step statuses
+ * (pending → active → complete) with optional dependency edges.
+ *
+ * Observability:
+ * - readGraph/writeGraph use YAML on disk — human-readable, diffable,
+ *   inspectable with `cat` or any YAML viewer.
+ * - Each GraphStep has status, startedAt, finishedAt fields visible in GRAPH.yaml.
+ * - writeGraph uses atomic write (tmp + rename) for crash safety.
+ * - All operations are immutable — callers always get a new graph object.
+ */
+
+import { parse, stringify } from "yaml";
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { WorkflowDefinition } from "./definition-loader.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface GraphStep {
+  /** Unique step identifier within the workflow. */
+  id: string;
+  /** Human-readable step title. */
+  title: string;
+  /** Current status: pending → active → complete → expanded (iterate parent). */
+  status: "pending" | "active" | "complete" | "expanded";
+  /** The prompt to dispatch for this step. */
+  prompt: string;
+  /** IDs of steps that must be "complete" before this step can run. */
+  dependsOn: string[];
+  /** For iteration instances: ID of the parent step that was expanded. */
+  parentStepId?: string;
+  /** ISO timestamp when the step started executing. */
+  startedAt?: string;
+  /** ISO timestamp when the step finished executing. */
+  finishedAt?: string;
+}
+
+export interface WorkflowGraph {
+  /** Ordered list of steps in the workflow. */
+  steps: GraphStep[];
+  /** Workflow metadata. */
+  metadata: {
+    name: string;
+    createdAt: string;
+  };
+}
+
+// ─── YAML schema mapping ─────────────────────────────────────────────────
+
+const GRAPH_FILENAME = "GRAPH.yaml";
+
+/**
+ * Internal YAML shape — uses snake_case for YAML keys.
+ * Converted to/from the camelCase TypeScript types on read/write.
+ */
+interface YamlStep {
+  id: string;
+  title: string;
+  status: string;
+  prompt: string;
+  depends_on?: string[];
+  parent_step_id?: string;
+  started_at?: string;
+  finished_at?: string;
+}
+
+interface YamlGraph {
+  steps: YamlStep[];
+  metadata: { name: string; created_at: string };
+}
+
+// ─── Functions ───────────────────────────────────────────────────────────
+
+/**
+ * Read and parse GRAPH.yaml from a run directory.
+ *
+ * @param runDir — directory containing GRAPH.yaml
+ * @returns Parsed workflow graph
+ * @throws Error if file doesn't exist or YAML is malformed
+ */
+export function readGraph(runDir: string): WorkflowGraph {
+  const filePath = join(runDir, GRAPH_FILENAME);
+  if (!existsSync(filePath)) {
+    throw new Error(`GRAPH.yaml not found: ${filePath}`);
+  }
+  const raw = readFileSync(filePath, "utf-8");
+  const yaml = parse(raw) as YamlGraph;
+
+  if (!yaml?.steps || !Array.isArray(yaml.steps)) {
+    throw new Error(`Invalid GRAPH.yaml: missing or invalid 'steps' array in ${filePath}`);
+  }
+
+  return {
+    steps: yaml.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      status: s.status as GraphStep["status"],
+      prompt: s.prompt,
+      dependsOn: s.depends_on ?? [],
+      ...(s.parent_step_id != null ? { parentStepId: s.parent_step_id } : {}),
+      ...(s.started_at != null ? { startedAt: s.started_at } : {}),
+      ...(s.finished_at != null ? { finishedAt: s.finished_at } : {}),
+    })),
+    metadata: {
+      name: yaml.metadata?.name ?? "unnamed",
+      createdAt: yaml.metadata?.created_at ?? new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Write a workflow graph to GRAPH.yaml in a run directory.
+ * Creates the directory if it doesn't exist. Write is atomic (write + rename).
+ *
+ * @param runDir — directory to write GRAPH.yaml into
+ * @param graph — the workflow graph to serialize
+ */
+export function writeGraph(runDir: string, graph: WorkflowGraph): void {
+  if (!existsSync(runDir)) {
+    mkdirSync(runDir, { recursive: true });
+  }
+
+  const yamlData: YamlGraph = {
+    steps: graph.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      status: s.status,
+      prompt: s.prompt,
+      depends_on: s.dependsOn.length > 0 ? s.dependsOn : undefined,
+      parent_step_id: s.parentStepId ?? undefined,
+      started_at: s.startedAt ?? undefined,
+      finished_at: s.finishedAt ?? undefined,
+    })) as YamlStep[],
+    metadata: {
+      name: graph.metadata.name,
+      created_at: graph.metadata.createdAt,
+    },
+  };
+
+  const filePath = join(runDir, GRAPH_FILENAME);
+  const tmpPath = filePath + ".tmp";
+  const content = stringify(yamlData);
+  writeFileSync(tmpPath, content, "utf-8");
+  // Atomic rename for crash safety
+  renameSync(tmpPath, filePath);
+}
+
+/**
+ * Get the next pending step whose dependencies are all complete.
+ *
+ * Returns the first step (in array order) with status "pending" where
+ * every step in its `dependsOn` list has status "complete".
+ *
+ * @param graph — the workflow graph to query
+ * @returns The next dispatchable step, or null if none available
+ */
+export function getNextPendingStep(graph: WorkflowGraph): GraphStep | null {
+  const statusMap = new Map(graph.steps.map((s) => [s.id, s.status]));
+
+  for (const step of graph.steps) {
+    if (step.status !== "pending") continue;
+    const depsComplete = step.dependsOn.every(
+      (depId) => statusMap.get(depId) === "complete",
+    );
+    if (depsComplete) return step;
+  }
+
+  return null;
+}
+
+/**
+ * Return a new graph with the specified step marked as "complete".
+ * Immutable — does not mutate the input graph.
+ *
+ * @param graph — the current workflow graph
+ * @param stepId — ID of the step to mark complete
+ * @returns New graph with the step's status set to "complete"
+ * @throws Error if stepId is not found in the graph
+ */
+export function markStepComplete(
+  graph: WorkflowGraph,
+  stepId: string,
+): WorkflowGraph {
+  const found = graph.steps.some((s) => s.id === stepId);
+  if (!found) {
+    throw new Error(`Step not found: ${stepId}`);
+  }
+
+  return {
+    ...graph,
+    steps: graph.steps.map((s) =>
+      s.id === stepId
+        ? { ...s, status: "complete" as const, finishedAt: new Date().toISOString() }
+        : s,
+    ),
+  };
+}
+
+// ─── Iteration expansion ─────────────────────────────────────────────────
+
+/**
+ * Expand an iterate step into concrete instances. Pure and deterministic —
+ * identical inputs always produce identical output.
+ *
+ * Given a parent step with status "pending" and an array of matched items,
+ * creates one instance step per item, marks the parent as "expanded", and
+ * rewrites any downstream dependsOn references from the parent ID to the
+ * full set of instance IDs.
+ *
+ * @param graph — the current workflow graph (not mutated)
+ * @param stepId — ID of the iterate step to expand
+ * @param items — matched items from the source artifact
+ * @param promptTemplate — template with {{item}} placeholders
+ * @returns New WorkflowGraph with instances inserted and deps rewritten
+ * @throws Error if stepId not found or step is not pending
+ */
+export function expandIteration(
+  graph: WorkflowGraph,
+  stepId: string,
+  items: string[],
+  promptTemplate: string,
+): WorkflowGraph {
+  const parentIndex = graph.steps.findIndex((s) => s.id === stepId);
+  if (parentIndex === -1) {
+    throw new Error(`expandIteration: step not found: ${stepId}`);
+  }
+  const parentStep = graph.steps[parentIndex];
+  if (parentStep.status !== "pending") {
+    throw new Error(
+      `expandIteration: step "${stepId}" has status "${parentStep.status}", expected "pending"`,
+    );
+  }
+
+  // Create instance steps
+  const instanceIds: string[] = [];
+  const instances: GraphStep[] = items.map((item, i) => {
+    const instanceId = `${stepId}--${String(i + 1).padStart(3, "0")}`;
+    instanceIds.push(instanceId);
+    return {
+      id: instanceId,
+      title: `${parentStep.title}: ${item}`,
+      status: "pending" as const,
+      prompt: promptTemplate.replace(/\{\{item\}\}/g, () => item),
+      dependsOn: [...parentStep.dependsOn],
+      parentStepId: stepId,
+    };
+  });
+
+  // Build new steps array: copy everything, mark parent as expanded,
+  // insert instances right after the parent, rewrite downstream deps.
+  const newSteps: GraphStep[] = [];
+  for (let i = 0; i < graph.steps.length; i++) {
+    if (i === parentIndex) {
+      // Mark parent as expanded
+      newSteps.push({ ...parentStep, status: "expanded" as const });
+      // Insert instances immediately after parent
+      newSteps.push(...instances);
+    } else {
+      const step = graph.steps[i];
+      // Rewrite dependsOn: replace parent ID with all instance IDs
+      const hasDep = step.dependsOn.includes(stepId);
+      if (hasDep) {
+        const rewritten = step.dependsOn.flatMap((dep) =>
+          dep === stepId ? instanceIds : [dep],
+        );
+        newSteps.push({ ...step, dependsOn: rewritten });
+      } else {
+        newSteps.push(step);
+      }
+    }
+  }
+
+  return {
+    ...graph,
+    steps: newSteps,
+  };
+}
+
+// ─── Definition → Graph conversion ──────────────────────────────────────
+
+/**
+ * Convert a parsed WorkflowDefinition into a WorkflowGraph with all
+ * steps in "pending" status. Used by run-manager to generate the initial
+ * GRAPH.yaml for a new run.
+ *
+ * @param def — a validated WorkflowDefinition from definition-loader
+ * @returns WorkflowGraph with pending steps and metadata from the definition
+ */
+export function initializeGraph(def: WorkflowDefinition): WorkflowGraph {
+  return {
+    steps: def.steps.map((s) => ({
+      id: s.id,
+      title: s.name,
+      status: "pending" as const,
+      prompt: s.prompt,
+      dependsOn: s.requires ?? [],
+    })),
+    metadata: {
+      name: def.name,
+      createdAt: new Date().toISOString(),
+    },
+  };
+}
+
+/** @deprecated Use initializeGraph instead. Kept for backward compatibility. */
+export { initializeGraph as graphFromDefinition };

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -847,6 +847,7 @@ export function nativeMergeSquash(basePath: string, branch: string): GitMergeRes
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
     });
     return { success: true, conflicts: [] };
   } catch (err: unknown) {

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

@@ -89,6 +89,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "reactive_execution",
   "github",
   "service_tier",
+  "forensics_dedup",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -223,6 +224,8 @@ export interface GSDPreferences {
   github?: GitHubSyncConfig;
   /** OpenAI service tier preference. "priority" = 2x cost, faster. "flex" = 0.5x cost, slower. Only affects gpt-5.4 models. */
   service_tier?: "priority" | "flex";
+  /** Opt-in: search existing issues and PRs before filing from /gsd forensics. Uses additional AI tokens. */
+  forensics_dedup?: boolean;
 }
 
 export interface LoadedGSDPreferences {

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

@@ -200,12 +200,22 @@ function loadPreferencesFile(path: string, scope: "global" | "project"): LoadedG
 export function parsePreferencesMarkdown(content: string): GSDPreferences | null {
   // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
   const startMarker = content.startsWith('---\r\n') ? '---\r\n' : '---\n';
-  if (!content.startsWith(startMarker)) return null;
-  const searchStart = startMarker.length;
-  const endIdx = content.indexOf('\n---', searchStart);
-  if (endIdx === -1) return null;
-  const block = content.slice(searchStart, endIdx);
-  return parseFrontmatterBlock(block.replace(/\r/g, ''));
+  if (content.startsWith(startMarker)) {
+    const searchStart = startMarker.length;
+    const endIdx = content.indexOf('\n---', searchStart);
+    if (endIdx === -1) return null;
+    const block = content.slice(searchStart, endIdx);
+    return parseFrontmatterBlock(block.replace(/\r/g, ''));
+  }
+
+  // Fallback: heading+list format (e.g. "## Git\n- isolation: none") (#2036)
+  // GSD agents may write preferences files without frontmatter delimiters.
+  if (/^##\s+\w/m.test(content)) {
+    return parseHeadingListFormat(content);
+  }
+
+  console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
+  return null;
 }
 
 function parseFrontmatterBlock(frontmatter: string): GSDPreferences {
@@ -221,6 +231,51 @@ function parseFrontmatterBlock(frontmatter: string): GSDPreferences {
   }
 }
 
+/**
+ * Parse heading+list format into a nested object, then cast to GSDPreferences.
+ * Handles markdown like:
+ *   ## Git
+ *   - isolation: none
+ *   - commit_docs: true
+ *   ## Models
+ *   - planner: sonnet
+ */
+function parseHeadingListFormat(content: string): GSDPreferences {
+  const result: Record<string, Record<string, string>> = {};
+  let currentSection: string | null = null;
+
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    const headingMatch = line.match(/^##\s+(.+)$/);
+    if (headingMatch) {
+      currentSection = headingMatch[1].trim().toLowerCase().replace(/\s+/g, '_');
+      continue;
+    }
+    if (currentSection) {
+      const itemMatch = line.match(/^-\s+([^:]+):\s*(.*)$/);
+      if (itemMatch) {
+        if (!result[currentSection]) result[currentSection] = {};
+        const value = itemMatch[2].trim();
+        // Coerce "true"/"false" strings and numbers
+        result[currentSection][itemMatch[1].trim()] = value;
+      }
+    }
+  }
+
+  // Convert string values to appropriate types via YAML parser for each section
+  const typed: Record<string, unknown> = {};
+  for (const [section, entries] of Object.entries(result)) {
+    const yamlLines = Object.entries(entries).map(([k, v]) => `${k}: ${v}`).join('\n');
+    try {
+      typed[section] = parseYaml(yamlLines);
+    } catch {
+      typed[section] = entries;
+    }
+  }
+
+  return typed as GSDPreferences;
+}
+
 // ─── Merging ────────────────────────────────────────────────────────────────
 
 /**
@@ -286,6 +341,7 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
       ? { ...(base.github ?? {}), ...(override.github ?? {}) } as import("../github-sync/types.js").GitHubSyncConfig
       : undefined,
     service_tier: override.service_tier ?? base.service_tier,
+    forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
   };
 }
 

package/src/resources/extensions/gsd/prompts/forensics.md

@@ -101,11 +101,19 @@ Explain your findings:
 - **Code snippet** — the problematic code and what it should do instead
 - **Recovery** — what the user can do right now to get unstuck
 
+{{dedupSection}}
+
 Then **offer GitHub issue creation**: "Would you like me to create a GitHub issue for this on gsd-build/gsd-2?"
 
-If yes, create using `gh issue create` with this format:
+**CRITICAL: The `github_issues` tool ONLY targets the current user's repository — it has no `repo` parameter. You MUST use `gh issue create --repo gsd-build/gsd-2` via the `bash` tool to file on the correct repo. Do NOT use the `github_issues` tool for this.**
 
-```
+If yes, create using the `bash` tool:
+
+```bash
+gh issue create --repo gsd-build/gsd-2 \
+  --title "..." \
+  --label "bug" --label "auto-generated" \
+  --body "$(cat <<'EOF'
 ## Problem
 [1-2 sentence summary]
 
@@ -128,11 +136,10 @@ If yes, create using `gh issue create` with this format:
 
 ---
 *Auto-generated by `/gsd forensics`*
+EOF
+)"
 ```
 
-**Repository:** gsd-build/gsd-2
-**Labels:** bug, auto-generated
-
 ### Redaction Rules (CRITICAL)
 
 Before creating the issue, you MUST:

package/src/resources/extensions/gsd/repo-identity.ts

@@ -8,7 +8,7 @@
 
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
@@ -271,15 +271,54 @@ export function externalProjectsRoot(): string {
   return join(base, "projects");
 }
 
+// ─── Numbered Variant Cleanup ────────────────────────────────────────────────
+
+/**
+ * macOS collision pattern: `.gsd 2`, `.gsd 3`, `.gsd 4`, etc.
+ *
+ * When `symlinkSync` (or Finder) tries to create `.gsd` but a real directory
+ * already exists at that path, macOS APFS silently renames the new entry to
+ * `.gsd 2`, then `.gsd 3`, and so on. These numbered variants confuse GSD
+ * because the canonical `.gsd` path no longer resolves to the external state
+ * directory, making tracked planning files appear deleted.
+ *
+ * This helper scans the project root for entries matching `.gsd <digits>` and
+ * removes them. It is called early in `ensureGsdSymlink()` so that the
+ * canonical `.gsd` path is always the one in use.
+ */
+const GSD_NUMBERED_VARIANT_RE = /^\.gsd \d+$/;
+
+export function cleanNumberedGsdVariants(projectPath: string): string[] {
+  const removed: string[] = [];
+  try {
+    const entries = readdirSync(projectPath);
+    for (const entry of entries) {
+      if (GSD_NUMBERED_VARIANT_RE.test(entry)) {
+        const fullPath = join(projectPath, entry);
+        try {
+          rmSync(fullPath, { recursive: true, force: true });
+          removed.push(entry);
+        } catch {
+          // Best-effort: if removal fails (e.g. permissions), continue with next
+        }
+      }
+    }
+  } catch {
+    // Non-fatal: readdir failure should not block symlink creation
+  }
+  return removed;
+}
+
 // ─── Symlink Management ─────────────────────────────────────────────────────
 
 /**
  * Ensure the `<project>/.gsd` symlink points to the external state directory.
  *
- * 1. mkdir -p the external dir
- * 2. If `<project>/.gsd` doesn't exist → create symlink
- * 3. If `<project>/.gsd` is already the correct symlink → no-op
- * 4. If `<project>/.gsd` is a real directory → return as-is (migration handles later)
+ * 1. Clean up any macOS numbered collision variants (`.gsd 2`, `.gsd 3`, etc.)
+ * 2. mkdir -p the external dir
+ * 3. If `<project>/.gsd` doesn't exist → create symlink
+ * 4. If `<project>/.gsd` is already the correct symlink → no-op
+ * 5. If `<project>/.gsd` is a real directory → return as-is (migration handles later)
  *
  * Returns the resolved external path.
  */
@@ -297,6 +336,10 @@ export function ensureGsdSymlink(projectPath: string): string {
     return localGsd;
   }
 
+  // Clean up macOS numbered collision variants (.gsd 2, .gsd 3, etc.) before
+  // any existence checks — otherwise they accumulate and confuse state (#2205).
+  cleanNumberedGsdVariants(projectPath);
+
   // Ensure external directory exists
   mkdirSync(externalPath, { recursive: true });