gsd-pi 2.77.0-dev.c9c8932c6 → 2.77.0-dev.cfd69e714

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -11,6 +11,7 @@
 import { join } from "node:path";
 import { transaction, insertAssessment, deleteAssessmentByScope, getMilestoneSlices, } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
@@ -59,14 +60,18 @@ export async function handleValidateMilestone(params, basePath, opts) {
         return { error: `verdict must be one of: ${VALIDATION_VERDICTS.join(", ")}` };
     }
     // ── Resolve paths and render markdown ────────────────────────────────
+    // #4761: route through the canonical-root resolver so that when a live
+    // worktree exists for this milestone, validation reads/writes the
+    // worktree's artifacts instead of stale project-root state.
     const validationMd = renderValidationMarkdown(params);
+    const canonicalBase = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
     let validationPath;
-    const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+    const milestoneDir = resolveMilestonePath(canonicalBase, params.milestoneId);
     if (milestoneDir) {
         validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
     }
     else {
-        const gsdDir = join(basePath, ".gsd");
+        const gsdDir = join(canonicalBase, ".gsd");
         const manualDir = join(gsdDir, "milestones", params.milestoneId);
         validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
     }

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -0,0 +1,147 @@
+// GSD-2 — UnitContextComposer (#4782 phase 2).
+//
+// Reads a unit type's manifest and orchestrates artifact inlining through
+// a caller-provided resolver. Returns a joined context block suitable for
+// substitution into the unit's prompt template.
+//
+// Design rationale:
+//   - Pure dependency on the manifest module — no circular import with
+//     `auto-prompts.ts` where the per-artifact-key resolver lives.
+//   - Caller-supplied resolver means the composer can be unit-tested with
+//     trivial mocks; production wiring in `auto-prompts.ts` dispatches to
+//     the existing `inlineFile` / `inline*FromDb` helpers.
+//   - Null-returning resolvers are skipped silently: they model the
+//     "artifact is optional / missing / not applicable to this milestone"
+//     case. The composer never errors on a missing artifact.
+//
+// Scope: phase 2 pilot shipped `composeInlinedContext` for static-key
+// inlining. Phase 3.5 (#4924) adds the v2 surface — `composeUnitContext`
+// — which also handles excerpts, computed artifacts, and prepended blocks.
+// `composeInlinedContext` stays for backward compatibility with the
+// already-migrated simple builders.
+//
+// ─── Composer boundary invariant (#4924) ─────────────────────────────────
+//
+// The composer is allowed to:
+//   - order named sections per the manifest's declared sequence
+//   - resolve registered artifacts (static / computed / excerpt / on-demand)
+//   - apply typed policies (knowledge / memory / codebase-map / preferences)
+//
+// The composer must NOT grow:
+//   - arbitrary conditionals on unit state
+//   - loops over caller-supplied data
+//   - string templating beyond section composition (join + separator)
+//
+// Logic that needs those belongs in a typed computed-artifact builder
+// owned by the unit, not in the composer. Reviews must enforce this — it
+// is the difference between an orchestrator and a runaway DSL.
+import { resolveManifest, } from "./unit-context-manifest.js";
+/**
+ * Produce the inlined-context portion of a unit's system prompt by
+ * walking the manifest's `artifacts.inline` list in order and calling
+ * the provided resolver for each key.
+ *
+ * Returns an empty string when the unit type has no manifest registered,
+ * so callers can guard their wiring with a simple truthy check. Unknown
+ * unit types do not error — this mirrors `resolveManifest`'s contract.
+ *
+ * The separator between inlined blocks matches the in-tree convention
+ * (`\n\n---\n\n`) so composer output slots into existing prompt templates
+ * without visible diff.
+ */
+export async function composeInlinedContext(unitType, resolveArtifact) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return "";
+    const blocks = [];
+    for (const key of manifest.artifacts.inline) {
+        const body = await resolveArtifact(key);
+        if (body !== null && body.length > 0) {
+            blocks.push(body);
+        }
+    }
+    return blocks.join("\n\n---\n\n");
+}
+/**
+ * Convenience helper returning the manifest's declared budget so callers
+ * can telemetry a mismatch between actual prompt size and declared budget.
+ * Returns null for unknown unit types.
+ */
+export function manifestBudgetChars(unitType) {
+    const manifest = resolveManifest(unitType);
+    return manifest ? manifest.maxSystemPromptChars : null;
+}
+const SECTION_SEPARATOR = "\n\n---\n\n";
+/**
+ * Compose all manifest-declared context for a unit type using the v2
+ * surface. Walks `prepend` first (computed-only), then the `inline` list
+ * (static keys via `resolveArtifact`), then `excerpt` (via `resolveExcerpt`),
+ * then `artifacts.computed` (via the typed registry). Order within each
+ * section follows the manifest's declared sequence.
+ *
+ * Unknown unit types return empty strings for both sections — callers can
+ * fall back to existing imperative wiring without a special case.
+ *
+ * Resolver / registry omissions: if the manifest declares an entry but no
+ * resolver / registry entry is provided, the composer skips it silently.
+ * This matches the v1 contract where a null body is a no-op, and lets
+ * partial migrations land without forcing every consumer to register
+ * every artifact class up-front.
+ */
+export async function composeUnitContext(unitType, opts) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return { prepend: "", inline: "" };
+    // Single-source `unitType`: the manifest is resolved against the
+    // function arg, but computed builders read it from `base.unitType`.
+    // If those ever diverge (caller passes one type to composeUnitContext
+    // but a different one in opts.base), the composer would silently
+    // mix one unit's manifest with another unit's computed context.
+    // Normalize here so the composer dispatches a consistent identity
+    // through to every builder.
+    const normalizedOpts = {
+        ...opts,
+        base: { ...opts.base, unitType },
+    };
+    const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
+    const inlineBlocks = [];
+    for (const key of manifest.artifacts.inline) {
+        if (!normalizedOpts.resolveArtifact)
+            break;
+        const body = await normalizedOpts.resolveArtifact(key);
+        if (body && body.length > 0)
+            inlineBlocks.push(body);
+    }
+    for (const key of manifest.artifacts.excerpt) {
+        if (!normalizedOpts.resolveExcerpt)
+            break;
+        const body = await normalizedOpts.resolveExcerpt(key);
+        if (body && body.length > 0)
+            inlineBlocks.push(body);
+    }
+    inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+    return {
+        prepend: prependBlocks.join(SECTION_SEPARATOR),
+        inline: inlineBlocks.join(SECTION_SEPARATOR),
+    };
+}
+/**
+ * Invoke the registered builder for each declared computed id, in order.
+ * Missing registry entries (manifest declares the id but caller didn't
+ * register it) are skipped silently — see composeUnitContext rationale.
+ */
+async function runComputed(ids, opts) {
+    if (ids.length === 0 || !opts.computed)
+        return [];
+    const registry = opts.computed;
+    const out = [];
+    for (const id of ids) {
+        const entry = registry[id];
+        if (!entry)
+            continue;
+        const body = await entry.build(entry.inputs, opts.base);
+        if (body && body.length > 0)
+            out.push(body);
+    }
+    return out;
+}

