@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.9ad8ae33

package/dist/resources/extensions/gsd/unit-tool-contracts.js

@@ -1,187 +1,14 @@
 // Project/App: gsd-pi
-// File Purpose: Central Unit-to-tool contracts for phase-aware GSD tool surfaces.
-export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
-    "gsd_uat_exec",
-    "gsd_uat_result_save",
-    "gsd_resume",
-    "gsd_milestone_status",
-    "gsd_journal_query",
-];
-export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
-    "find",
-    "glob",
-    "grep",
-    "ls",
-    "read",
-];
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-    "browser_navigate",
-    "browser_click",
-    "browser_type",
-    "browser_fill_form",
-    "browser_click_ref",
-    "browser_fill_ref",
-    "browser_wait_for",
-    "browser_assert",
-    "browser_verify",
-    "browser_screenshot",
-    "browser_snapshot_refs",
-    "browser_find",
-    "browser_get_console_logs",
-    "browser_get_network_logs",
-    "browser_evaluate",
-    "browser_reload",
-    "browser_batch",
-    "browser_act",
-];
+// File Purpose: Unit-to-tool contract views derived from the Unit Registry (ADR-033).
+//
+// The contract data lives in unit-registry.ts (one Unit Descriptor per unit
+// type). This file keeps the established import surface: the derived
+// `UNIT_TOOL_CONTRACTS` table and its accessor functions are unchanged for
+// consumers.
+import { UNIT_REGISTRY, } from "./unit-registry.js";
+export { RUN_UAT_WORKFLOW_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_BROWSER_TOOL_NAMES, } from "./unit-registry.js";
 export const RUN_UAT_TOOL_PRESENTATION_PLAN_ID = "run-uat/default-v1";
