@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/dist/resources/extensions/gsd/status-guards.js

@@ -1,16 +1,64 @@
 /**
- * Status predicates for GSD state-machine guards.
+ * Status predicates and the canonical status vocabulary for GSD state-machine
+ * guards (ADR-030).
  *
- * The DB stores status as free-form strings. Three values indicate
- * "closed": "complete" (canonical), "done" (legacy / alias),
- * "closed" (legacy/imported), and
- * "skipped" (user-directed skip via rethink or backtrack).
- * Every inline `status === "complete" || status === "done"` should
- * use isClosedStatus() instead.
+ * The DB column is free-form `string` so legacy/imported rows still load. Three
+ * raw values besides canonical "complete"/"skipped" indicate "closed": "done"
+ * (legacy alias), "closed" (legacy/imported), and "skipped" (user-directed skip
+ * via rethink or backtrack). `RAW_CLOSED_STATUSES` is the single source for both
+ * `isClosedStatus()` and the SQL terminal-status fragment
+ * (`db/sql-constants.ts` derives `TERMINAL_STATUS_SQL` from it), replacing the
+ * prior independent definitions.
+ *
+ * `toStatus()` is the single seam where a free-form string becomes the canonical
+ * `Status` vocabulary; the Status Transition Core writes canonical, so the store
+ * converges over time without a forced migration.
+ */
+/**
+ * Canonical, normalized entity-status vocabulary across milestones, slices, and
+ * tasks — the single source for both the `Status` type and the runtime
+ * membership set. The in-memory domain speaks `Status`; the DB column stays
+ * free-form.
+ */
+export const CANONICAL_STATUSES = [
+    "pending", "queued", "active", "parked", "in_progress", "blocked", "complete", "skipped", "deferred",
+];
+const CANONICAL_STATUS_SET = new Set(CANONICAL_STATUSES);
+/**
+ * Raw status values that mean a unit is closed — the single source of truth.
+ * Includes legacy/imported aliases ("done", "closed") alongside canonical
+ * "complete"/"skipped" because the DB column is free-form and older rows /
+ * imports still carry them. Order matters: `TERMINAL_STATUS_SQL` is derived
+ * from this array verbatim.
+ */
+export const RAW_CLOSED_STATUSES = ["complete", "done", "skipped", "closed"];
+const RAW_CLOSED_SET = new Set(RAW_CLOSED_STATUSES);
+/** Free-form aliases mapped to their canonical Status on read. */
+const ALIAS_TO_CANONICAL = {
+    done: "complete",
+    closed: "complete",
+    planned: "pending",
+    "in-progress": "in_progress",
+};
+/**
+ * Normalize a free-form DB status string into the canonical `Status`
+ * vocabulary. Maps known aliases (done/closed → complete, planned → pending,
+ * in-progress → in_progress). An unrecognized/legacy value is **quarantined** —
+ * preserved verbatim rather than silently remapped to a wrong canonical state —
+ * so reads never fail and reconciliation/telemetry can surface it.
  */
