@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

package/dist/resources/extensions/gsd/unmerged-milestone-guard.js

@@ -1,22 +1,38 @@
 // Project/App: gsd-pi
 // File Purpose: Block new workflow entry when completed milestone branches are still unmerged.
-import { nativeBranchExists, nativeDetectMainBranch, nativeDiffNumstat, } from "./native-git-bridge.js";
+import { execFileSync } from "node:child_process";
+import { nativeBranchExists, nativeDetectMainBranch, nativeDiffNumstat, nativeIsAncestor, } from "./native-git-bridge.js";
 import { autoWorktreeBranch } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getAllMilestones } from "./gsd-db.js";
 import { resolveMilestoneIntegrationBranch } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { captureRootDirtySnapshot } from "./root-write-leak-guard.js";
 import { isClosedStatus } from "./status-guards.js";
 const BLOCKED_COMMANDS = new Set([
     "auto",
     "next",
-    "parallel",
     "start",
     "workflow",
     "new-milestone",
     "new-project",
     "do",
+    "discuss-phase",
+    "plan-phase",
+    "execute-phase",
+    "spec-phase",
+    "mvp-phase",
+    "ui-phase",
+    "ai-integration-phase",
+    "ultraplan-phase",
+    "validate-phase",
+    "docs-update",
+    "review-backlog",
+    "import",
+    "ingest-docs",
+    "secure-phase",
+    "plan-review-convergence",
+    "autonomous",
+    "resume-work",
     "execute-task",
     "research-milestone",
     "plan-slice",
@@ -26,13 +42,53 @@ const BLOCKED_COMMANDS = new Set([
     "validate-milestone",
     "complete-milestone",
 ]);
+const UNMERGED_SAFE_PARALLEL_SUBCOMMANDS = new Set([
+    "status",
+    "watch",
+]);
 function isRuntimePath(path) {
     return path === ".gsd" || path.startsWith(".gsd/");
 }
+function captureDirtyPathStatusSnapshot(rootPath) {
+    const snapshot = new Map();
+    let status = "";
+    try {
+        status = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], {
+            cwd: rootPath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch {
+        return snapshot;
+    }
+    for (const line of status.split("\n")) {
+        if (!line.trim())
+            continue;
+        const code = line.slice(0, 2);
+        const path = line.slice(3).replace(/^"|"$/g, "");
+        if (!path || isRuntimePath(path))
+            continue;
+        snapshot.set(path, {
+            path,
+            status: code.trim() || code,
+        });
+    }
+    return snapshot;
+}
 function formatCommandLabel(attemptedCommand) {
     const trimmed = attemptedCommand.trim();
     return trimmed ? `/gsd ${trimmed}` : "/gsd";
 }
+function hasFlag(command, flag) {
+    const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|\\s)${escaped}(?=\\s|$)`).test(command);
+}
+function isMutatingPhaseCommand(subcommand) {
+    if (!subcommand)
+        return false;
+    return ["add", "create", "new", "insert", "remove", "edit"].includes(subcommand);
+}
 function resolveIntegrationBranch(base, milestoneId) {
     const prefs = loadEffectiveGSDPreferences(base)?.preferences?.git ?? {};
     const resolution = resolveMilestoneIntegrationBranch(base, milestoneId, prefs);
@@ -57,12 +113,30 @@ export function isUnmergedMilestoneAllowedCommand(trimmed) {
     if (name === "dispatch") {
         return subcommand === "complete" || subcommand === "complete-milestone";
     }
+    if (name === "audit-fix") {
+        return hasFlag(command, "--dry-run");
+    }
+    if (name === "code-review") {
+        return !hasFlag(command, "--fix");
+    }
+    if (name === "docs-update") {
+        return hasFlag(command, "--verify-only");
+    }
+    if (name === "parallel") {
+        return UNMERGED_SAFE_PARALLEL_SUBCOMMANDS.has(subcommand ?? "");
+    }
+    if (name === "phase") {
+        return !isMutatingPhaseCommand(subcommand);
+    }
+    if (name === "progress") {
+        return !hasFlag(command, "--next") && !hasFlag(command, "--do");
+    }
     return !BLOCKED_COMMANDS.has(name);
 }
 export async function findUnmergedCompletedMilestones(base) {
     await ensureDbOpen(base);
     const blockers = [];
-    const dirtyByPath = captureRootDirtySnapshot(base);
+    let dirtyByPath = null;
     for (const milestone of getAllMilestones()) {
         if (!isClosedStatus(milestone.status))
             continue;
@@ -72,19 +146,31 @@ export async function findUnmergedCompletedMilestones(base) {
         const integrationBranch = resolveIntegrationBranch(base, milestone.id);
         if (!integrationBranch || integrationBranch === branch)
             continue;
+        // The milestone is merged when its branch tip is reachable from the
+        // integration branch tip — true for fast-forward, --no-ff, and squash
+        // merges alike. A raw diff is the wrong predicate: a --no-ff merge that
+        // took main's side for some conflicts leaves the branch tip differing from
+        // main, which the diff check would misread as "unmerged" (#825). The diff
+        // below remains the correct fallback only when the branch is NOT yet an
+        // ancestor — i.e. the merge is genuinely still pending.
+        if (nativeIsAncestor(base, branch, integrationBranch))
+            continue;
         const files = nativeDiffNumstat(base, integrationBranch, branch)
             .map((entry) => entry.path)
             .filter((path) => path && !isRuntimePath(path));
         const uniqueFiles = [...new Set(files)].sort();
         if (uniqueFiles.length === 0)
             continue;
+        if (!dirtyByPath)
+            dirtyByPath = captureDirtyPathStatusSnapshot(base);
+        const dirtySnapshot = dirtyByPath;
         blockers.push({
             milestoneId: milestone.id,
             branch,
             integrationBranch,
             files: uniqueFiles,
             dirtyOverlap: uniqueFiles
-                .map((path) => dirtyByPath.get(path))
+                .map((path) => dirtySnapshot.get(path))
                 .filter((entry) => Boolean(entry)),
         });
     }

package/dist/resources/extensions/gsd/validation-block-guard.js

@@ -3,8 +3,9 @@
 import { existsSync } from "node:fs";
 import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";
-import { deriveState } from "./state.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import { detectWorktreeName } from "./worktree.js";
 const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 const VALIDATION_SAFE_DISPATCH_COMMANDS = new Set([
@@ -20,6 +21,27 @@ const VALIDATION_BLOCKED_COMMANDS = new Set([
     "ship",
     "complete-milestone",
     "do",
+    "discuss-phase",
+    "import",
+    "ingest-docs",
+    "review-backlog",
+    "docs-update",
+    "secure-phase",
+    "plan-phase",
+    "execute-phase",
+    "spec-phase",
+    "mvp-phase",
+    "ui-phase",
+    "ai-integration-phase",
+    "ultraplan-phase",
+    "plan-review-convergence",
+    "autonomous",
+    "resume-work",
+    "discuss-phase",
+    "import",
+    "ingest-docs",
+    "review-backlog",
+    "secure-phase",
 ]);
 const VALIDATION_BLOCKED_PARALLEL_SUBCOMMANDS = new Set([
     "",
@@ -37,6 +59,15 @@ const VALIDATION_SAFE_WORKFLOW_SUBCOMMANDS = new Set([
     "install",
     "uninstall",
 ]);
+function hasFlag(command, flag) {
+    const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|\\s)${escaped}(?=\\s|$)`).test(command);
+}
+function isMutatingPhaseCommand(subcommand) {
+    if (!subcommand)
+        return false;
+    return ["add", "create", "new", "insert", "remove", "edit"].includes(subcommand);
+}
 export function isValidationBlockedState(state) {
     if (state.phase !== "blocked")
         return false;
@@ -56,6 +87,21 @@ export function isValidationBlockAllowedCommand(trimmed) {
     if (name === "workflow") {
         return VALIDATION_SAFE_WORKFLOW_SUBCOMMANDS.has(subcommand ?? "");
     }
+    if (name === "audit-fix") {
+        return hasFlag(command, "--dry-run");
+    }
+    if (name === "code-review") {
+        return !hasFlag(command, "--fix");
+    }
+    if (name === "docs-update") {
+        return hasFlag(command, "--verify-only");
+    }
+    if (name === "phase") {
+        return !isMutatingPhaseCommand(subcommand);
+    }
+    if (name === "progress") {
+        return !hasFlag(command, "--next") && !hasFlag(command, "--do");
+    }
     return !VALIDATION_BLOCKED_COMMANDS.has(name);
 }
 export function formatValidationBlockedMessage(state, attemptedCommand = "") {
@@ -70,8 +116,7 @@ export function formatValidationBlockedMessage(state, attemptedCommand = "") {
         ...blockers,
     ].join("\n\n");
 }
-export async function getValidationBlockMessageForBase(base, attemptedCommand = "") {
-    await ensureDbOpen(base);
+async function deriveValidationBlockState(base) {
     let state = await deriveState(base);
     if (state.activeMilestone &&
         getIsolationMode(base) === "worktree" &&
@@ -82,5 +127,12 @@ export async function getValidationBlockMessageForBase(base, attemptedCommand =
             state = await deriveState(wtPath);
         }
     }
+    return state;
+}
+export async function getValidationBlockMessageForBase(base, attemptedCommand = "") {
+    await ensureDbOpen(base);
+    refreshWorkflowDatabaseFromDisk();
+    invalidateStateCache();
+    const state = await deriveValidationBlockState(base);
     return formatValidationBlockedMessage(state, attemptedCommand);
 }

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/visualizer-data.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { deriveState } from './state.js';
 import { parseSummary, loadFile } from './files.js';
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from './gsd-db.js';
+import { openExistingWorkflowDatabase } from './db-workspace.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
 import { findMilestoneIds } from './milestone-ids.js';
 import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile, gsdRoot } from './paths.js';
@@ -15,6 +16,7 @@ import { generateSkillHealthReport } from './skill-health.js';
 import { runEnvironmentChecks } from './doctor-environment.js';
 import { computeProgressScore } from './progress-score.js';
 import { getHealthHistory } from './doctor-proactive.js';
+import { getActiveMemories, getActiveMemoriesRanked } from './memory-store.js';
 // ─── Critical Path ────────────────────────────────────────────────────────────
 export function computeCriticalPath(milestones) {
     const empty = {
@@ -351,6 +353,36 @@ function loadKnowledge(basePath) {
     }
     return { rules, patterns, lessons, exists: true };
 }
+// ─── Memory Loader ────────────────────────────────────────────────────────────
+const VISUALIZER_MEMORY_LIMIT = 20;
+const VISUALIZER_MEMORY_CONTENT_LIMIT = 2000;
+function ensureVisualizerDb(basePath) {
+    if (isDbAvailable())
+        return;
+    openExistingWorkflowDatabase(basePath);
+}
+function loadMemories() {
+    const allActive = getActiveMemories();
+    const ranked = getActiveMemoriesRanked(VISUALIZER_MEMORY_LIMIT);
+    return {
+        totalCount: allActive.length,
+        entries: ranked.map((memory) => ({
+            id: memory.id,
+            category: memory.category,
+            content: limitMemoryContent(memory.content),
+            confidence: memory.confidence,
+            hitCount: memory.hit_count,
+            scope: memory.scope,
+            tags: memory.tags,
+            updatedAt: memory.updated_at,
+        })),
+    };
+}
+function limitMemoryContent(content) {
+    if (content.length <= VISUALIZER_MEMORY_CONTENT_LIMIT)
+        return content;
+    return `${content.slice(0, VISUALIZER_MEMORY_CONTENT_LIMIT).trimEnd()}...`;
+}
 // ─── Health Loader ────────────────────────────────────────────────────────────
 function loadHealth(units, totals, basePath) {
     const prefs = loadEffectiveGSDPreferences();
@@ -524,6 +556,7 @@ function readFileCached(filePath) {
 }
 // ─── Loader ───────────────────────────────────────────────────────────────────
 export async function loadVisualizerData(basePath) {
+    ensureVisualizerDb(basePath);
     const state = await deriveState(basePath);
     const milestoneIds = findMilestoneIds(basePath);
     const milestones = [];
@@ -640,6 +673,7 @@ export async function loadVisualizerData(basePath) {
     const agentActivity = loadAgentActivity(units, milestones);
     const { changelog, verifications: sliceVerifications } = await loadChangelogAndVerifications(basePath, milestones);
     const knowledge = loadKnowledge(basePath);
+    const memories = loadMemories();
     const allCaptures = loadAllCaptures(basePath);
     const pendingCount = countPendingCaptures(basePath);
     const captures = {
@@ -666,6 +700,7 @@ export async function loadVisualizerData(basePath) {
         changelog,
         sliceVerifications,
         knowledge,
+        memories,
         captures,
         health,
         discussion,

package/dist/resources/extensions/gsd/visualizer-views.js

@@ -705,11 +705,16 @@ export function renderExportView(_data, th, _width, lastExportPath) {
 export function renderKnowledgeView(data, th, width) {
     const lines = [];
     const knowledge = data.knowledge;
-    if (!knowledge.exists) {
+    const memories = data.memories;
+    if (!knowledge.exists && memories.entries.length === 0) {
         lines.push(th.fg("dim", "No KNOWLEDGE.md found"));
         return lines;
     }
-    if (knowledge.rules.length === 0 && knowledge.patterns.length === 0 && knowledge.lessons.length === 0) {
+    if (knowledge.exists &&
+        knowledge.rules.length === 0 &&
+        knowledge.patterns.length === 0 &&
+        knowledge.lessons.length === 0 &&
+        memories.entries.length === 0) {
         lines.push(th.fg("dim", "KNOWLEDGE.md exists but is empty"));
         return lines;
     }
@@ -740,6 +745,20 @@ export function renderKnowledgeView(data, th, width) {
         }
         lines.push("");
     }
+    if (memories.entries.length > 0) {
+        const countLabel = memories.totalCount > memories.entries.length
+            ? `${memories.entries.length}/${memories.totalCount}`
+            : `${memories.totalCount}`;
+        lines.push(th.fg("accent", th.bold(`Memories (${countLabel})`)));
+        lines.push("");
+        for (const memory of memories.entries) {
+            const scope = memory.scope && memory.scope !== "project" ? ` ${th.fg("dim", `[${memory.scope}]`)}` : "";
+            const tags = memory.tags.length > 0 ? ` ${th.fg("dim", `#${memory.tags.join(" #")}`)}` : "";
+            lines.push(truncateToWidth(`  ${th.fg("accent", memory.id)}  (${memory.category}, ${memory.confidence.toFixed(2)}, hits ${memory.hitCount})${scope}${tags}`, width));
+            lines.push(truncateToWidth(`    ${memory.content}`, width));
+        }
+        lines.push("");
+    }
     return lines;
 }
 // ─── Captures View ───────────────────────────────────────────────────────────

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

@@ -0,0 +1,117 @@
+// Project/App: gsd-pi
+// 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");
+    if (!existsSync(packageJsonPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasPlaywrightTestDependency(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    if (!pkg)
+        return false;
+    const names = [
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.devDependencies ?? {}),
+    ];
+    return names.some((name) => name === "playwright" || name === "@playwright/test");
+}
+export function findPlaywrightTestScript(projectRoot) {
+    const pkg = readPackageJson(projectRoot);
+    if (!pkg?.scripts)
+        return null;
+    for (const [name, value] of Object.entries(pkg.scripts)) {
+        if (typeof value !== "string")
+            continue;
+        if (/\bplaywright\s+test\b/.test(value)) {
+            return `npm run ${name}`;
+        }
+    }
+    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. 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, 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)",
+        "",
+        describeBrowserToolBacking(resolvedEngine),
+        "",
+        "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
+        ...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`)",
+        "- Slice Verification and UAT test cases must not say \"open in browser\" under `artifact-driven` — complete-slice rejects that",
+        "- Milestone `Verification Classes` → UAT row must describe browser-observable acceptance, not \"manual spot check\" alone",
+    ];
+    if (hasPlaywright) {
+        lines.push("", "**Playwright:** dependency detected.");
+        if (playwrightScript) {
+            lines.push(`- Prefer slice verification and runtime-executable UAT referencing \`${playwrightScript}\` or a focused \`npx playwright test <spec>\` command`);
+        }
+        else {
+            lines.push("- Prefer runtime-executable UAT with `npx playwright test` (or a focused spec path) when UI behavior is covered by specs");
+        }
+        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");
+        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;
+    }
+}