-export const UNIT_TOOL_CONTRACTS = {
-    "research-milestone": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_summary_save"],
-    },
-    "plan-milestone": {
-        allowedGsdTools: [
-            "gsd_milestone_status",
-            "gsd_plan_milestone",
-            "gsd_plan_slice",
-            "gsd_decision_save",
-            "gsd_requirement_update",
-        ],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
-    },
-    "discuss-milestone": {
-        allowedGsdTools: [
-            "gsd_summary_save",
-            "gsd_decision_save",
-            "gsd_requirement_save",
-            "gsd_requirement_update",
-            "gsd_plan_milestone",
-            "gsd_milestone_generate_id",
-        ],
-        requiredWorkflowTools: [
-            "ask_user_questions",
-            "gsd_summary_save",
-            "gsd_requirement_save",
-            "gsd_requirement_update",
-            "gsd_plan_milestone",
-            "gsd_milestone_generate_id",
-        ],
-    },
-    "discuss-slice": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-    },
-    "validate-milestone": {
-        allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
-    },
-    "complete-milestone": {
-        allowedGsdTools: [
-            "gsd_milestone_status",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "gsd_complete_milestone",
-            "subagent",
-        ],
-        requiredWorkflowTools: [
-            "gsd_milestone_status",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "gsd_complete_milestone",
-        ],
-    },
-    "research-slice": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_summary_save"],
-    },
-    "plan-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
-    },
-    "refine-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_plan_slice"],
-    },
-    "replan-slice": {
-        allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_replan_slice"],
-    },
-    "complete-slice": {
-        allowedGsdTools: [
-            "gsd_slice_complete",
-            "gsd_task_reopen",
-            "gsd_replan_slice",
-            "gsd_decision_save",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "subagent",
-        ],
-        requiredWorkflowTools: [
-            "gsd_slice_complete",
-            "gsd_task_reopen",
-            "gsd_replan_slice",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-        ],
-        forbiddenGsdTools: {
-            gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
-        },
-    },
-    "reassess-roadmap": {
-        allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-    },
-    "execute-task": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete"],
-    },
-    "execute-task-simple": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete"],
-    },
-    "reactive-execute": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
-    },
-    "run-uat": {
-        allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
-        requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
-        forbiddenGsdTools: {
-            gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
-            gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
-            gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
-        },
-    },
-    "gate-evaluate": {
-        allowedGsdTools: ["gsd_save_gate_result"],
-        requiredWorkflowTools: ["gsd_save_gate_result"],
-    },
-    "rewrite-docs": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: [],
-    },
-    "workflow-preferences": {
-        allowedGsdTools: ["gsd_summary_save"],
-        requiredWorkflowTools: [],
-    },
-    "discuss-project": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-    },
-    "discuss-requirements": {
-        allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
-    },
-    "research-decision": {
-        allowedGsdTools: ["gsd_summary_save"],
-        requiredWorkflowTools: ["ask_user_questions"],
-    },
-    "research-project": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: [],
-    },
-};
+export const UNIT_TOOL_CONTRACTS = Object.fromEntries(Object.entries(UNIT_REGISTRY).flatMap(([unitType, descriptor]) => descriptor.toolContract ? [[unitType, descriptor.toolContract]] : []));
 export const AUTO_UNIT_SCOPED_TOOLS = Object.fromEntries(Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]));
 export function getUnitToolSurfaceContract(unitType) {
     return UNIT_TOOL_CONTRACTS[unitType];

package/dist/resources/extensions/gsd/verdict-parser.js

@@ -128,7 +128,7 @@ export function isValidMilestoneVerdict(verdict) {
  * 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) {
     return getDeclaredUatType(content);

package/dist/resources/extensions/gsd/verification-verdict.js

@@ -1,5 +1,6 @@
 // Project/App: gsd-pi
 // File Purpose: Host-owned verification verdict policy for auto-mode units.
+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, result) {
     if (unitType === "execute-task" && result.discoverySource === "task-plan-prose" && result.checks.length === 0) {
         return {
@@ -14,7 +15,7 @@ export function decideVerificationVerdict(unitType, result) {
             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,
         };
     }
     if (!result.passed) {

package/dist/resources/extensions/gsd/web-app-uat.js

@@ -1,8 +1,10 @@
 // Project/App: gsd-pi
-// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution } from "../browser-tools/engine/selection.js";
 import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES } from "./uat-policy.js";
 export { detectWebApp };
 function readPackageJson(projectRoot) {
     const packageJsonPath = resolve(projectRoot, "package.json");
@@ -39,24 +41,56 @@ export function findPlaywrightTestScript(projectRoot) {
     }
     return null;
 }
+function describeBrowserToolBacking(engineResolution) {
+    switch (engineResolution.engine) {
+        case "gsd-browser":
+            return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+        case "legacy":
+            return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+        case "off":
+            return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+    }
+}
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE = [
+    {
+        mode: "browser-executable",
+        bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+    },
+    {
+        mode: "runtime-executable",
+        bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+    },
+    {
+        mode: "mixed",
+        bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    },
+];
 /**
  * Markdown block injected into plan/complete-slice prompts when the project
- * looks browser-facing. Returns null for CLI/library-only repos.
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
  */
-export function buildWebAppUatGuidanceBlock(projectRoot) {
+export function buildWebAppUatGuidanceBlock(projectRoot, engineResolution) {
     if (!detectWebApp(projectRoot))
         return null;
+    const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+    const browserToolsAvailable = resolvedEngine.engine !== "off";
     const playwrightScript = findPlaywrightTestScript(projectRoot);
     const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
     const lines = [
         "### Web App UAT (detected)",
         "",
-        "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools by default for run-uat.",
+        describeBrowserToolBacking(resolvedEngine),
         "",
         "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
-        "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
-        "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
-        "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+        ...UAT_MODE_GUIDANCE
+            .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+            .map(({ bullet }) => bullet),
         "",
         "**Planning / closeout rules:**",
         "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
@@ -74,7 +108,10 @@ export function buildWebAppUatGuidanceBlock(projectRoot) {
         lines.push("- Name concrete spec paths in slice Verification (for example `e2e/smoke.spec.ts`)");
     }
     else {
-        lines.push("", "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.", "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)", "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command", "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        lines.push("", "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.", "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)", "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command");
+        if (browserToolsAvailable) {
+            lines.push("- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        }
     }
     return lines.join("\n");
 }

package/dist/resources/extensions/gsd/workflow-event-ledger.js

@@ -0,0 +1,91 @@
+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";
+export const WORKFLOW_EVENT_LOG_FILENAME = "event-log.jsonl";
+export function resolveWorkflowEventLedgerLocation(basePath, originalProjectRoot) {
+    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) {
+    return resolveWorkflowEventLedgerLocation(basePath).projectLogPath;
+}
+export function workflowEventArchivePath(basePath, milestoneId) {
+    const location = resolveWorkflowEventLedgerLocation(basePath);
+    return join(location.projectGsd, `event-log-${milestoneId}.jsonl.archived`);
+}
+export function readWorktreeEventLogPath(worktreeBasePath) {
+    const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+    return location.worktreeLogPath ?? location.projectLogPath;
+}
+export function buildWorkflowEvent(event, sessionId) {
+    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, event, sessionId) {
+    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, events) {
+    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, events) {
+    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, event) {
+    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/dist/resources/extensions/gsd/workflow-event-vocabulary.js

@@ -0,0 +1,46 @@
+export function normalizeWorkflowEventCommand(cmd) {
+    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) {
+    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;
+    }
+}

package/dist/resources/extensions/gsd/workflow-events.js

@@ -1,8 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { withFileLockSync } from "./file-lock.js";
+import { appendWorkflowEvent, workflowEventArchivePath, workflowEventLogPath, } from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 // ─── Session ID ───────────────────────────────────────────────────────────
 /**
@@ -20,19 +20,7 @@ export function getSessionId() {
  * Creates .gsd directory if needed.
  */
 export function appendEvent(basePath, event) {
-    const hash = createHash("sha256")
-        .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-        .digest("hex")
-        .slice(0, 16);
-    const fullEvent = {
-        v: 2,
-        ...event,
-        hash,
-        session_id: ENGINE_SESSION_ID,
-    };
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+    appendWorkflowEvent(basePath, event, ENGINE_SESSION_ID);
 }
 // ─── readEvents ──────────────────────────────────────────────────────────
 /**
@@ -87,8 +75,8 @@ export function findForkPoint(logA, logB) {
  * @returns { archived: number } — count of events moved to archive
  */
 export function compactMilestoneEvents(basePath, milestoneId) {
-    const logPath = join(basePath, ".gsd", "event-log.jsonl");
-    const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+    const logPath = workflowEventLogPath(basePath);
+    const archivePath = workflowEventArchivePath(basePath, milestoneId);
     return withFileLockSync(logPath, () => {
         const allEvents = readEvents(logPath);
         // Single-pass partition to halve the work (per reviewer agent)

package/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -2,6 +2,8 @@ import { join } from "node:path";
 import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
+import { normalizeWorkflowEventCommand, workflowEventEntityKey, } from "./workflow-event-vocabulary.js";
+import { readWorktreeEventLogPath, workflowEventLogPath, writeWorkflowEventLog, writeWorktreeEventLog, } from "./workflow-event-ledger.js";
 import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, setTaskBlockerDiscovered, insertOrIgnoreSlice, insertOrIgnoreTask, } from "./gsd-db.js";
 import { openWorkflowDatabasePath } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -48,14 +50,11 @@ function replayEvents(events) {
     transaction(() => {
         for (const event of events) {
             const p = event.params;
-            // Normalize cmd format: completion tools write hyphens ("complete-task"),
-            // legacy logs use underscores ("complete_task"). Accept both formats.
-            // Type guard: malformed event lines with non-string cmd are skipped.
-            if (typeof event.cmd !== "string") {
+            const cmd = normalizeWorkflowEventCommand(event.cmd);
+            if (!cmd) {
                 logWarning("reconcile", `Event with non-string cmd skipped: ${JSON.stringify(event.cmd)}`);
                 continue;
             }
-            const cmd = event.cmd.replace(/-/g, "_");
             switch (cmd) {
                 case "complete_task": {
                     const milestoneId = p["milestoneId"];
@@ -199,43 +198,7 @@ function replayEvents(events) {
  * (e.g. unknown or future cmds).
  */
 export function extractEntityKey(event) {
-    const p = event.params;
-    // Normalize cmd format: accept both hyphens and underscores
-    if (typeof event.cmd !== "string")
-        return null;
-    const cmd = event.cmd.replace(/-/g, "_");
-    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;
-    }
+    return workflowEventEntityKey(event);
 }
 // ─── detectConflicts ──────────────────────────────────────────────────────────
 /**
@@ -302,12 +265,6 @@ function rewriteDivergedEventsForEntity(divergedEvents, entityType, entityId, re
     }
     return rewritten;
 }
-function writeEventLog(basePath, events) {
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    const content = events.map((e) => JSON.stringify(e)).join("\n") + (events.length > 0 ? "\n" : "");
-    atomicWriteSync(join(dir, "event-log.jsonl"), content);
-}
 // ─── writeConflictsFile ───────────────────────────────────────────────────────
 /**
  * Write a human-readable CONFLICTS.md to basePath/.gsd/CONFLICTS.md.
@@ -375,10 +332,15 @@ export function reconcileWorktreeLogs(mainBasePath, worktreeBasePath) {
 }
 function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     // Step 1: Read both logs
-    const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
-    const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+    const mainLogPath = workflowEventLogPath(mainBasePath);
+    const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
     const mainEvents = readEvents(mainLogPath);
     const wtEvents = readEvents(wtLogPath);
+    // Canonical worktree appends are already durable in the project ledger.
+    // Empty/missing worktree shards are legacy-only absence, not divergence.
+    if (wtEvents.length === 0) {
+        return { autoMerged: 0, conflicts: [] };
+    }
     // Step 2: Find fork point
     const forkPoint = findForkPoint(mainEvents, wtEvents);
     // Step 3: Slice diverged sets
@@ -412,9 +374,7 @@ function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     }
     const baseEvents = mainEvents.slice(0, forkPoint + 1);
     const mergedLog = baseEvents.concat(merged);
-    const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
-    mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
-    atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
+    writeWorkflowEventLog(mainBasePath, mergedLog);
     // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
     openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
     replayEvents(merged);
@@ -533,8 +493,8 @@ pick) {
         throw new Error(`No conflict found for entity ${entityKey}`);
     const conflict = conflicts[idx];
     const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
-    const mainLogPath = join(basePath, ".gsd", "event-log.jsonl");
-    const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+    const mainLogPath = workflowEventLogPath(basePath);
+    const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
     const mainEvents = readEvents(mainLogPath);
     const wtEvents = readEvents(wtLogPath);
     const forkPoint = findForkPoint(mainEvents, wtEvents);
@@ -547,7 +507,12 @@ pick) {
         : rewriteDivergedEventsForEntity(mainDiverged, entityType, entityId, eventsToReplay);
     const targetBasePath = pick === "main" ? worktreeBasePath : basePath;
     const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
-    writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    if (pick === "main") {
+        writeWorktreeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    }
+    else {
+        writeWorkflowEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    }
     // Replay resolved events through the DB (updates DB state)
     openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);
     replayEvents(eventsToReplay);

package/dist/resources/extensions/gsd/workflow-tool-surface.js

@@ -8,7 +8,7 @@ export const WORKFLOW_TOOL_ALIAS_NAMES = CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES;
 export const DB_WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
 export const WORKFLOW_TOOL_ALIAS_PAIRS = WORKFLOW_TOOL_CONTRACTS.flatMap((tool) => tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })));
 export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL = Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
     "gsd_cancel",
     "gsd_captures",
     "ask_user_questions",