gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/dist/resources/extensions/gsd/escalation.js

@@ -0,0 +1,321 @@
+// GSD Extension — ADR-011 Phase 2 Mid-Execution Escalation
+//
+// A single module that owns: escalation artifact I/O, detection, resolution,
+// carry-forward injection lookup, and audit-event emission. Scoped to
+// execute-task only (refine-slice escalation is deferred per ADR-011).
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveSlicePath } from "./paths.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { getTask, setTaskEscalationPending, setTaskEscalationAwaitingReview, clearTaskEscalationFlags, claimEscalationOverride, findUnappliedEscalationOverride, setTaskBlockerSource, listEscalationArtifacts, } from "./gsd-db.js";
+import { emitUokAuditEvent, buildAuditEnvelope } from "./uok/audit.js";
+import { logWarning } from "./workflow-logger.js";
+// ─── Paths ────────────────────────────────────────────────────────────────
+/**
+ * Canonical escalation artifact path, parallel to T##-SUMMARY.md:
+ *   .gsd/milestones/{M}/slices/{S}/tasks/{T}-ESCALATION.json
+ */
+export function escalationArtifactPath(basePath, milestoneId, sliceId, taskId) {
+    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    if (!sDir)
+        return null;
+    return join(sDir, "tasks", `${taskId}-ESCALATION.json`);
+}
+// ─── Artifact I/O ─────────────────────────────────────────────────────────
+/** Build an EscalationArtifact from a gsd_complete_task escalation payload. */
+export function buildEscalationArtifact(params) {
+    // Server-side validation — the MCP Type schema already constrains shape,
+    // but we belt-and-suspenders here so non-MCP callers can't construct
+    // malformed artifacts. These checks match readEscalationArtifact's.
+    if (!Array.isArray(params.options) || params.options.length < 2 || params.options.length > 4) {
+        throw new Error(`escalation.options must have between 2 and 4 entries (got ${params.options?.length ?? 0})`);
+    }
+    const optionIds = new Set(params.options.map((o) => o.id));
+    if (optionIds.size !== params.options.length) {
+        throw new Error("escalation.options must have unique ids");
+    }
+    if (!optionIds.has(params.recommendation)) {
+        throw new Error(`escalation.recommendation "${params.recommendation}" is not one of the option ids: ${[...optionIds].join(", ")}`);
+    }
+    return {
+        version: 1,
+        taskId: params.taskId,
+        sliceId: params.sliceId,
+        milestoneId: params.milestoneId,
+        question: params.question,
+        options: params.options,
+        recommendation: params.recommendation,
+        recommendationRationale: params.recommendationRationale,
+        continueWithDefault: params.continueWithDefault,
+        createdAt: new Date().toISOString(),
+    };
+}
+/** Atomically write an escalation artifact and flip the appropriate DB flag. */
+export function writeEscalationArtifact(basePath, artifact) {
+    const path = escalationArtifactPath(basePath, artifact.milestoneId, artifact.sliceId, artifact.taskId);
+    if (!path) {
+        throw new Error(`escalation: cannot resolve tasks dir for ${artifact.milestoneId}/${artifact.sliceId} — run doctor`);
+    }
+    mkdirSync(join(path, ".."), { recursive: true });
+    atomicWriteSync(path, JSON.stringify(artifact, null, 2));
+    if (artifact.continueWithDefault) {
+        setTaskEscalationAwaitingReview(artifact.milestoneId, artifact.sliceId, artifact.taskId, path);
+    }
+    else {
+        setTaskEscalationPending(artifact.milestoneId, artifact.sliceId, artifact.taskId, path);
+    }
+    emitUokAuditEvent(basePath, buildAuditEnvelope({
+        traceId: `escalation:${artifact.milestoneId}:${artifact.sliceId}:${artifact.taskId}`,
+        category: "gate",
+        type: "escalation-manual-attention-created",
+        payload: {
+            milestoneId: artifact.milestoneId,
+            sliceId: artifact.sliceId,
+            taskId: artifact.taskId,
+            continueWithDefault: artifact.continueWithDefault,
+            optionCount: artifact.options.length,
+            recommendation: artifact.recommendation,
+        },
+    }));
+    return path;
+}
+/** Read an escalation artifact by path. Returns null when missing or malformed. */
+export function readEscalationArtifact(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const art = parsed;
+        // Full schema validation — invalid artifacts return null so downstream
+        // code (formatEscalationForDisplay, resolveEscalation, carry-forward)
+        // never crashes on malformed input.
+        if (art.version !== 1)
+            return null;
+        if (typeof art.taskId !== "string" || art.taskId.length === 0)
+            return null;
+        if (typeof art.sliceId !== "string" || art.sliceId.length === 0)
+            return null;
+        if (typeof art.milestoneId !== "string" || art.milestoneId.length === 0)
+            return null;
+        if (typeof art.question !== "string" || art.question.length === 0)
+            return null;
+        // Option array constraints — kept in sync with buildEscalationArtifact so
+        // a hand-edited artifact cannot be weaker than what the writer would emit.
+        if (!Array.isArray(art.options) || art.options.length < 2 || art.options.length > 4)
+            return null;
+        const optionIds = new Set();
+        for (const opt of art.options) {
+            if (!opt || typeof opt !== "object")
+                return null;
+            const o = opt;
+            if (typeof o.id !== "string" || o.id.length === 0)
+                return null;
+            if (typeof o.label !== "string")
+                return null;
+            if (typeof o.tradeoffs !== "string")
+                return null;
+            if (optionIds.has(o.id))
+                return null;
+            optionIds.add(o.id);
+        }
+        if (typeof art.recommendation !== "string")
+            return null;
+        // Recommendation must reference a real option id.
+        if (!art.options.some((o) => o.id === art.recommendation))
+            return null;
+        if (typeof art.continueWithDefault !== "boolean")
+            return null;
+        if (typeof art.createdAt !== "string")
+            return null;
+        return art;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Detection ────────────────────────────────────────────────────────────
+/**
+ * Returns the task id of the first task with an un-resolved pause-escalation
+ * (escalation_pending=1, not yet respondedAt). awaiting_review slices are NOT
+ * returned — they don't pause the loop.
+ */
+export function detectPendingEscalation(tasks, basePath) {
+    for (const t of tasks) {
+        if (t.escalation_pending !== 1)
+            continue;
+        if (!t.escalation_artifact_path)
+            continue;
+        const art = readEscalationArtifact(t.escalation_artifact_path);
+        if (art && !art.respondedAt)
+            return t.id;
+    }
+    return null;
+}
+/**
+ * Apply a user response to a pending escalation:
+ *  1) Update the artifact with respondedAt/userChoice/userRationale.
+ *  2) Clear the DB escalation flags.
+ *  3) For "reject-blocker": set blocker_discovered=1 + blocker_source='reject-escalation'.
+ *  4) Emit audit events.
+ *
+ * Note: this does NOT persist a decision via saveDecisionToDb — the caller
+ * (commands/handlers/escalate.ts) owns that step so it can fail gracefully
+ * and surface the decision id in the user-visible message.
+ */
+export function resolveEscalation(basePath, milestoneId, sliceId, taskId, choice, rationale) {
+    const task = getTask(milestoneId, sliceId, taskId);
+    if (!task || !task.escalation_artifact_path) {
+        return { status: "not-found", message: `No escalation artifact found for ${milestoneId}/${sliceId}/${taskId}.` };
+    }
+    const art = readEscalationArtifact(task.escalation_artifact_path);
+    if (!art) {
+        return { status: "not-found", message: `Escalation artifact at ${task.escalation_artifact_path} is missing or malformed.` };
+    }
+    if (art.respondedAt) {
+        return { status: "already-resolved", message: `Escalation for ${taskId} was already resolved at ${art.respondedAt}.` };
+    }
+    // Resolve `choice` into a concrete option.
+    let chosenOption;
+    if (choice === "accept") {
+        chosenOption = art.options.find((o) => o.id === art.recommendation);
+    }
+    else if (choice === "reject-blocker") {
+        // Handled below; no option selection.
+    }
+    else {
+        chosenOption = art.options.find((o) => o.id === choice);
+        if (!chosenOption) {
+            const valid = ["accept", "reject-blocker", ...art.options.map((o) => o.id)].join(", ");
+            return { status: "invalid-choice", message: `Unknown choice "${choice}". Valid choices: ${valid}.` };
+        }
+    }
+    const respondedAt = new Date().toISOString();
+    const updated = {
+        ...art,
+        respondedAt,
+        userChoice: choice,
+        userRationale: rationale,
+    };
+    atomicWriteSync(task.escalation_artifact_path, JSON.stringify(updated, null, 2));
+    clearTaskEscalationFlags(milestoneId, sliceId, taskId);
+    if (choice === "reject-blocker") {
+        setTaskBlockerSource(milestoneId, sliceId, taskId, "reject-escalation");
+        emitUokAuditEvent(basePath, buildAuditEnvelope({
+            traceId: `escalation:${milestoneId}:${sliceId}:${taskId}`,
+            category: "gate",
+            type: "escalation-rejected-to-blocker",
+            payload: { milestoneId, sliceId, taskId, rationale },
+        }));
+        return {
+            status: "rejected-to-blocker",
+            message: `Escalation rejected. Task ${taskId} now flagged as a blocker — next /gsd auto will replan slice ${sliceId}.`,
+            artifactPath: task.escalation_artifact_path,
+        };
+    }
+    emitUokAuditEvent(basePath, buildAuditEnvelope({
+        traceId: `escalation:${milestoneId}:${sliceId}:${taskId}`,
+        category: "gate",
+        type: "escalation-user-responded",
+        payload: {
+            milestoneId, sliceId, taskId,
+            chosenOptionId: chosenOption?.id,
+            rationale,
+        },
+    }));
+    return {
+        status: "resolved",
+        message: `Escalation resolved. Next task in ${sliceId} will receive the override.`,
+        artifactPath: task.escalation_artifact_path,
+        chosenOption,
+    };
+}
+// ─── Carry-forward lookup ─────────────────────────────────────────────────
+/**
+ * If this slice has a resolved-but-unapplied escalation override, atomically
+ * claim it (via DB UPDATE) and return the markdown block to prepend to the
+ * next task's prompt. Returns null when there's no unapplied override OR
+ * when another caller claimed it first (idempotent).
+ */
+export function claimOverrideForInjection(basePath, milestoneId, sliceId) {
+    const unapplied = findUnappliedEscalationOverride(milestoneId, sliceId);
+    if (!unapplied)
+        return null;
+    // Validate artifact BEFORE claiming so a missing/malformed file doesn't
+    // mark the DB row as applied (which would silently swallow the override
+    // forever). If the artifact is bad, return null without touching the row.
+    const art = readEscalationArtifact(unapplied.artifactPath);
+    if (!art) {
+        logWarning("tool", `escalation: artifact missing/malformed at ${unapplied.artifactPath} (task ${unapplied.taskId}); skipping without claim — operator should resolve or remove the row`);
+        return null;
+    }
+    if (!art.respondedAt || !art.userChoice)
+        return null;
+    const claimed = claimEscalationOverride(milestoneId, sliceId, unapplied.taskId);
+    if (!claimed)
+        return null; // lost the race
+    void basePath;
+    return {
+        injectionBlock: formatOverrideBlock(art),
+        sourceTaskId: unapplied.taskId,
+    };
+}
+function formatOverrideBlock(art) {
+    const isReject = art.userChoice === "reject-blocker";
+    const isAccept = art.userChoice === "accept";
+    const isOptionChoice = !!art.userChoice && !isReject && !isAccept;
+    // Include the stable option id in the block so downstream prompts and
+    // parsers have a machine-readable token, not just the display label.
+    const choiceLabel = isReject
+        ? "rejected — blocker path"
+        : isAccept
+            ? `accepted recommendation (${art.recommendation})`
+            : isOptionChoice
+                ? `${art.options.find((o) => o.id === art.userChoice)?.label ?? art.userChoice} (id: ${art.userChoice})`
+                : (art.userChoice ?? "unknown");
+    const tradeoffs = isOptionChoice
+        ? art.options.find((o) => o.id === art.userChoice)?.tradeoffs ?? ""
+        : "";
+    const rationale = art.userRationale ? `\n\n**User rationale:** ${art.userRationale}` : "";
+    return [
+        `## Escalation Override (from ${art.taskId})`,
+        "",
+        `During ${art.taskId} the executor escalated: **${art.question}**`,
+        "",
+        `The user's resolution: **${choiceLabel}**.${rationale}`,
+        tradeoffs ? `\n**Tradeoffs of this choice:** ${tradeoffs}` : "",
+        "",
+        "Apply this decision as a hard constraint for the current task. If it contradicts the task plan, surface the conflict in your summary rather than silently deviating.",
+    ].filter((line) => line !== undefined).join("\n");
+}
+// ─── Display ──────────────────────────────────────────────────────────────
+/** Human-readable summary of an artifact for `/gsd escalate show`. */
+export function formatEscalationForDisplay(art) {
+    const resolved = art.respondedAt
+        ? `\nResolved: ${art.respondedAt} — user chose "${art.userChoice}"${art.userRationale ? ` (rationale: ${art.userRationale})` : ""}`
+        : "\nStatus: awaiting user response";
+    const optionLines = art.options.map((o) => `  [${o.id}] ${o.label}${o.id === art.recommendation ? "  (recommended)" : ""}\n      ${o.tradeoffs}`).join("\n");
+    return [
+        `Task ${art.taskId} (slice ${art.sliceId})`,
+        `continueWithDefault: ${art.continueWithDefault}`,
+        `Question: ${art.question}`,
+        "",
+        "Options:",
+        optionLines,
+        "",
+        `Recommendation: ${art.recommendation} — ${art.recommendationRationale}`,
+        resolved,
+        "",
+        `Resolve with: /gsd escalate resolve ${art.taskId} <${art.options.map((o) => o.id).join("|")}|accept|reject-blocker> [rationale...]`,
+    ].join("\n");
+}
+/** List actionable (unresolved) escalations for `/gsd escalate list`. */
+export function listActionableEscalations(milestoneId) {
+    return listEscalationArtifacts(milestoneId, /* includeResolved */ false);
+}
+/** List every escalation (including resolved) for `/gsd escalate list --all`. */
+export function listAllEscalations(milestoneId) {
+    return listEscalationArtifacts(milestoneId, /* includeResolved */ true);
+}

package/dist/resources/extensions/gsd/forensics.js

@@ -451,7 +451,32 @@ function gatherActivityLogMeta(basePath, activeMilestone) {
         return null;
     }
 }
