gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/dist/resources/extensions/gsd/commands-workflow-templates.js

@@ -12,6 +12,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 } from "./workflow-plugins.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from text.
@@ -257,8 +258,19 @@ export async function handleStart(args, ctx, pi) {
     const template = match.template;
     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 = 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.`, "warning");
         return;
@@ -406,3 +418,90 @@ export function getTemplateCompletions(prefix) {
         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, description, ctx, pi) {
+    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;
+    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/dist/resources/extensions/gsd/custom-workflow-engine.js

@@ -13,7 +13,7 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readGraph, writeGraph, getNextPendingStep, markStepComplete, expandIteration, } from "./graph.js";
+import { readGraph, writeGraph, getNextPendingStep, markStepActive, markStepComplete, expandIteration, } from "./graph.js";
 import { injectContext } from "./context-injector.js";
 import { readFrozenDefinition } from "./definition-io.js";
 import { parseUnitId } from "./unit-id.js";
@@ -62,66 +62,86 @@ export class CustomWorkflowEngine {
      * - Expanded GRAPH.yaml is written to disk before dispatch — inspectable on disk.
      */
     async resolveDispatch(state, _context) {
-        let graph = state.raw;
-        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) => s.id === next.id);
-        if (stepDef?.iterate) {
-            const iterate = stepDef.iterate;
-            // Read source artifact
-            const sourcePath = join(this.runDir, iterate.source);
-            let sourceContent;
-            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 = [];
-            const matchStart = Date.now();
-            let match;
-            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`);
-                }
+        const graphPath = join(this.runDir, "GRAPH.yaml");
+        return await withFileLock(graphPath, () => {
+            let graph = readGraph(this.runDir);
+            const active = graph.steps.find((step) => step.status === "active");
+            if (active) {
+                return {
+                    action: "dispatch",
+                    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);
-        return {
-            action: "dispatch",
-            step: {
-                unitType: "custom-step",
-                unitId: `${graph.metadata.name}/${next.id}`,
-                prompt: enrichedPrompt,
-            },
-        };
+            // Check frozen DEFINITION.yaml for iterate config on this step
+            const def = readFrozenDefinition(this.runDir);
+            const stepDef = def.steps.find((s) => s.id === next.id);
+            if (stepDef?.iterate) {
+                const iterate = stepDef.iterate;
+                // Read source artifact
+                const sourcePath = join(this.runDir, iterate.source);
+                let sourceContent;
+                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 = [];
+                const matchStart = Date.now();
+                let match;
+                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",
+                step: {
+                    unitType: "custom-step",
+                    unitId: `${activeGraph.metadata.name}/${activeStep.id}`,
+                    prompt: enrichedPrompt,
+                },
+            };
+        });
     }
     /**
      * Reconcile state after a step completes.

package/dist/resources/extensions/gsd/db-writer.js

@@ -205,6 +205,19 @@ export async function nextDecisionId() {
         return 'D001';
     }
 }
+/** Synchronous variant for use inside db.transaction(). */
+function nextDecisionIdSync(adapter) {
+    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'] : null;
+    if (maxNum == null || isNaN(maxNum))
+        return 'D001';
+    const next = maxNum + 1;
+    return `D${String(next).padStart(3, '0')}`;
+}
 // ─── Next Requirement ID ─────────────────────────────────────────────────
 /**
  * Compute the next requirement ID from the current DB state.
@@ -318,32 +331,44 @@ export async function saveRequirementToDb(fields, basePath) {
         throw err;
     }
 }
+// ─── 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.resolve();
+/** Reset the mutex — only for tests. */
+export function _resetDecisionSaveLock() {
+    _decisionSaveLock = Promise.resolve();
+}
 /**
  * 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.
  */
 export async function saveDecisionToDb(fields, basePath) {
+    // Serialize via async mutex: each call waits for the previous one to
+    // complete before starting, preventing interleaved DB + file writes.
+    let release;
+    const prev = _decisionSaveLock;
+    _decisionSaveLock = new Promise(r => { release = r; });
+    try {
+        await prev;
+    }
+    catch {
+        // Previous call failed — proceed regardless; the lock chain must continue.
+    }
     try {
         const db = await import('./gsd-db.js');
-        // Atomic ID assignment + insert inside a transaction to prevent
-        // parallel calls from racing on the same MAX(id) value.
+        const adapter = db._getAdapter();
         const id = db.transaction(() => {
-            const adapter = db._getAdapter();
-            if (!adapter)
-                throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-            const row = adapter
-                .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions')
-                .get();
-            const maxNum = row ? row['max_num'] : null;
-            const nextId = (maxNum == null || isNaN(maxNum))
-                ? 'D001'
-                : `D${String(maxNum + 1).padStart(3, '0')}`;
+            const nextId = nextDecisionIdSync(adapter);
             db.upsertDecision({
                 id: nextId,
                 when_context: fields.when_context ?? '',
@@ -353,12 +378,12 @@ export async function saveDecisionToDb(fields, basePath) {
                 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 = [];
         if (adapter) {
             const rows = adapter.prepare('SELECT * FROM decisions ORDER BY seq').all();
@@ -433,12 +458,60 @@ export async function saveDecisionToDb(fields, basePath) {
         invalidateStateCache();
         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 = [];
+            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.message),
+            });
+        }
         return { id };
     }
     catch (err) {
         logError('manifest', 'saveDecisionToDb failed', { fn: 'saveDecisionToDb', error: String(err.message) });
         throw err;
     }
+    finally {
+        release();
+    }
 }
 /**
  * Extract a milestone/slice reference from a deferral decision.

package/dist/resources/extensions/gsd/debug-session-store.js

@@ -0,0 +1,238 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { gsdRoot } from "./paths.js";
+const DEFAULT_PHASE = "queued";
+const DEFAULT_STATUS = "active";
+const SESSION_FILE_SUFFIX = ".json";
+const MAX_SLUG_LENGTH = 64;
+const MAX_COLLISION_ATTEMPTS = 10_000;
+function debugRoot(basePath) {
+    return join(gsdRoot(basePath), "debug");
+}
+export function debugSessionsDir(basePath) {
+    return join(debugRoot(basePath), "sessions");
+}
+export function debugSessionArtifactPath(basePath, slug) {
+    assertValidDebugSessionSlug(slug);
+    return join(debugSessionsDir(basePath), `${slug}${SESSION_FILE_SUFFIX}`);
+}
+export function debugSessionLogPath(basePath, slug) {
+    assertValidDebugSessionSlug(slug);
+    return join(debugRoot(basePath), `${slug}.log`);
+}
+function ensureSessionsDir(basePath) {
+    const dir = debugSessionsDir(basePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function slugifyDebugSessionIssue(issue) {
+    const normalized = issue
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-")
+        .slice(0, MAX_SLUG_LENGTH)
+        .replace(/-+$/g, "");
+    if (!normalized) {
+        throw new Error("Issue text must contain at least one alphanumeric character.");
+    }
+    return normalized;
+}
+export function assertValidDebugSessionSlug(slug) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) {
+        throw new Error(`Invalid debug session slug: ${slug}`);
+    }
+}
+function isDebugSessionStatus(value) {
+    return value === "active" || value === "paused" || value === "resolved" || value === "failed";
+}
+function isDebugCheckpointShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    const validTypes = ["human-verify", "human-action", "decision", "root-cause-found", "inconclusive"];
+    return (validTypes.includes(o.type)
+        && typeof o.summary === "string"
+        && typeof o.awaitingResponse === "boolean"
+        && (o.userResponse === undefined || typeof o.userResponse === "string"));
+}
+function isDebugTddGateShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    const validPhases = ["pending", "red", "green"];
+    return (typeof o.enabled === "boolean"
+        && validPhases.includes(o.phase)
+        && (o.testFile === undefined || typeof o.testFile === "string")
+        && (o.testName === undefined || typeof o.testName === "string")
+        && (o.failureOutput === undefined || typeof o.failureOutput === "string"));
+}
+function isDebugSpecialistReviewShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    return (typeof o.hint === "string"
+        && (typeof o.skill === "string" || o.skill === null)
+        && typeof o.verdict === "string"
+        && typeof o.detail === "string"
+        && typeof o.reviewedAt === "number");
+}
+function isDebugSessionArtifact(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    return (o.version === 1
+        && (o.mode === "debug" || o.mode === "diagnose")
+        && typeof o.slug === "string"
+        && typeof o.issue === "string"
+        && isDebugSessionStatus(o.status)
+        && typeof o.phase === "string"
+        && typeof o.createdAt === "number"
+        && typeof o.updatedAt === "number"
+        && typeof o.logPath === "string"
+        && (typeof o.lastError === "string" || o.lastError === null)
+        && (o.checkpoint === undefined || o.checkpoint === null || isDebugCheckpointShape(o.checkpoint))
+        && (o.tddGate === undefined || o.tddGate === null || isDebugTddGateShape(o.tddGate))
+        && (o.specialistReview === undefined || o.specialistReview === null || isDebugSpecialistReviewShape(o.specialistReview)));
+}
+function parseDebugSessionArtifact(filePath, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse debug session artifact ${filePath}: ${message}`);
+    }
+    if (!isDebugSessionArtifact(parsed)) {
+        throw new Error(`Malformed debug session artifact ${filePath}: schema validation failed`);
+    }
+    return parsed;
+}
+function defaultDeps(deps) {
+    return {
+        atomicWrite: deps.atomicWrite ?? atomicWriteSync,
+        readFile: deps.readFile ?? ((filePath, encoding) => readFileSync(filePath, encoding)),
+        listDir: deps.listDir ?? ((dirPath) => readdirSync(dirPath)),
+        exists: deps.exists ?? ((filePath) => existsSync(filePath)),
+        now: deps.now ?? (() => Date.now()),
+    };
+}
+function nextSlug(basePath, baseSlug, deps) {
+    const baseArtifactPath = debugSessionArtifactPath(basePath, baseSlug);
+    if (!deps.exists(baseArtifactPath))
+        return baseSlug;
+    for (let n = 2; n < MAX_COLLISION_ATTEMPTS; n++) {
+        const candidate = `${baseSlug}-${n}`;
+        const candidatePath = debugSessionArtifactPath(basePath, candidate);
+        if (!deps.exists(candidatePath))
+            return candidate;
+    }
+    throw new Error(`Unable to allocate unique debug session slug for '${baseSlug}'`);
+}
+function serializeArtifact(session) {
+    return JSON.stringify(session, null, 2) + "\n";
+}
+export function createDebugSession(basePath, input, deps = {}) {
+    const d = defaultDeps(deps);
+    const issue = input.issue?.trim() ?? "";
+    if (!issue) {
+        throw new Error("Issue text is required to create a debug session.");
+    }
+    ensureSessionsDir(basePath);
+    const baseSlug = slugifyDebugSessionIssue(issue);
+    const slug = nextSlug(basePath, baseSlug, d);
+    const now = input.createdAt ?? d.now();
+    const session = {
+        version: 1,
+        mode: input.mode ?? "debug",
+        slug,
+        issue,
+        status: input.status ?? DEFAULT_STATUS,
+        phase: input.phase ?? DEFAULT_PHASE,
+        createdAt: now,
+        updatedAt: now,
+        logPath: debugSessionLogPath(basePath, slug),
+        lastError: null,
+    };
+    const artifactPath = debugSessionArtifactPath(basePath, slug);
+    d.atomicWrite(artifactPath, serializeArtifact(session), "utf-8");
+    return { artifactPath, session };
+}
+export function loadDebugSession(basePath, slug, deps = {}) {
+    assertValidDebugSessionSlug(slug);
+    const d = defaultDeps(deps);
+    const artifactPath = debugSessionArtifactPath(basePath, slug);
+    if (!d.exists(artifactPath))
+        return null;
+    const raw = d.readFile(artifactPath, "utf-8");
+    const session = parseDebugSessionArtifact(artifactPath, raw);
+    return { artifactPath, session };
+}
+export function listDebugSessions(basePath, deps = {}) {
+    const d = defaultDeps(deps);
+    const dir = debugSessionsDir(basePath);
+    if (!d.exists(dir))
+        return { sessions: [], malformed: [] };
+    const entries = d.listDir(dir)
+        .filter(entry => entry.endsWith(SESSION_FILE_SUFFIX))
+        .sort((a, b) => a.localeCompare(b));
+    const sessions = [];
+    const malformed = [];
+    for (const entry of entries) {
+        const artifactPath = join(dir, entry);
+        try {
+            const raw = d.readFile(artifactPath, "utf-8");
+            const session = parseDebugSessionArtifact(artifactPath, raw);
+            sessions.push({ artifactPath, session });
+        }
+        catch (error) {
+            malformed.push({
+                artifactPath,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    sessions.sort((a, b) => {
+        if (a.session.updatedAt !== b.session.updatedAt) {
+            return b.session.updatedAt - a.session.updatedAt;
+        }
+        if (a.session.createdAt !== b.session.createdAt) {
+            return b.session.createdAt - a.session.createdAt;
+        }
+        return a.session.slug.localeCompare(b.session.slug);
+    });
+    return { sessions, malformed };
+}
+export function updateDebugSession(basePath, slug, update, deps = {}) {
+    const d = defaultDeps(deps);
+    const loaded = loadDebugSession(basePath, slug, d);
+    if (!loaded) {
+        throw new Error(`Debug session not found for slug: ${slug}`);
+    }
+    const nextIssue = update.issue?.trim() ?? loaded.session.issue;
+    if (!nextIssue) {
+        throw new Error("Issue text cannot be empty.");
+    }
+    const nextStatus = update.status ?? loaded.session.status;
+    if (!isDebugSessionStatus(nextStatus)) {
+        throw new Error(`Invalid debug session status: ${String(update.status)}`);
+    }
+    const nextUpdatedAt = update.updatedAt ?? d.now();
+    const session = {
+        ...loaded.session,
+        issue: nextIssue,
+        status: nextStatus,
+        phase: update.phase ?? loaded.session.phase,
+        lastError: update.lastError === undefined ? loaded.session.lastError : update.lastError,
+        checkpoint: update.checkpoint === undefined ? loaded.session.checkpoint : update.checkpoint,
+        tddGate: update.tddGate === undefined ? loaded.session.tddGate : update.tddGate,
+        specialistReview: update.specialistReview === undefined ? loaded.session.specialistReview : update.specialistReview,
+        updatedAt: nextUpdatedAt,
+    };
+    d.atomicWrite(loaded.artifactPath, serializeArtifact(session), "utf-8");
+    return { artifactPath: loaded.artifactPath, session };
+}

package/dist/resources/extensions/gsd/definition-loader.js

@@ -246,6 +246,13 @@ export function validateDefinition(parsed) {
  */
 export function loadDefinition(defsDir, name) {
     const filePath = join(defsDir, `${name}.yaml`);
+    return loadDefinitionFromFile(filePath);
+}
+/**
+ * Load and validate a YAML workflow definition from an absolute file path.
+ * Accepts both `.yaml` and `.yml` extensions.
+ */
+export function loadDefinitionFromFile(filePath) {
     if (!existsSync(filePath)) {
         throw new Error(`Definition file not found: ${filePath}`);
     }