+export function toStatus(raw) {
+    const value = raw.trim();
+    if (CANONICAL_STATUS_SET.has(value))
+        return value;
+    const alias = ALIAS_TO_CANONICAL[value];
+    if (alias)
+        return alias;
+    return value;
+}
 /** Returns true when a milestone, slice, or task status indicates closure. */
 export function isClosedStatus(status) {
-    return status === "complete" || status === "done" || status === "skipped" || status === "closed";
+    return RAW_CLOSED_SET.has(status);
 }
 /** Returns true when a slice status indicates it was deferred by a decision. */
 export function isDeferredStatus(status) {

package/dist/resources/extensions/gsd/stop-notice.js

@@ -0,0 +1,57 @@
+// Project/App: gsd-pi
+// File Purpose: Stop Notice module — single owner of the auto/step-mode
+// stop/pause notice vocabulary. Both sides of the wire live here: the
+// formatters that produce the canonical prefixes (used by stopAuto/pauseAuto)
+// and the classifiers that recognize them (used by the headless host to pick
+// exit codes). Wording changes in this file keep emitter and detector in
+// lockstep; round-trip tests enforce it.
+/** A reason string of the form "Blocked: …" marks a blocked stop. */
+export function isBlockedStopReason(reason) {
+    return /^Blocked:\s*/i.test(reason ?? "");
+}
+/** Strip the "Blocked: " marker for display. */
+export function stopNoticeDisplayReason(reason) {
+    return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
+}
+export function stopNoticeKind(reason) {
+    return isBlockedStopReason(reason) ? "blocked" : "stopped";
+}
+/** Canonical stop-notice prefix: "Auto-mode blocked — reason" / "Auto-mode stopped". */
+export function formatStopNoticePrefix(reason) {
+    const displayReason = stopNoticeDisplayReason(reason);
+    const prefix = stopNoticeKind(reason) === "blocked" ? "Auto-mode blocked" : "Auto-mode stopped";
+    return displayReason ? `${prefix} — ${displayReason}` : prefix;
+}
+// ─── Classification (headless host side) ────────────────────────────────
+// The canonical lowercase prefixes the headless event loop recognizes in
+// notify messages. Emitters above and ad-hoc emitters elsewhere must start
+// their terminal notices with one of these.
+export const PAUSED_NOTICE_PREFIXES = ["auto-mode paused", "step-mode paused"];
+export const TERMINAL_NOTICE_PREFIXES = [
+    "auto-mode stopped",
+    "step-mode stopped",
+    "auto-mode complete",
+    "no active milestone",
+    "auto-mode idle",
+];
+/** Manual-resolution notices emitted before auto-mode can formally pause/stop. */
+export function isManualResolutionNotice(message) {
+    return (message.includes("resolve manually and re-run /gsd auto") ||
+        message.includes("resolve conflicts manually and run /gsd auto to resume") ||
+        message.includes("resolve and run /gsd auto to resume"));
+}
+export function isPauseNotice(message) {
+    return PAUSED_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+export function isTerminalNotice(message) {
+    return TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+/** Pauses that do not require operator intervention in headless mode. */
+export function isNonBlockingPauseNotice(message) {
+    return message.includes("idempotent advance: unit already active");
+}
+export function isBlockedNoticeMessage(message) {
+    return (message.includes("blocked:") ||
+        (isPauseNotice(message) && !isNonBlockingPauseNotice(message)) ||
+        isManualResolutionNotice(message));
+}

package/dist/resources/extensions/gsd/templates/plan.md

@@ -46,6 +46,13 @@
      For simple projects or scripts:
      - Executable verification commands (bash assertions, curl checks, etc.) are sufficient
 
+     For browser-facing web apps (React, Next, Vue, Vite, static HTML, etc.):
+     - Prefer `npx playwright test <spec>` in Verification when `@playwright/test` exists
+     - If Playwright is not set up yet, the first UI slice should add `playwright.config.ts`,
+       a minimal smoke spec (for example `e2e/smoke.spec.ts`), and a safe verify command
+     - Slice closeout UAT must declare `browser-executable` or `runtime-executable` — not
+       `artifact-driven` — when checks navigate to localhost or exercise the live UI
+
      If the project has no test framework and the work is non-trivial,
      the first task should set one up. A test runner costs 2 minutes
      and pays for itself immediately.

package/dist/resources/extensions/gsd/templates/project.md

@@ -20,6 +20,7 @@
 
 - **Complexity:** {{simple | complex}}
 - **Why:** {{one-line rationale citing the signals that decided it}}
+- **Web stack:** {{browser-facing framework or "not a web UI" — e.g. Next.js + Playwright, static HTML, N/A for CLI/API-only}}
 
 ## Current State
 

package/dist/resources/extensions/gsd/templates/roadmap.md

@@ -42,7 +42,7 @@
 - Contract verification: {{tests / shell verifiers / fixtures / artifact checks}}
 - Integration verification: {{real subsystem interaction that must be exercised, or none}}
 - Operational verification: {{service lifecycle / restart / reconnect / supervision / deploy-install behavior, or none}}
-- UAT / human verification: {{what needs real human judgment, or none}}
+- UAT / human verification: {{what needs real human judgment, or none — for web apps prefer browser-executable / runtime-executable Playwright checks over deferring UI proof to humans}}
 
 ## Milestone Definition of Done
 

package/dist/resources/extensions/gsd/templates/uat.md

@@ -5,9 +5,13 @@
 
 ## UAT Type
 
-- UAT mode: {{artifact-driven | live-runtime | human-experience | mixed}}
+- UAT mode: {{artifact-driven | browser-executable | runtime-executable | live-runtime | human-experience | mixed}}
 - Why this mode is sufficient: {{reason}}
 
+<!-- Web apps: never use artifact-driven when steps open a browser, navigate to localhost,
+     or capture screenshots. Use browser-executable (browser_* tools) or runtime-executable
+     (npx playwright test). Name dev-server preconditions below. -->
+
 ## Preconditions
 
 {{whatMustBeTrueBeforeTesting — server running, data seeded, etc.}}

package/dist/resources/extensions/gsd/tool-contract.js

@@ -1,9 +1,31 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Tool Contract module for Unit prompt, policy, and tool parity.
 import { resolveManifest, } from "./unit-context-manifest.js";
-import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
-import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
+import { getWorkflowTransportSupportError, } from "./workflow-mcp.js";
+import { getRequiredWorkflowToolsForUnit, getUnitToolSurfaceContract, } from "./unit-tool-contracts.js";
 import { WHOLE_FILE_OBSERVATION_MAX_BYTES, WHOLE_FILE_OBSERVATION_MAX_LINES, } from "./source-observations.js";
+export function compileUnitContextContract(unitType) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest) {
+        return {
+            ok: false,
+            reason: "unknown-unit-type",
+            detail: `No Unit manifest is registered for ${unitType}`,
+        };
+    }
+    return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
+}
+export function getUnitWorkflowDispatchReadinessError(input) {
+    return getWorkflowTransportSupportError(input.provider, getRequiredWorkflowToolsForUnit(input.unitType), {
+        projectRoot: input.projectRoot,
+        env: input.env,
+        surface: input.surface,
+        unitType: input.unitType,
+        authMode: input.authMode,
+        baseUrl: input.baseUrl,
+        activeTools: input.activeTools,
+    });
+}
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
     const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -14,7 +36,7 @@ export function compileUnitToolContract(unitType) {
             detail: `No Unit manifest is registered for ${unitType}`,
         };
     }