-// ─── Completed Keys Loader ────────────────────────────────────────────────────
+// ─── Completed Keys Helpers ───────────────────────────────────────────────────
+/**
+ * Parse a completed-unit key into { unitType, unitId }.
+ *
+ * Most unit types are a single segment ("execute-task", "complete-slice", …)
+ * so the key format is simply "unitType/unitId". Hook units are the exception:
+ * their type is compound ("hook/<hookName>"), making the key look like
+ * "hook/telegram-progress/M007/S01". Splitting naïvely on the first slash
+ * yields unitType="hook" which bypasses verifyExpectedArtifact()'s
+ * startsWith("hook/") guard and produces false-positive missing-artifact
+ * errors (#2826).
+ *
+ * Returns null for malformed keys (no slash, or hook/ with no second slash).
+ */
+export function splitCompletedKey(key) {
+    if (key.startsWith("hook/")) {
+        const secondSlash = key.indexOf("/", 5); // skip past "hook/"
+        if (secondSlash === -1)
+            return null; // malformed — "hook/" with no hook name
+        return { unitType: key.slice(0, secondSlash), unitId: key.slice(secondSlash + 1) };
+    }
+    const slashIdx = key.indexOf("/");
+    if (slashIdx === -1)
+        return null;
+    return { unitType: key.slice(0, slashIdx), unitId: key.slice(slashIdx + 1) };
+}
 function loadCompletedKeys(basePath) {
     const file = join(gsdRoot(basePath), "completed-units.json");
     try {
@@ -583,34 +608,6 @@ function detectTimeouts(traces, anomalies) {
         }
     }
 }
