@opengsd/gsd-pi 1.2.0-dev.84c56d87 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -19,9 +19,10 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -48,13 +49,21 @@ import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
-import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import {
   prepareUatRun,
   saveUatAttemptArtifact,
   type UatResultSaveParams,
 } from "../uat-run.js";
+import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
+import {
+  claimMilestoneLease,
+  releaseMilestoneLease,
+  getMilestoneLease,
+  refreshMilestoneLease,
+  milestoneLeaseTtlSeconds,
+} from "../db/milestone-leases.js";
 export type {
   UatCheckResultInput,
   UatEvidenceRef,
@@ -105,6 +114,24 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   };
 }
 
+function milestoneLeaseConflictResult(
+  milestoneId: string,
+  byWorker: string,
+  expiresAt: string,
+): ToolExecutionResult {
+  return {
+    content: [{ type: "text", text: `Milestone ${milestoneId} is currently leased by ${byWorker}. Retry after ${expiresAt}.` }],
+    details: {
+      operation: "plan_milestone",
+      error: "milestone_lease_conflict",
+      milestoneId,
+      byWorker,
+      expiresAt,
+    },
+    isError: true,
+  };
+}
+
 export interface SummarySaveParams {
   milestone_id?: string;
   slice_id?: string;
@@ -1244,7 +1271,48 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  let workerId: string | null = null;
+  let acquiredToken: number | null = null;
+  let leaseRefreshTimer: ReturnType<typeof setInterval> | undefined;
   try {
+    // Re-read at the gate so a peer-created milestone is not treated as fresh.
+    const milestoneExists = getMilestone(params.milestoneId) !== null;
+    if (milestoneExists) {
+      const heldLease = getMilestoneLease(params.milestoneId);
+      if (heldLease?.status === "held" && Date.parse(heldLease.expires_at) > Date.now()) {
+        const holder = getAutoWorker(heldLease.worker_id);
+        // Let the one-shot claim path recover stale same-process worker rows.
+        const projectRoot = normalizeRealPath(basePath);
+        const isOurAutoLease = isAutoActive() && heldLease.worker_id === autoSession.workerId;
+        const holderIsOneShotReentrantPeer = !isAutoActive()
+          && !!holder
+          && holder.host === hostname()
+          && holder.pid === process.pid
+          && holder.project_root_realpath === projectRoot;
+        if (holder?.status === "active" && !isOurAutoLease && !holderIsOneShotReentrantPeer) {
+          return milestoneLeaseConflictResult(params.milestoneId, heldLease.worker_id, heldLease.expires_at);
+        }
+      }
+    }
+
+    // Fresh creation cannot claim a lease because the FK row does not exist.
+    // In-process auto already owns its lease; re-claiming would bump its token.
+    if (!isAutoActive() && milestoneExists) {
+      workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(basePath) });
+      const lease = claimMilestoneLease(workerId, params.milestoneId);
+      if (!lease.ok) {
+        return milestoneLeaseConflictResult(params.milestoneId, lease.byWorker, lease.expiresAt);
+      }
+      acquiredToken = lease.token;
+
+      const leaseRefreshMs = (milestoneLeaseTtlSeconds() / 2) * 1000;
+      leaseRefreshTimer = setInterval(() => {
+        if (acquiredToken !== null && workerId !== null) {
+          refreshMilestoneLease(workerId, params.milestoneId, acquiredToken);
+        }
+      }, leaseRefreshMs);
+    }
+
     const result = await handlePlanMilestone(params, basePath);
     if ("error" in result) {
       return {
@@ -1270,6 +1338,17 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  finally {
+    if (leaseRefreshTimer !== undefined) {
+      clearInterval(leaseRefreshTimer);
+    }
+    if (workerId !== null && acquiredToken !== null) {
+      releaseMilestoneLease(workerId, params.milestoneId, acquiredToken);
+    }
+    if (workerId !== null) {
+      markWorkerStopping(workerId);
+    }
+  }
 }
 
 export async function executePlanSlice(

package/src/resources/extensions/gsd/uat-policy.ts

@@ -2,7 +2,7 @@
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
 
 import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
-import { extractUatType } from "./files.js";
+import { extractUatType, UAT_TYPE_KEYWORDS } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
 import { parseMcpToolName } from "./mcp-tool-name.js";
@@ -28,19 +28,14 @@ export interface UatModePolicy {
 
 export interface UatContentPolicy {
   declaredType: UatType;
+  /** False when no parseable `UAT mode:` declaration exists and declaredType defaulted to artifact-driven. */
+  modeDeclared: boolean;
   effectiveType: UatType;
   browserRequired: boolean;
   shouldDispatchByDefault: boolean;
 }
 
-export const UAT_TYPES: readonly UatType[] = [
-  "artifact-driven",
-  "browser-executable",
-  "runtime-executable",
-  "live-runtime",
-  "mixed",
-  "human-experience",
-] as const;
+export const UAT_TYPES: readonly UatType[] = UAT_TYPE_KEYWORDS;
 
 export const UAT_MODE_POLICIES: Readonly<Record<UatType, UatModePolicy>> = {
   "artifact-driven": {
@@ -89,26 +84,76 @@ export function getDeclaredUatType(content: string): UatType {
   return extractUatType(content) ?? "artifact-driven";
 }
 
-export function classifyUatContent(content: string): UatContentPolicy {
-  const declaredType = getDeclaredUatType(content);
-  const browserRequired = hasBrowserRequiredText(content);
-  const effectiveType = declaredType === "artifact-driven" && browserRequired
+/** Self-contained browser UAT harnesses that manage server lifecycle internally. */
+const SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE =
+  /\b(?:npm run test:uat|node\s+(?:--check\s+\S+\s+&&\s+)*tests\/browser\/search-uat\.mjs|npx playwright test(?:\s+\S+)?)\b/i;
+
+export function hasSelfContainedRuntimeUatCommand(content: string): boolean {
+  return SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE.test(content);
+}
+
+function resolveEffectiveUatTypeFromPolicy(
+  declaredType: UatType,
+  browserRequired: boolean,
+  content: string,
+): UatType {
+  let effectiveType = declaredType === "artifact-driven" && browserRequired
     ? "browser-executable"
     : declaredType;
 
+  // M006/S01 regression: specs often declare browser-executable with localhost
+  // preconditions while the Evidence section names a runtime harness such as
+  // `npm run test:uat`. Interactive browser_* checks then race a fixed port
+  // against the script's own ephemeral server — run the harness instead.
+  if (
+    effectiveType === "browser-executable" &&
+    hasSelfContainedRuntimeUatCommand(content)
+  ) {
+    effectiveType = "runtime-executable";
+  }
+
+  return effectiveType;
+}
+
+export function classifyUatContent(content: string): UatContentPolicy {
+  return classifyUatContentForRun(content);
+}
+
+/**
+ * Classify UAT mode for run-uat dispatch. Supplemental context (slice summary,
+ * verification excerpts) can name a self-contained harness even when the UAT
+ * file only documents a separate server command such as `npm run test:server`.
+ */
+export function classifyUatContentForRun(content: string, supplementalContext = ""): UatContentPolicy {
+  const parsedType = extractUatType(content);
+  const declaredType = parsedType ?? "artifact-driven";
+  const browserRequired = hasBrowserRequiredText(content);
+  const combinedForHarness = supplementalContext.trim()
+    ? `${content}\n\n${supplementalContext}`
+    : content;
+  const effectiveType = resolveEffectiveUatTypeFromPolicy(
+    declaredType,
+    browserRequired,
+    combinedForHarness,
+  );
+
   return {
     declaredType,
+    modeDeclared: parsedType !== undefined,
     effectiveType,
     browserRequired,
     shouldDispatchByDefault: effectiveType !== "artifact-driven" || browserRequired,
   };
 }
 
-export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
-  const policy = classifyUatContent(content);
+export function escalatesArtifactUatToBrowser(policy: UatContentPolicy): boolean {
   return policy.declaredType === "artifact-driven" && policy.browserRequired;
 }
 
+export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
+  return escalatesArtifactUatToBrowser(classifyUatContent(content));
+}
+
 export function resolveEffectiveUatType(content: string): UatType {
   return classifyUatContent(content).effectiveType;
 }

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -43,8 +43,10 @@ import {
   type ComputedArtifactId,
   type ComputedArtifactRegistry,
   type ContextModePolicy,
+  type ToolsPolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 import type { UnitPromptContextContract } from "./tool-contract.js";
 
 /**
@@ -171,6 +173,103 @@ export function composeContextModeInstructions(
   ].join("\n");
 }
 
+// ─── Tool surface hardening ───────────────────────────────────────────────
+//
+// Upfront guidance for units whose runtime tool surface is narrower than the
+// default Claude/native set. Prevents wasted turns on tools that are blocked
+// by the write gate or Claude Code SDK allowlists (run-uat gsd_exec/Bash).
+
+export interface ComposeToolSurfaceInstructionOptions {
+  readonly renderMode: ContextModeRenderMode;
+}
+
+const TOOL_SURFACE_GUIDANCE_BY_UNIT: Record<string, string> = {
+  "run-uat":
+    "Do not call `gsd_exec`, `Bash`, `Write`, or `Edit` — they are unavailable in this unit. Run every automated check through `gsd_uat_exec` with the appropriate `intent`. For browser UAT modes, use `browser_*` tools when presented; if browser automation fails, record the failure honestly and use `gsd_uat_exec` for the best objective substitute.",
+  "complete-slice":
+    "Run slice-level verification through `gsd_exec` (or MCP-scoped `mcp__…__gsd_exec`), not direct `bash`. Capture learnings through `gsd_capture_thought` (or MCP-scoped `mcp__…__gsd_capture_thought`), not bare `capture_thought`, when workflow MCP tools are presented. Do not call `gsd_uat_result_save` — run-uat owns persisted UAT assessment. On verification failure, do not edit user source files in this unit.",
+  "gate-evaluate":
+    "Dispatch only **tester** subagents via `subagent`. Persist each gate with `gsd_save_gate_result`. Do not use `ToolSearch` — it is not available.",
+  "reactive-execute":
+    "Dispatch only **worker** subagents via `subagent`. Do not call `gsd_task_complete` from this parent batch — each worker owns its task completion. If a failed task left no summary, call `gsd_summary_save` with `blocker_discovered: true`.",
+  "execute-task":
+    "Complete only this task via `gsd_task_complete`. Do not call `gsd_slice_complete`, `gsd_validate_milestone`, or `gsd_complete_milestone` — the orchestrator owns phase transitions.",
+  "validate-milestone":
+    "Dispatch reviewer subagents in parallel, then persist the verdict via `gsd_validate_milestone`. Do not query `.gsd/gsd.db` directly — use `gsd_milestone_status` and inlined context.",
+  "complete-milestone":
+    "Persist completion only through `gsd_complete_milestone` after verification passes. Do not query `.gsd/gsd.db` directly. Do not write `.gsd/PROJECT.md` or `.gsd/REQUIREMENTS.md` by hand — use `gsd_summary_save` and `gsd_requirement_update`.",
+  "replan-slice":
+    "Persist replans through `gsd_replan_slice` only. Do not edit `PLAN.md` or task plans directly.",
+  "plan-slice":
+    "Persist planning through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner** for reconnaissance — not implementation agents. Do not edit user source files outside `.gsd/**`.",
+  "refine-slice":
+    "Persist refinements through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner**. Do not edit user source files outside `.gsd/**`.",
+  "plan-milestone":
+    "Persist milestone planning through `gsd_plan_milestone` / `gsd_plan_slice`. Do not edit user source files outside `.gsd/**`.",
+  "research-slice":
+    "Dispatch subagents only to **scout** or **planner** for reconnaissance. Do not edit user source files outside `.gsd/**`.",
+};
+
+function guidanceForToolsPolicy(policy: ToolsPolicy): string | null {
+  switch (policy.mode) {
+    case "planning":
+      return "Writes are restricted to `.gsd/**` under the working directory — do not edit user source files. `bash` is limited to read-only investigation commands. Do not dispatch subagents. For human elicitation, use workflow MCP `ask_user_questions` when available — not native `AskUserQuestion`.";
+    case "planning-dispatch": {
+      const agents = policy.allowedSubagents.map((agent) => `**${agent}**`).join(", ");
+      return `Writes are restricted to \`.gsd/**\`. Dispatch subagents only to: ${agents}. Do not edit user source files.`;
+    }
+    case "docs":
+      return "Writes are restricted to `.gsd/**` and project documentation paths (`docs/`, `README*`, `CHANGELOG.md`, root `*.md`). Do not edit application source.";
+    case "verification": {
+      const subagentLine = policy.allowedSubagents?.length
+        ? ` Dispatch subagents only to: ${policy.allowedSubagents.map((agent) => `**${agent}**`).join(", ")}.`
+        : " Do not dispatch subagents.";
+      return `\`bash\` is limited to build/test verification commands. Writes restricted to \`.gsd/**\`.${subagentLine}`;
+    }
+    default:
+      return null;
+  }
+}
+
+function formatForbiddenWorkflowToolsLine(
+  unitType: string,
+  unitGuidance: string | undefined,
+): string | null {
+  const forbidden = getUnitToolSurfaceContract(unitType)?.forbiddenGsdTools;
+  if (!forbidden) return null;
+  const names = Object.keys(forbidden).filter((name) => !unitGuidance?.includes(`\`${name}\``));
+  if (names.length === 0) return null;
+  return `Do not call ${names.map((name) => `\`${name}\``).join(", ")} in this unit.`;
+}
+
+/**
+ * Render upfront tool-surface guidance for a unit type. Unknown units and
+ * unrestricted (`tools.mode: "all"`) units omit the block unless they have
+ * unit-specific closeout guidance registered above.
+ */
+export function composeToolSurfaceInstructions(
+  unitType: string,
+  opts: ComposeToolSurfaceInstructionOptions,
+): string {
+  const manifest = resolveManifest(unitType);
+  if (!manifest) return "";
+
+  const unitGuidance = TOOL_SURFACE_GUIDANCE_BY_UNIT[unitType];
+  const policyGuidance = unitGuidance ? null : guidanceForToolsPolicy(manifest.tools);
+  const forbiddenLine = formatForbiddenWorkflowToolsLine(unitType, unitGuidance);
+  const parts = [unitGuidance, policyGuidance, forbiddenLine].filter(
+    (part): part is string => typeof part === "string" && part.length > 0,
+  );
+  if (parts.length === 0) return "";
+
+  const body = parts.join(" ");
+  if (opts.renderMode === "nested") {
+    return `Tool surface: ${body}`;
+  }
+
+  return ["## Tool Surface", "", body].join("\n");
+}
+
 // ─── v2 surface (#4924) ───────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/unit-registry.ts

@@ -220,15 +220,19 @@ export const UNIT_REGISTRY = {
     phaseChain: ["completion"],
     toolContract: {
       allowedGsdTools: [
+        "gsd_exec",
         "gsd_slice_complete",
         "gsd_task_reopen",
         "gsd_replan_slice",
         "gsd_decision_save",
+        "gsd_capture_thought",
         "gsd_requirement_update",
         "gsd_summary_save",
         "subagent",
       ],
       requiredWorkflowTools: [
+        "gsd_exec",
+        "gsd_capture_thought",
         "gsd_slice_complete",
         "gsd_task_reopen",
         "gsd_replan_slice",
@@ -254,8 +258,21 @@ export const UNIT_REGISTRY = {
     scopeClass: "execute-task",
     phaseChain: ["execution"],
     toolContract: {
-      allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-      requiredWorkflowTools: ["gsd_task_complete"],
+      allowedGsdTools: [
+        "gsd_task_complete",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+        "gsd_capture_thought",
+        "gsd_decision_save",
+      ],
+      requiredWorkflowTools: [
+        "gsd_task_complete",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+        "gsd_capture_thought",
+      ],
     },
   },
   "execute-task-simple": {
@@ -263,8 +280,21 @@ export const UNIT_REGISTRY = {
     scopeClass: "execute-task",
     phaseChain: ["execution_simple", "execution"],
     toolContract: {
-      allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-      requiredWorkflowTools: ["gsd_task_complete"],
+      allowedGsdTools: [
+        "gsd_task_complete",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+        "gsd_capture_thought",
+        "gsd_decision_save",
+      ],
+      requiredWorkflowTools: [
+        "gsd_task_complete",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+        "gsd_capture_thought",
+      ],
     },
   },
   "reactive-execute": {

package/src/resources/extensions/gsd/verdict-parser.ts

@@ -137,7 +137,7 @@ export function isValidMilestoneVerdict(verdict: string): verdict is ValidationV
  * Extract the UAT type from content, defaulting to `"artifact-driven"`.
  *
  * The `"artifact-driven"` fallback is the original default used throughout
- * the codebase when a UAT file lacks an explicit `## UAT Type` section.
+ * the codebase when a UAT file has no parseable UAT mode declaration.
  */
 export function getUatType(content: string): UatType {
   return getDeclaredUatType(content);

package/src/resources/extensions/gsd/verification-verdict.ts

@@ -15,6 +15,9 @@ export interface VerificationVerdict {
   failureContext: string;
 }
 
+export const NO_HOST_CHECKS_FAILURE_CONTEXT =
+  "No runnable host-owned verification command was discovered. Add project verification_commands in .gsd/PREFERENCES.md or a runnable task-plan Verify command, then resume with /gsd next.";
+
 export function decideVerificationVerdict(
   unitType: string,
   result: VerificationGateResult,
@@ -33,8 +36,7 @@ export function decideVerificationVerdict(
       passed: false,
       reason: "no-host-checks",
       retryable: false,
-      failureContext:
-        "No runnable host-owned verification command was discovered. Add project verification_commands or a runnable task-plan Verify command before completing this execute-task.",
+      failureContext: NO_HOST_CHECKS_FAILURE_CONTEXT,
     };
   }
 

package/src/resources/extensions/gsd/workflow-event-ledger.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { normalizeWorkflowEventCommand } from "./workflow-event-vocabulary.js";
+import type { WorkflowEvent } from "./workflow-events.js";
+
+export const WORKFLOW_EVENT_LOG_FILENAME = "event-log.jsonl";
+
+export interface WorkflowEventLedgerLocation {
+  projectRoot: string;
+  workRoot: string;
+  projectGsd: string;
+  worktreeGsd: string | null;
+  projectLogPath: string;
+  worktreeLogPath: string | null;
+  isWorktree: boolean;
+}
+
+export type WorkflowEventInput = Omit<WorkflowEvent, "hash" | "session_id"> & {
+  actor_name?: string;
+  trigger_reason?: string;
+};
+
+export function resolveWorkflowEventLedgerLocation(
+  basePath: string,
+  originalProjectRoot?: string | null,
+): WorkflowEventLedgerLocation {
+  const contract = resolveGsdPathContract(basePath, originalProjectRoot);
+  return {
+    projectRoot: contract.projectRoot,
+    workRoot: contract.workRoot,
+    projectGsd: contract.projectGsd,
+    worktreeGsd: contract.worktreeGsd,
+    projectLogPath: join(contract.projectGsd, WORKFLOW_EVENT_LOG_FILENAME),
+    worktreeLogPath: contract.worktreeGsd
+      ? join(contract.worktreeGsd, WORKFLOW_EVENT_LOG_FILENAME)
+      : null,
+    isWorktree: contract.isWorktree,
+  };
+}
+
+export function workflowEventLogPath(basePath: string): string {
+  return resolveWorkflowEventLedgerLocation(basePath).projectLogPath;
+}
+
+export function workflowEventArchivePath(basePath: string, milestoneId: string): string {
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+  return join(location.projectGsd, `event-log-${milestoneId}.jsonl.archived`);
+}
+
+export function readWorktreeEventLogPath(worktreeBasePath: string): string {
+  const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+  return location.worktreeLogPath ?? location.projectLogPath;
+}
+
+export function buildWorkflowEvent(event: WorkflowEventInput, sessionId: string): WorkflowEvent {
+  const hash = createHash("sha256")
+    .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
+    .digest("hex")
+    .slice(0, 16);
+
+  return {
+    v: 2,
+    ...event,
+    hash,
+    session_id: sessionId,
+  };
+}
+
+export function appendWorkflowEvent(
+  basePath: string,
+  event: WorkflowEventInput,
+  sessionId: string,
+): WorkflowEvent {
+  const fullEvent = buildWorkflowEvent(event, sessionId);
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+
+  mkdirSync(location.projectGsd, { recursive: true });
+  appendFileSync(location.projectLogPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
+  emitWorkflowEventAudit(location.projectRoot, fullEvent);
+  return fullEvent;
+}
+
+export function writeWorkflowEventLog(basePath: string, events: readonly WorkflowEvent[]): void {
+  const location = resolveWorkflowEventLedgerLocation(basePath);
+  mkdirSync(location.projectGsd, { recursive: true });
+  const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+  atomicWriteSync(location.projectLogPath, content);
+}
+
+export function writeWorktreeEventLog(
+  worktreeBasePath: string,
+  events: readonly WorkflowEvent[],
+): void {
+  const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+  const logPath = location.worktreeLogPath ?? location.projectLogPath;
+  mkdirSync(dirname(logPath), { recursive: true });
+  const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+  atomicWriteSync(logPath, content);
+}
+
+function emitWorkflowEventAudit(basePath: string, event: WorkflowEvent): void {
+  if (!isUnifiedAuditEnabled()) return;
+  try {
+    const normalized = normalizeWorkflowEventCommand(event.cmd) ?? "unknown";
+    emitUokAuditEvent(
+      basePath,
+      buildAuditEnvelope({
+        traceId: event.session_id,
+        category: "orchestration",
+        type: `workflow-event-${normalized}`,
+        payload: {
+          cmd: event.cmd,
+          params: event.params,
+          actor: event.actor,
+          actorName: event.actor_name,
+          triggerReason: event.trigger_reason,
+          eventTs: event.ts,
+          hash: event.hash,
+        },
+      }),
+    );
+  } catch {
+    // Best-effort: audit projection must never block the workflow event ledger.
+  }
+}

package/src/resources/extensions/gsd/workflow-event-vocabulary.ts

@@ -0,0 +1,59 @@
+import type { WorkflowEvent } from "./workflow-events.js";
+
+export interface WorkflowEventEntityKey {
+  type: string;
+  id: string;
+}
+
+export function normalizeWorkflowEventCommand(cmd: unknown): string | null {
+  return typeof cmd === "string" ? cmd.replace(/-/g, "_") : null;
+}
+
+/**
+ * Workflow progress events are keyed by the domain entity they mutate.
+ * Keep command aliases and conflict identity in this module so replay,
+ * conflict detection, and tests do not each grow their own vocabulary.
+ */
+export function workflowEventEntityKey(event: WorkflowEvent): WorkflowEventEntityKey | null {
+  const p = event.params;
+  const cmd = normalizeWorkflowEventCommand(event.cmd);
+  if (!cmd) return null;
+
+  switch (cmd) {
+    case "complete_task":
+    case "start_task":
+    case "skip_task":
+    case "report_blocker":
+    case "record_verification":
+    case "plan_task":
+      return typeof p["taskId"] === "string"
+        ? { type: "task", id: p["taskId"] }
+        : null;
+
+    case "complete_slice":
+    case "replan_slice":
+      return typeof p["sliceId"] === "string"
+        ? { type: "slice", id: p["sliceId"] }
+        : null;
+
+    case "plan_slice":
+      return typeof p["sliceId"] === "string"
+        ? { type: "slice_plan", id: p["sliceId"] }
+        : null;
+
+    case "complete_milestone":
+    case "plan_milestone":
+      return typeof p["milestoneId"] === "string"
+        ? { type: "milestone", id: p["milestoneId"] }
+        : null;
+
+    case "save_decision":
+      if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
+        return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
+      }
+      return null;
+
+    default:
+      return null;
+  }
+}