-    const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+    const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType);
     const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
         .map(([name, reason]) => ({ name, reason }));
     const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool));
@@ -25,6 +47,7 @@ export function compileUnitToolContract(unitType) {
             detail: `${unitType} has no closeout workflow tool`,
         };
     }
+    const promptContext = buildPromptContextContract(unitType, manifest);
     return {
         ok: true,
         contract: {
@@ -33,10 +56,8 @@ export function compileUnitToolContract(unitType) {
             toolsPolicy: manifest.tools,
             requiredWorkflowTools,
             forbiddenWorkflowTools,
-            promptObligations: [
-                `context-mode:${manifest.contextMode}`,
-                `tools-policy:${manifest.tools.mode}`,
-            ],
+            promptObligations: promptContext.obligations,
+            promptContext,
             validationRules: [
                 "unit-manifest-present",
                 "workflow-tool-surface-present",
@@ -44,15 +65,49 @@ export function compileUnitToolContract(unitType) {
                 ...(unitType === "execute-task" ? ["source-observation-contract-present"] : []),
             ],
             closeoutTools,
-            sourceObservations: sourceObservationContractForUnit(unitType),
+            sourceObservations: promptContext.sourceObservations,
             artifacts: {
-                inline: manifest.artifacts.inline,
-                excerpt: manifest.artifacts.excerpt,
-                onDemand: manifest.artifacts.onDemand,
+                inline: promptContext.artifacts.inline,
+                excerpt: promptContext.artifacts.excerpt,
+                onDemand: promptContext.artifacts.onDemand,
             },
         },
     };
 }
+function buildPromptContextContract(unitType, manifest) {
+    const sourceObservations = sourceObservationContractForUnit(unitType);
+    return {
+        unitType,
+        contextMode: manifest.contextMode,
+        toolsPolicy: manifest.tools,
+        obligations: promptContextObligations(manifest, sourceObservations),
+        sourceObservations,
+        artifacts: {
+            inline: manifest.artifacts.inline,
+            excerpt: manifest.artifacts.excerpt,
+            onDemand: manifest.artifacts.onDemand,
+            computed: manifest.artifacts.computed ?? [],
+            prepend: manifest.prepend ?? [],
+        },
+        maxSystemPromptChars: manifest.maxSystemPromptChars,
+    };
+}
+function promptContextObligations(manifest, sourceObservations) {
+    const obligations = [
+        `context-mode:${manifest.contextMode}`,
+        `tools-policy:${manifest.tools.mode}`,
+        artifactObligation("context-inline", manifest.artifacts.inline),
+        artifactObligation("context-excerpt", manifest.artifacts.excerpt),
+        artifactObligation("context-on-demand", manifest.artifacts.onDemand),
+    ];
+    if (sourceObservations.mode !== "none") {
+        obligations.push(`source-observations:${sourceObservations.mode}`);
+    }
+    return obligations;
+}
+function artifactObligation(label, artifacts) {
+    return `${label}:${artifacts.length > 0 ? artifacts.join(",") : "none"}`;
+}
 function sourceObservationContractForUnit(unitType) {
     if (unitType !== "execute-task")
         return { mode: "none" };

package/dist/resources/extensions/gsd/tool-presentation-plan.js

@@ -1,7 +1,10 @@
 // Project/App: gsd-pi
 // File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
 import { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
+import { toMcpToolName } from "./mcp-tool-name.js";
+import { createToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 export { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
 export const RUN_UAT_FORBIDDEN_TOOL_NAMES = [
     "edit",
@@ -21,43 +24,12 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
     "Glob",
     "Grep",
 ];
-const WORKFLOW_ALIAS_TO_CANONICAL = {
-    gsd_save_decision: "gsd_decision_save",
-    gsd_update_requirement: "gsd_requirement_update",
-    gsd_save_requirement: "gsd_requirement_save",
-    gsd_save_summary: "gsd_summary_save",
-    gsd_generate_milestone_id: "gsd_milestone_generate_id",
-    gsd_milestone_plan: "gsd_plan_milestone",
-    gsd_slice_plan: "gsd_plan_slice",
-    gsd_task_plan: "gsd_plan_task",
-    gsd_slice_replan: "gsd_replan_slice",
-    gsd_complete_slice: "gsd_slice_complete",
-    gsd_milestone_complete: "gsd_complete_milestone",
-    gsd_milestone_validate: "gsd_validate_milestone",
-    gsd_roadmap_reassess: "gsd_reassess_roadmap",
-    gsd_complete_task: "gsd_task_complete",
-    gsd_reopen_task: "gsd_task_reopen",
-    gsd_reopen_slice: "gsd_slice_reopen",
-    gsd_reopen_milestone: "gsd_milestone_reopen",
-};
-export function canonicalWorkflowToolName(toolName) {
-    const mcp = parseMcpToolName(toolName);
-    const baseName = mcp?.tool ?? toolName;
-    return WORKFLOW_ALIAS_TO_CANONICAL[baseName] ?? baseName;
-}
-export function parseMcpToolName(toolName) {
-    if (!toolName.startsWith("mcp__"))
-        return null;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    if (toolSeparator < 0)
-        return null;
-    return {
-        server: toolName.slice("mcp__".length, toolSeparator),
-        tool: toolName.slice(toolSeparator + 2),
-    };
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing presentation importers (uat-run.ts).
+export { canonicalWorkflowToolName };
+export { parseMcpToolName } from "./mcp-tool-name.js";
 export function toWorkflowMcpToolName(serverName, toolName) {
-    return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+    return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));
 }
 function dedupe(values) {
     return [...new Set(values)];
@@ -134,6 +106,14 @@ export function resolveToolPresentationPlan(options) {
             ? toWorkflowMcpToolName(workflowServerName, name)
             : name)
         : allowedToolNames;
+    const toolSurface = createToolSurfaceSnapshot({
+        source: "presentation-plan",
+        phase: options.phase,
+        modelFacingToolNames: options.availableToolNames ?? requested,
+        registeredToolNames: options.availableToolNames ?? requested,
+        scopedToolNames: allowedToolNames,
+        presentedToolNames,
+    });
     if (options.phase === "run-uat") {
         for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
             addBlockedTool(blockedToolNames, forbidden, "forbidden during run-uat");
@@ -148,5 +128,6 @@ export function resolveToolPresentationPlan(options) {
         blockedToolNames,
         aliases,
         diagnostics: [],
+        toolSurface,
     };
 }

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

@@ -0,0 +1,56 @@
+// Project/App: gsd-pi
+// File Purpose: Tool Contract module's runtime face — verify the live SDK tool surface covers a Unit's required workflow tools.
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+/**
+ * Stable phrase recognized as transient by auto-tool-tracking's
+ * isToolUnavailableError and error-classifier's transient buckets,
+ * which build their matchers from this constant.
+ */
+export const TOOL_SURFACE_NOT_READY = "workflow tool surface not ready";
+/** MCP server statuses that will not self-heal within the session. */
+const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
+/**
+ * Verify the live tool surface observed at SDK session init covers the Unit's
+ * required workflow tools. Complements the static pre-dispatch gate
+ * (getWorkflowTransportSupportError), which only proves the MCP launch config
+ * is discoverable — the workflow server connects asynchronously after session
+ * start, so the static gate cannot see whether the tools actually registered.
+ *
+ * Returns a transient, recovery-classifiable error (kind tool-unavailable →
+ * retry) when the workflow server failed or has not yet registered a required
+ * tool, so dispatch aborts before the first model turn instead of letting the
+ * Unit improvise around "No such tool available". Returns null when no
+ * workflow server is part of this session (native tool path), when the Unit
+ * requires no workflow tools, or when the surface is ready.
+ */
+export function getToolSurfaceReadinessError(input) {
+    const { unitType, workflowServerName, observation } = input;
+    if (!unitType || !workflowServerName)
+        return null;
+    const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+    if (required.length === 0)
+        return null;
+    const server = observation.mcpServers.find((entry) => entry.name === workflowServerName);
+    if (!server) {
+        return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is absent from the init surface (not yet connected): ${required.join(", ")}`;
+    }
+    // The SDK does not wait for MCP servers before init — a still-connecting
+    // server reports "pending" there routinely, then registers within seconds,
+    // usually well before the Unit's first workflow tool call. Aborting on
+    // "pending" would fail the common healthy session, so it passes through;
+    // a genuine miss after pass-through still surfaces in-session as
+    // "No such tool available" and classifies tool-unavailable → bounded retry.
+    // Only statuses that cannot self-heal abort here.
+    if (server.status !== "connected" && !TERMINAL_MCP_SERVER_STATUSES.has(server.status)) {
+        return null;
+    }
+    const missing = required.filter((tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
+    if (missing.length === 0)
+        return null;
+    const serverDetail = server.status === "connected"
+        ? `MCP server "${workflowServerName}" is connected but has not registered`
+        : `MCP server "${workflowServerName}" status is "${server.status}" and it has not registered`;
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: ${serverDetail}: ${missing.join(", ")}`;
+}

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

@@ -0,0 +1,17 @@
+// Project/App: gsd-pi
+// File Purpose: Typed snapshots for model-facing, registered, scoped, and presented tool surfaces.
+function dedupeToolNames(toolNames) {
+    return [...new Set(toolNames ?? [])];
+}
+export function createToolSurfaceSnapshot(input) {
+    return {
+        source: input.source,
+        unitType: input.unitType,
+        phase: input.phase,
+        modelFacingToolNames: dedupeToolNames(input.modelFacingToolNames),
+        registeredToolNames: dedupeToolNames(input.registeredToolNames),
+        scopedToolNames: dedupeToolNames(input.scopedToolNames),
+        presentedToolNames: dedupeToolNames(input.presentedToolNames),
+        capturedAt: input.capturedAt ?? Date.now(),
+    };
+}

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

@@ -16,7 +16,8 @@ import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { isClosedStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js";
+import { stripIdPrefix } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -166,7 +167,7 @@ export async function handleCompleteMilestone(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await renderAllProjections(artifactBasePath, params.milestoneId);
+        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
     }
     catch (projErr) {
         logWarning("tool", `complete-milestone projection warning: ${projErr.message}`);

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

@@ -11,19 +11,17 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { isClosedStatus } from "../status-guards.js";
-import { transaction, insertMilestone, insertSlice, getSlice, getSliceTasks, getMilestone, updateSliceStatus, setSliceSummaryMd, saveGateResult, getPendingGatesForTurn, getMilestoneSlices, updateMilestoneStatus, } from "../gsd-db.js";
+import { completeSliceCascade, setSliceSummaryMd, saveGateResult, getPendingGatesForTurn, } from "../gsd-db.js";
 import { getGatesForTurn } from "../gate-registry.js";
 import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
-import { getDeclaredUatType, shouldEscalateArtifactUatToBrowser } from "../uat-policy.js";
+import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy.js";
 import { invalidateStateCache } from "../state.js";
-import { renderRoadmapFromDb } from "../markdown-renderer.js";
-import { parseRoadmap } from "../parsers-legacy.js";
+import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.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, logError } from "../workflow-logger.js";
@@ -56,9 +54,11 @@ function hasCompleteSliceArtifactContract(basePath, milestoneId, sliceId) {
         join(gsdProjectionRoot(basePath), "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
     if (!existsSync(roadmapPath))
         return false;
+    // Projection-completeness check (ADR-017): the DB has already recorded the
+    // duplicate completion; this only verifies the rendered markdown artifacts
+    // exist and reflect it, deciding whether re-rendering is needed.
     try {
-        const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-        return roadmap.slices.some((slice) => slice.id === sliceId && slice.done);
+        return roadmapRenderMarksSliceDone(readFileSync(roadmapPath, "utf-8"), sliceId);
     }
     catch {
         return false;
@@ -289,58 +289,48 @@ export async function handleCompleteSlice(params, basePath) {
     // `npx playwright test` via gsd_uat_exec, and live-runtime/mixed/
     // browser-executable receive browser tools (UAT_MODE_POLICIES).
     const uatContent = params.uatContent || "";
-    const declaredUatMode = getDeclaredUatType(uatContent);
-    if (shouldEscalateArtifactUatToBrowser(uatContent)) {
+    const uatPolicy = classifyUatContent(uatContent);
+    if (escalatesArtifactUatToBrowser(uatPolicy)) {
+        // Distinguish an explicit artifact-driven declaration from a missing or
+        // unparseable one that merely *defaulted* to artifact-driven — telling an
+        // agent it "declared artifact-driven" when its declaration simply failed
+        // to parse sends it into a rewrite loop with the same unparseable format.
+        const staticOnlyClause = `which only runs static/file checks and would defer the browser work to a human`;
+        const modeClause = uatPolicy.modeDeclared
+            ? `declares "UAT mode: artifact-driven", ${staticOnlyClause}`
+            : `has no parseable UAT mode declaration in its "## UAT Type" section (the declaration must be a bullet exactly like "- UAT mode: browser-executable"), so it defaults to "artifact-driven", ${staticOnlyClause}`;
         return {
-            error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but declares "UAT mode: artifact-driven", which only runs static/file checks and would defer the browser work to a human. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
+            error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but ${modeClause}. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
         };
     }
-    // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+    // ── Atomic completion cascade (guards + writes in one transaction) ───────
     const completedAt = new Date().toISOString();
     let guardError = null;
     let existingSummaryMd = "";
     let duplicateComplete = false;
-    transaction(() => {
-        // State machine preconditions (inside txn for atomicity).
-        // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
-        // Only block if they exist and are closed.
-        const milestone = getMilestone(params.milestoneId);
-        if (milestone && isClosedStatus(milestone.status)) {
-            guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
-            return;
-        }
-        const slice = getSlice(params.milestoneId, params.sliceId);
-        existingSummaryMd = slice?.full_summary_md?.trim() ?? "";
-        if (slice && isClosedStatus(slice.status)) {
-            duplicateComplete = true;
-            return;
-        }
-        // Verify all tasks are complete
-        const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-        if (tasks.length === 0) {
-            guardError = `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}`;
-            return;
-        }
-        const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
-        if (incompleteTasks.length > 0) {
-            const incompleteIds = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
-            guardError = `incomplete tasks: ${incompleteIds}`;
-            return;
-        }
-        // All guards passed — perform writes. Preserve existing planning metadata:
-        // completion should not overwrite title/risk/depends/demo/sequence.
-        insertMilestone({ id: params.milestoneId, title: params.milestoneId });
-        if (!slice) {
-            insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceTitle || params.sliceId });
-        }
-        updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
-        const updatedSlices = getMilestoneSlices(params.milestoneId);
-        if (milestone?.status === "planned" &&
-            updatedSlices.length > 0 &&
-            updatedSlices.every((s) => isClosedStatus(s.status))) {
-            updateMilestoneStatus(params.milestoneId, "active");
-        }
+    const outcome = completeSliceCascade(params.milestoneId, params.sliceId, {
+        sliceTitle: params.sliceTitle,
+        completedAt,
     });
+    if (outcome.ok) {
+        existingSummaryMd = outcome.existingSummaryMd;
+        duplicateComplete = outcome.duplicate;
+    }
+    else {
+        switch (outcome.reason) {
+            case "milestone-closed":
+                guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${outcome.status})`;
+                break;
+            case "no-tasks":
+                guardError = `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}`;
+                break;
+            case "incomplete-tasks": {
+                const incompleteIds = outcome.incomplete.map((t) => `${t.id} (status: ${t.status})`).join(", ");
+                guardError = `incomplete tasks: ${incompleteIds}`;
+                break;
+            }
+        }
+    }
     if (duplicateComplete) {
         const staleSummaryPath = sliceSummaryPath(artifactBasePath, params.milestoneId, params.sliceId);
         const duplicateIsStale = isStaleWrite("complete-slice");
@@ -407,8 +397,9 @@ export async function handleCompleteSlice(params, basePath) {
         await saveFile(uatPath, uatMd);
         const roadmap = await renderRoadmapFromDb(artifactBasePath, params.milestoneId);
         clearParseCache();
-        const roadmapSlice = parseRoadmap(roadmap.content).slices.find((slice) => slice.id === params.sliceId);
-        if (!roadmapSlice?.done) {
+        // Render verification (ADR-017): confirms the just-written projection
+        // reflects the DB completion; the DB row is already committed.
+        if (!roadmapRenderMarksSliceDone(roadmap.content, params.sliceId)) {
             throw new Error(`roadmap render did not mark ${params.milestoneId}/${params.sliceId} complete`);
         }
     }
@@ -457,7 +448,7 @@ export async function handleCompleteSlice(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await renderAllProjections(artifactBasePath, params.milestoneId);
+        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
     }
     catch (projErr) {
         logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${projErr.message}`);

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

@@ -18,7 +18,8 @@ import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanCheckboxes } from "../markdown-renderer.js";
-import { renderAllProjections, renderSummaryContent } from "../workflow-projections.js";
+import { renderSummaryContent } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -358,7 +359,7 @@ export async function handleCompleteTask(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await renderAllProjections(artifactBasePath, params.milestoneId);
+        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
     }
     catch (projErr) {
         logWarning("tool", `complete-task projection warning: ${projErr.message}`);