package/dist/resources/extensions/gsd/unit-context-manifest.js

@@ -0,0 +1,370 @@
+// GSD-2 — UnitContextManifest (#4782 phase 1).
+//
+// Declarative description of what context each auto-mode unit type needs
+// in its system prompt. Establishes the contract that later phases will
+// use to drive a single composeSystemPromptForUnit() — replacing the
+// per-unit-type branching currently spread across `auto-prompts.ts`.
+//
+// **Phase 1 ships the type + the data + a CI coverage guard.** It adds
+// zero wiring — no caller reads a manifest yet. Every unit type gets a
+// manifest that describes today's behavior as faithfully as possible, so
+// when the composer lands in phase 2 the migration can proceed manifest-
+// by-manifest without behavior change.
+//
+// Phased rollout tracking:
+//   - Phase 1 (this PR): schema + manifests + coverage test.
+//   - Phase 2: add composeSystemPromptForUnit(); migrate one low-risk
+//     unit type (e.g. reassess-roadmap) as the pilot.
+//   - Phase 3: migrate remaining unit types, tighten manifests per
+//     empirical usage, introduce skipWhen predicates absorbing the
+//     reassess opt-in gate from #4778.
+//   - Phase 4: introduce pipeline variants as declared sequences,
+//     absorbing the scope-classifier gates from #4781.
+//
+// Naming:
+//   - Artifact keys are STABLE strings (not paths). Path resolution is
+//     the composer's job; manifests describe intent, not disk layout.
+//   - Char budgets are nominal — blown budgets log a telemetry event,
+//     they do not truncate or error (the composer decides fallback).
+// ─── Artifact registry ────────────────────────────────────────────────────
+/**
+ * Stable identifiers for every artifact class a unit might inline, excerpt,
+ * or reference on-demand. Adding a new artifact class requires (a) a key
+ * here, (b) path/body resolution in the composer, and (c) updates to any
+ * manifest that should surface it.
+ */
+export const ARTIFACT_KEYS = [
+    // Milestone-scoped
+    "roadmap",
+    "milestone-context",
+    "milestone-summary",
+    "milestone-validation",
+    "milestone-research",
+    "milestone-plan",
+    // Slice-scoped
+    "slice-context",
+    "slice-research",
+    "slice-plan",
+    "slice-summary",
+    "slice-uat",
+    "slice-assessment",
+    // Task-scoped
+    "task-plan",
+    "task-summary",
+    "prior-task-summaries",
+    "dependency-summaries",
+    // Project-scoped
+    "requirements",
+    "decisions",
+    "project",
+    "templates",
+];
+// ─── Manifests ────────────────────────────────────────────────────────────
+// Phase 1 policy: every manifest encodes today's behavior. Skills = "all"
+// unless the unit type was already narrowed via the existing skill-manifest
+// resolver (#4779). Memory/knowledge policies reflect the defaults in
+// `bootstrap/system-context.ts`. Artifact classifications follow what
+// `auto-prompts.ts` inlines today for each unit type.
+const COMMON_BUDGET_LARGE = 1_500_000; // ~400K tokens
+const COMMON_BUDGET_MEDIUM = 750_000; // ~200K tokens
+const COMMON_BUDGET_SMALL = 250_000; // ~65K tokens
+// ─── Tool policy constants (#4934) ────────────────────────────────────────
+// Reused across manifests so per-unit assignment stays declarative and the
+// allowed-path set for the docs policy lives in one reviewable place.
+const TOOLS_ALL = { mode: "all" };
+const TOOLS_PLANNING = { mode: "planning" };
+const TOOLS_DOCS = {
+    mode: "docs",
+    // Globs are resolved relative to project basePath. The set is intentionally
+    // narrow: top-level docs/, README, CHANGELOG, and any markdown at the
+    // project root. Projects with non-standard layouts (e.g. mintlify-docs/)
+    // will need this list extended in a follow-up; landed conservative now,
+    // expand on demand.
+    allowedPathGlobs: [
+        "docs/**",
+        "README.md",
+        "README.*.md",
+        "CHANGELOG.md",
+        "*.md",
+    ],
+};
+/**
+ * Canonical unit types handled by auto-mode dispatch. The coverage test
+ * enumerates these against `UNIT_MANIFESTS` to catch manifest drift when
+ * a new unit type lands.
+ */
+export const KNOWN_UNIT_TYPES = [
+    "research-milestone",
+    "plan-milestone",
+    "discuss-milestone",
+    "validate-milestone",
+    "complete-milestone",
+    "research-slice",
+    "plan-slice",
+    "refine-slice",
+    "replan-slice",
+    "complete-slice",
+    "reassess-roadmap",
+    "execute-task",
+    "reactive-execute",
+    "run-uat",
+    "gate-evaluate",
+    "rewrite-docs",
+];
+export const UNIT_MANIFESTS = {
+    // ─── Milestone-scoped ────────────────────────────────────────────────
+    "research-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            // Phase 3 migration (#4782): matches today's actual
+            // buildResearchMilestonePrompt inlining order.
+            inline: ["milestone-context", "project", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "plan-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "milestone-research", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "discuss-milestone": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "milestone-context", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "validate-milestone": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "complete-milestone": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            // #4780 landed slice-summary as excerpt for this unit; phase 2 of
+            // the architecture will read this manifest as the source of truth
+            // and retire the special-case wiring in auto-prompts.ts.
+            inline: ["roadmap", "milestone-context", "requirements", "decisions", "project", "templates"],
+            excerpt: ["slice-summary"],
+            onDemand: ["slice-summary"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // ─── Slice-scoped ────────────────────────────────────────────────────
+    "research-slice": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["roadmap", "milestone-research", "dependency-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "plan-slice": {
+        skills: { mode: "all" },
+        knowledge: "full",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["roadmap", "slice-research", "dependency-summaries", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "refine-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["slice-plan", "slice-research", "dependency-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "replan-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["slice-plan", "slice-research", "dependency-summaries", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    "complete-slice": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: false,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            // Phase 3 migration (#4782): matches today's actual
+            // buildCompleteSlicePrompt inlining order. Overrides prepend +
+            // knowledge splice stay in the builder imperatively (see RFC
+            // #4924 — computed/prepend blocks are phase-4 composer work).
+            inline: ["roadmap", "slice-context", "slice-plan", "requirements", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "reassess-roadmap": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "none",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            // Phase 2 pilot (#4782): manifest now matches today's actual
+            // buildReassessRoadmapPrompt behavior for equivalence. Phase 3
+            // will tighten this list once the composer reports real telemetry.
+            inline: ["roadmap", "slice-context", "slice-summary", "project", "requirements", "decisions"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+    // ─── Task-scoped ─────────────────────────────────────────────────────
+    "execute-task": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_ALL,
+        artifacts: {
+            inline: ["task-plan", "slice-plan", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: ["slice-research"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    "reactive-execute": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_ALL,
+        artifacts: {
+            inline: ["slice-plan", "prior-task-summaries", "templates"],
+            excerpt: [],
+            onDemand: ["slice-research"],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_LARGE,
+    },
+    // ─── Ancillary units ─────────────────────────────────────────────────
+    "run-uat": {
+        skills: { mode: "all" },
+        knowledge: "critical-only",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            // Phase 3 migration (#4782): manifest matches today's actual
+            // buildRunUatPrompt inlining. Prior phase-1 entry listed
+            // `slice-plan` aspirationally — the real builder inlines the UAT
+            // file, the slice SUMMARY (optional), and the project row.
+            inline: ["slice-uat", "slice-summary", "project"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    "gate-evaluate": {
+        skills: { mode: "all" },
+        knowledge: "critical-only",
+        memory: "critical-only",
+        codebaseMap: false,
+        preferences: "active-only",
+        tools: TOOLS_PLANNING,
+        artifacts: {
+            inline: ["slice-plan", "prior-task-summaries"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_SMALL,
+    },
+    "rewrite-docs": {
+        skills: { mode: "all" },
+        knowledge: "scoped",
+        memory: "prompt-relevant",
+        codebaseMap: true,
+        preferences: "active-only",
+        tools: TOOLS_DOCS,
+        artifacts: {
+            inline: ["project", "requirements", "decisions", "templates"],
+            excerpt: [],
+            onDemand: [],
+        },
+        maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+    },
+};
+// ─── Lookup helper ────────────────────────────────────────────────────────
+/**
+ * Return the manifest for a unit type, or null when the type is unknown.
+ *
+ * Callers MUST treat null as "fall through to today's default behavior"
+ * rather than erroring — unknown unit types may be experimental and
+ * should not crash the composer.
+ */
+export function resolveManifest(unitType) {
+    return UNIT_MANIFESTS[unitType] ?? null;
+}

package/dist/resources/extensions/gsd/uok/audit.js

@@ -1,6 +1,8 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { isStaleWrite } from "../auto/turn-epoch.js";
+import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 function auditLogPath(basePath) {
@@ -22,9 +24,23 @@ export function buildAuditEnvelope(args) {
     };
 }
 export function emitUokAuditEvent(basePath, event) {
+    // Drop writes from a turn superseded by timeout recovery / cancellation.
+    if (isStaleWrite("uok-audit"))
+        return;
     try {
         ensureAuditDir(basePath);
-        appendFileSync(auditLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+        const path = auditLogPath(basePath);
+        // proper-lockfile requires the target file to exist before locking.
+        // Touch it via open(O_APPEND|O_CREAT) so the first writer wins the race
+        // atomically at the kernel level.
+        if (!existsSync(path))
+            closeSync(openSync(path, "a"));
+        // onLocked: "skip" — audit writes are best-effort; under heavy contention
+        // POSIX O_APPEND atomicity still protects small line writes, so skipping
+        // the lock rather than stalling orchestration is the correct tradeoff.
+        withFileLockSync(path, () => {
+            appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+        }, { onLocked: "skip" });
     }
     catch {
         // Best-effort: audit writes must never break orchestration.

package/dist/resources/extensions/gsd/uok/dispatch-envelope.js

@@ -0,0 +1,33 @@
+export function buildDispatchEnvelope(input) {
+    return {
+        action: input.action,
+        nodeKind: input.node?.kind,
+        unitType: input.unitType,
+        unitId: input.unitId,
+        prompt: input.prompt,
+        reason: {
+            reasonCode: input.reasonCode,
+            summary: input.summary,
+            evidence: input.evidence,
+            blockedBy: input.blockedBy,
+        },
+        gateVerdict: input.gateVerdict,
+        constraints: input.node
+            ? {
+                reads: input.node.reads,
+                writes: input.node.writes,
+                dependsOn: input.node.dependsOn,
+            }
+            : undefined,
+        trace: input.trace,
+    };
+}
+export function explainDispatch(envelope) {
+    const subject = envelope.unitType && envelope.unitId
+        ? `${envelope.unitType} ${envelope.unitId}`
+        : envelope.nodeKind ?? envelope.action;
+    const blocked = envelope.reason.blockedBy && envelope.reason.blockedBy.length > 0
+        ? ` Blocked by: ${envelope.reason.blockedBy.map((b) => `${b.kind}:${b.id}`).join(", ")}.`
+        : "";
+    return `[${envelope.reason.reasonCode}] ${subject}: ${envelope.reason.summary}.${blocked}`;
+}

package/dist/resources/extensions/gsd/uok/execution-graph.js

@@ -68,6 +68,16 @@ export function buildSidecarQueueNodes(queue) {
         metadata: { index },
     }));
 }
+export function buildExecutionGraphSnapshot(nodes, phase) {
+    const sorted = topologicalSort(nodes);
+    return {
+        capturedAt: new Date().toISOString(),
+        phase,
+        nodes: sorted,
+        order: sorted.map((node) => node.id),
+        conflicts: detectFileConflicts(nodes),
+    };
+}
 export async function scheduleSidecarQueue(queue) {
     if (queue.length <= 1)
         return [...queue];