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

package/dist/resources/extensions/gsd/tools/plan-task.js

@@ -4,7 +4,7 @@ import { isNonEmptyString, validateStringArray } from "../validation.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -110,7 +110,7 @@ export async function handlePlanTask(rawParams, basePath) {
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────────────
         try {
-            await renderAllProjections(basePath, params.milestoneId);
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "plan-task",

package/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -6,7 +6,7 @@ import { isNonEmptyString } from "../validation.js";
 import { transaction, getMilestone, getMilestoneSlices, getSlice, insertSlice, updateSliceFields, insertAssessment, deleteAssessmentByScope, deleteSlice, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -234,7 +234,7 @@ export async function handleReassessRoadmap(rawParams, basePath) {
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────
         try {
-            await renderAllProjections(basePath, params.milestoneId);
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "reassess-roadmap",

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

@@ -9,7 +9,7 @@
  */
 import { getMilestoneSlices, getSliceTasks, reopenMilestoneCascade, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -74,7 +74,7 @@ export async function handleReopenMilestone(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-milestone",

package/dist/resources/extensions/gsd/tools/reopen-slice.js

@@ -11,7 +11,7 @@
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 import { getSliceTasks, reopenSliceCascade, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -72,7 +72,7 @@ export async function handleReopenSlice(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-slice",

package/dist/resources/extensions/gsd/tools/reopen-task.js

@@ -11,7 +11,7 @@
 import { getMilestone, getSlice, getTask, updateTaskStatus, transaction, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -83,7 +83,7 @@ export async function handleReopenTask(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-task",

package/dist/resources/extensions/gsd/tools/replan-slice.js

@@ -4,7 +4,7 @@ import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
 import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -162,7 +162,7 @@ export async function handleReplanSlice(rawParams, basePath) {
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────
         try {
-            await renderAllProjections(basePath, params.milestoneId);
+            await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
             writeManifest(basePath);
             appendEvent(basePath, {
                 cmd: "replan-slice",

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -6,9 +6,10 @@ import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, should
 import { getActiveRequirements, getAllMilestones, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertMilestone, insertAssessment, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } 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 { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
@@ -25,9 +26,11 @@ 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, } 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 const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -61,6 +64,19 @@ function blockIfWrongAutoUnit(requiredUnitType, operation) {
         isError: true,
     };
 }
+function milestoneLeaseConflictResult(milestoneId, byWorker, expiresAt) {
+    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,
+    };
+}
 function registerProjectMilestoneSequence(content) {
     const parsed = parseProject(content);
     const registered = [];
@@ -1066,7 +1082,45 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             isError: true,
         };
     }
+    let workerId = null;
+    let acquiredToken = null;
+    let leaseRefreshTimer;
     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 {
@@ -1093,6 +1147,17 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             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(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);

package/dist/resources/extensions/gsd/uat-policy.js

@@ -1,17 +1,10 @@
 // Project/App: gsd-pi
 // 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 { hasBrowserRequiredText } from "./browser-evidence.js";
 import { parseMcpToolName } from "./mcp-tool-name.js";
-export const UAT_TYPES = [
-    "artifact-driven",
-    "browser-executable",
-    "runtime-executable",
-    "live-runtime",
-    "mixed",
-    "human-experience",
-];
+export const UAT_TYPES = UAT_TYPE_KEYWORDS;
 export const UAT_MODE_POLICIES = {
     "artifact-driven": {
         browserTools: false,
@@ -56,23 +49,55 @@ export function isUatType(value) {
 export function getDeclaredUatType(content) {
     return extractUatType(content) ?? "artifact-driven";
 }
-export function classifyUatContent(content) {
-    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) {
+    return SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE.test(content);
+}
+function resolveEffectiveUatTypeFromPolicy(declaredType, browserRequired, content) {
+    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) {
+    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, supplementalContext = "") {
+    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) {
-    const policy = classifyUatContent(content);
+export function escalatesArtifactUatToBrowser(policy) {
     return policy.declaredType === "artifact-driven" && policy.browserRequired;
 }
+export function shouldEscalateArtifactUatToBrowser(content) {
+    return escalatesArtifactUatToBrowser(classifyUatContent(content));
+}
 export function resolveEffectiveUatType(content) {
     return classifyUatContent(content).effectiveType;
 }

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

@@ -36,6 +36,7 @@
 // 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";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 /**
  * Produce the inlined-context portion of a unit's system prompt by
  * walking the manifest's `artifacts.inline` list in order and calling
@@ -122,6 +123,70 @@ export function composeContextModeInstructions(unitType, opts) {
         guidance,
     ].join("\n");
 }
+const TOOL_SURFACE_GUIDANCE_BY_UNIT = {
+    "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) {
+    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, unitGuidance) {
+    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, opts) {
+    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) => 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");
+}
 const SECTION_SEPARATOR = "\n\n---\n\n";
 /**
  * Compose all manifest-declared context for a unit type using the v2

package/dist/resources/extensions/gsd/unit-registry.js

@@ -173,15 +173,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",
@@ -207,8 +211,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": {
@@ -216,8 +233,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/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/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;
+    }
+}