-/**
- * Parse a completed-unit key into its unitType and unitId.
- *
- * Hook units use a compound slash-delimited type ("hook/<hookName>"), so a
- * naive `key.indexOf("/")` would split "hook/telegram-progress/M007/S01" into
- * unitType="hook" (wrong) instead of "hook/telegram-progress".
- *
- * Returns `null` for malformed keys that cannot be split.
- */
-export function splitCompletedKey(key) {
-    if (key.startsWith("hook/")) {
-        // Hook unit types are two segments: "hook/<hookName>/<unitId...>"
-        const secondSlash = key.indexOf("/", 5); // skip past "hook/"
-        if (secondSlash === -1)
-            return null; // malformed — no unitId after hook name
-        return {
-            unitType: key.slice(0, secondSlash),
-            unitId: key.slice(secondSlash + 1),
-        };
-    }
-    const slashIdx = key.indexOf("/");
-    if (slashIdx === -1)
-        return null;
-    return {
-        unitType: key.slice(0, slashIdx),
-        unitId: key.slice(slashIdx + 1),
-    };
-}
 function detectMissingArtifacts(completedKeys, basePath, activeMilestone, anomalies) {
     // Also check the worktree path for artifacts — they may exist there but not at root
     const wtBasePath = activeMilestone ? getAutoWorktreePath(basePath, activeMilestone) : null;

package/dist/resources/extensions/gsd/git-service.js

@@ -15,7 +15,7 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { detectWorktreeName, } from "./worktree.js";
 import { SLICE_BRANCH_RE, QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.js";
-import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchExists, nativeHasChanges, nativeAddAllWithExclusions, nativeHasStagedChanges, nativeCommit, nativeRmCached, nativeUpdateRef, nativeResetSoft, nativeCommitSubject, } from "./native-git-bridge.js";
+import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchExists, nativeHasChanges, nativeAddAllWithExclusions, nativeHasStagedChanges, nativeCommit, nativeRmCached, nativeUpdateRef, nativeResetSoft, nativeCommitSubject, _resetHasChangesCache, } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
 import { getErrorMessage } from "./error-utils.js";
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -574,7 +574,6 @@ export class GitServiceImpl {
      * Run pre-merge verification check. Auto-detects test runner from project
      * files, or uses custom command from prefs.pre_merge_check.
      * Gated on prefs.pre_merge_check (false = skip, string = custom command).
-     * Stub: to be implemented in T03.
      */
     runPreMergeCheck() {
         if (this.prefs.pre_merge_check === false) {
@@ -641,6 +640,54 @@ export function createGitService(basePath) {
     const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
     return new GitServiceImpl(basePath, gitPrefs);
 }
+function buildTurnSnapshotLabel(unitType, unitId) {
+    const raw = `${unitType}/${unitId}`.trim();
+    if (!raw)
+        return "turn";
+    return raw
+        .replace(/[^a-zA-Z0-9._/-]/g, "-")
+        .replace(/\/{2,}/g, "/")
+        .replace(/-{2,}/g, "-")
+        .replace(/^[-/]+|[-/]+$/g, "") || "turn";
+}
+export function runTurnGitAction(args) {
+    try {
+        // Force fresh working-tree status per turn; nativeHasChanges caches briefly.
+        _resetHasChangesCache();
+        if (args.action === "status-only") {
+            return {
+                action: args.action,
+                status: "ok",
+                dirty: nativeHasChanges(args.basePath),
+            };
+        }
+        const git = createGitService(args.basePath);
+        if (args.action === "snapshot") {
+            const label = buildTurnSnapshotLabel(args.unitType, args.unitId);
+            git.createSnapshot(label);
+            return {
+                action: args.action,
+                status: "ok",
+                snapshotLabel: label,
+                dirty: nativeHasChanges(args.basePath),
+            };
+        }
+        const commitMessage = git.autoCommit(args.unitType, args.unitId, [], args.taskContext) ?? undefined;
+        return {
+            action: args.action,
+            status: "ok",
+            commitMessage,
+            dirty: nativeHasChanges(args.basePath),
+        };
+    }
+    catch (err) {
+        return {
+            action: args.action,
+            status: "failed",
+            error: getErrorMessage(err),
+        };
+    }
+}
 // ─── Commit Type Inference ─────────────────────────────────────────────────
 /**
  * Infer a conventional commit type from a title (and optional one-liner).

package/dist/resources/extensions/gsd/graph-context.js

@@ -0,0 +1,157 @@
+/**
+ * Graph-aware context injection for dispatch prompt builders.
+ *
+ * Reads the pre-built graph.json and returns a formatted context block
+ * for injection into prompts. Gracefully returns null when no graph exists
+ * or the query yields no results — callers must handle null.
+ */
+import { logWarning } from "./workflow-logger.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+let cachedGraphApi = null;
+let resolvedGraphApi = false;
+function readGraphFile(projectDir) {
+    try {
+        const graphPath = join(projectDir, ".gsd", "graphs", "graph.json");
+        const raw = readFileSync(graphPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const nodes = Array.isArray(parsed.nodes) ? parsed.nodes : [];
+        const edges = Array.isArray(parsed.edges) ? parsed.edges : [];
+        return { nodes, edges, builtAt: typeof parsed.builtAt === "string" ? parsed.builtAt : undefined };
+    }
+    catch {
+        return null;
+    }
+}
+async function fallbackGraphQuery(projectDir, term, budget = 3000) {
+    const graph = readGraphFile(projectDir);
+    if (!graph)
+        return { nodes: [], edges: [] };
+    const needle = term.trim().toLowerCase();
+    const matches = graph.nodes.filter((node) => {
+        const hay = [node.id, node.label, node.description].filter(Boolean).join(" ").toLowerCase();
+        return hay.includes(needle);
+    });
+    const maxNodes = Math.max(1, Math.floor(Math.max(1, budget) / 20));
+    const selectedIds = new Set(matches.slice(0, maxNodes).map((node) => node.id));
+    const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
+    // Pull one-hop neighbors so relation context survives even when the term
+    // matches only one side of an edge.
+    for (const edge of graph.edges) {
+        if (selectedIds.size >= maxNodes)
+            break;
+        const touchesSelection = selectedIds.has(edge.from) || selectedIds.has(edge.to);
+        if (!touchesSelection)
+            continue;
+        if (selectedIds.has(edge.from) && !selectedIds.has(edge.to) && nodeById.has(edge.to)) {
+            selectedIds.add(edge.to);
+        }
+        else if (selectedIds.has(edge.to) && !selectedIds.has(edge.from) && nodeById.has(edge.from)) {
+            selectedIds.add(edge.from);
+        }
+    }
+    const nodes = graph.nodes.filter((node) => selectedIds.has(node.id));
+    const remainingBudget = Math.max(0, budget - nodes.length * 20);
+    const maxEdges = Math.floor(remainingBudget / 10);
+    const edges = graph.edges
+        .filter((edge) => selectedIds.has(edge.from) && selectedIds.has(edge.to))
+        .slice(0, maxEdges);
+    return { nodes, edges };
+}
+async function fallbackGraphStatus(projectDir) {
+    const graph = readGraphFile(projectDir);
+    if (!graph)
+        return { exists: false, stale: false };
+    if (!graph.builtAt)
+        return { exists: true, stale: false };
+    const builtAtMs = Date.parse(graph.builtAt);
+    if (!Number.isFinite(builtAtMs))
+        return { exists: true, stale: false };
+    const ageHours = (Date.now() - builtAtMs) / (1000 * 60 * 60);
+    return { exists: true, stale: ageHours > 24, ageHours };
+}
+function isGraphApi(mod) {
+    if (!mod || typeof mod !== "object")
+        return false;
+    const candidate = mod;
+    return typeof candidate.graphQuery === "function" && typeof candidate.graphStatus === "function";
+}
+async function resolveGraphApi() {
+    if (resolvedGraphApi && cachedGraphApi)
+        return cachedGraphApi;
+    resolvedGraphApi = true;
+    try {
+        const imported = await import("@gsd-build/mcp-server");
+        if (isGraphApi(imported)) {
+            cachedGraphApi = imported;
+            return cachedGraphApi;
+        }
+        logWarning("prompt", "@gsd-build/mcp-server graph exports unavailable; using local graph fallback");
+    }
+    catch {
+        // Fall back to local reader implementation.
+    }
+    cachedGraphApi = {
+        graphQuery: fallbackGraphQuery,
+        graphStatus: fallbackGraphStatus,
+    };
+    return cachedGraphApi;
+}
+/**
+ * Query the knowledge graph for nodes related to the given term and format
+ * the result as an inlined context block.
+ *
+ * Returns null when:
+ * - @gsd-build/mcp-server fails to import
+ * - graph.json does not exist (graphQuery already handles this gracefully)
+ * - query returns zero nodes
+ *
+ * Annotates the block header when the graph is stale (> 24 hours old).
+ */
+export async function inlineGraphSubgraph(projectDir, term, opts) {
+    if (!term || !term.trim())
+        return null;
+    try {
+        const graphApi = await resolveGraphApi();
+        const result = await graphApi.graphQuery(projectDir, term, opts.budget);
+        if (result.nodes.length === 0)
+            return null;
+        // Check staleness for annotation
+        let staleAnnotation = "";
+        try {
+            const status = await graphApi.graphStatus(projectDir);
+            if (status.exists && status.stale && status.ageHours !== undefined) {
+                const hours = Math.round(status.ageHours);
+                staleAnnotation = `\n> ⚠ Graph last built ${hours}h ago — context may be outdated`;
+            }
+        }
+        catch {
+            // Non-fatal — skip annotation on error
+        }
+        // Format nodes as a compact list
+        const nodeLines = result.nodes.map((node) => {
+            const desc = node.description ? ` — ${node.description}` : "";
+            return `- **${node.label}** (\`${node.type}\`, ${node.confidence})${desc}`;
+        });
+        // Format edges as relations (only if present)
+        const edgeLines = result.edges.length > 0
+            ? result.edges.map((edge) => `- \`${edge.from}\` →[${edge.type}]→ \`${edge.to}\``)
+            : [];
+        const sections = [
+            `### Knowledge Graph Context (term: "${term}")`,
+            `Source: \`.gsd/graphs/graph.json\``,
+            staleAnnotation,
+            "",
+            `**Nodes (${result.nodes.length}):**`,
+            ...nodeLines,
+        ];
+        if (edgeLines.length > 0) {
+            sections.push("", `**Relations (${result.edges.length}):**`, ...edgeLines);
+        }
+        return sections.filter((l) => l !== undefined).join("\n");
+    }
+    catch (err) {
+        logWarning("prompt", `inlineGraphSubgraph failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

package/dist/resources/extensions/gsd/graph.js

@@ -129,6 +129,32 @@ export function markStepComplete(graph, stepId) {
             : s),
     };
 }
+/**
+ * Return a new graph with the specified step marked as "active".
+ * Immutable — does not mutate the input graph.
+ *
+ * @param graph — the current workflow graph
+ * @param stepId — ID of the step to mark active
+ * @returns New graph with the step's status set to "active"
+ * @throws Error if stepId is not found in the graph
+ */
+export function markStepActive(graph, stepId) {
+    const found = graph.steps.some((s) => s.id === stepId);
+    if (!found) {
+        throw new Error(`Step not found: ${stepId}`);
+    }
+    const startedAt = new Date().toISOString();
+    return {
+        ...graph,
+        steps: graph.steps.map((s) => s.id === stepId
+            ? {
+                ...s,
+                status: "active",
+                startedAt: s.startedAt ?? startedAt,
+            }
+            : s),
+    };
+}
 // ─── Iteration expansion ─────────────────────────────────────────────────
 /**
  * Expand an iterate step into concrete instances. Pure and deterministic —
@@ -221,5 +247,3 @@ export function initializeGraph(def) {
         },
     };
 }
-/** @deprecated Use initializeGraph instead. Kept for backward compatibility. */
-export { initializeGraph as graphFromDefinition };