@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

package/dist/resources/extensions/gsd/quality-gate-closure.js

@@ -0,0 +1,109 @@
+// Project/App: gsd-pi
+// File Purpose: Canonical quality-gate closure from durable DB and artifact evidence.
+import { existsSync, readFileSync } from "node:fs";
+import { extractSection } from "./files.js";
+import { getGateDefinition } from "./gate-registry.js";
+import { getMilestoneSlices, getPendingGates, saveGateResult } from "./gsd-db.js";
+import { resolveSliceFile, resolveTaskFile } from "./paths.js";
+const GATE_SECTION_HEADINGS = {
+    Q3: ["Threat Surface", "Abuse Surface"],
+    Q4: ["Requirement Impact", "Broken Promises"],
+    Q5: ["Failure Modes"],
+    Q6: ["Load Profile"],
+    Q7: ["Negative Tests"],
+    Q8: ["Operational Readiness"],
+};
+function readFile(path) {
+    if (!path || !existsSync(path))
+        return null;
+    return readFileSync(path, "utf-8");
+}
+function firstSection(content, gateId) {
+    if (!content)
+        return null;
+    for (const heading of GATE_SECTION_HEADINGS[gateId] ?? []) {
+        const section = extractSection(content, heading);
+        if (section)
+            return section;
+    }
+    return null;
+}
+function evidenceArtifactContent(row, basePath) {
+    const def = getGateDefinition(row.gate_id);
+    switch (def?.ownerTurn) {
+        case "gate-evaluate":
+            return readFile(resolveSliceFile(basePath, row.milestone_id, row.slice_id, "PLAN"));
+        case "execute-task":
+            return readFile(resolveTaskFile(basePath, row.milestone_id, row.slice_id, row.task_id, "SUMMARY"));
+        case "complete-slice":
+            return readFile(resolveSliceFile(basePath, row.milestone_id, row.slice_id, "SUMMARY"));
+        default:
+            return null;
+    }
+}
+function closureEvidence(row, options) {
+    const def = getGateDefinition(row.gate_id);
+    if (!def)
+        return null;
+    if (def.ownerTurn === "validate-milestone" && options.milestoneValidationPassed) {
+        return {
+            verdict: "pass",
+            rationale: `${def.promptSection} covered by passing milestone validation`,
+            findings: "",
+        };
+    }
+    if (!options.artifactBasePath)
+        return null;
+    const section = firstSection(evidenceArtifactContent(row, options.artifactBasePath), row.gate_id);
+    if (section) {
+        return {
+            verdict: "pass",
+            rationale: `${def.promptSection} evidence found in durable artifact`,
+            findings: section,
+        };
+    }
+    if (!options.milestoneValidationPassed)
+        return null;
+    return {
+        verdict: "omitted",
+        rationale: `${def.promptSection} has no durable artifact section; milestone validation passed`,
+        findings: "",
+    };
+}
+function closeGate(row, evidence) {
+    saveGateResult({
+        milestoneId: row.milestone_id,
+        sliceId: row.slice_id,
+        gateId: row.gate_id,
+        taskId: row.task_id,
+        verdict: evidence.verdict,
+        rationale: evidence.rationale,
+        findings: evidence.findings,
+    });
+}
+export function closeQualityGatesFromEvidence(milestoneId, options = {}) {
+    const repaired = [];
+    const unresolved = [];
+    for (const slice of getMilestoneSlices(milestoneId)) {
+        const sliceId = slice.id;
+        for (const row of getPendingGates(milestoneId, sliceId)) {
+            if (!getGateDefinition(row.gate_id)) {
+                unresolved.push(row);
+                continue;
+            }
+            const evidence = closureEvidence(row, options);
+            if (!evidence) {
+                unresolved.push(row);
+                continue;
+            }
+            closeGate(row, evidence);
+            repaired.push({
+                gateId: row.gate_id,
+                sliceId: row.slice_id,
+                ...(row.task_id ? { taskId: row.task_id } : {}),
+                verdict: evidence.verdict,
+            });
+        }
+    }
+    return { repaired, unresolved };
+}

package/dist/resources/extensions/gsd/question-transport.js

@@ -0,0 +1,86 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve how workflow units should ask the user for input.
+import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
+function isWorkflowMcpServerName(serverName) {
+    const normalized = serverName.toLowerCase();
+    return normalized === "gsd" || normalized.includes("workflow");
+}
+export function usesWorkflowMcpTransport(authMode, baseUrl) {
+    return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
+}
+export function hasAskUserQuestionsTool(activeTools) {
+    return activeTools.some((toolName) => {
+        if (toolName === "ask_user_questions")
+            return true;
+        const mcp = parseMcpToolName(toolName);
+        if (!mcp)
+            return false;
+        if (mcp.toolName === "ask_user_questions")
+            return true;
+        return mcp.toolName === "*" && isWorkflowMcpServerName(mcp.serverName);
+    });
+}
+function workflowMcpStructuredQuestionsEnabled(env = process.env) {
+    const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS?.trim().toLowerCase();
+    return value !== "0" && value !== "false" && value !== "off";
+}
+export function resolveQuestionTransport(options) {
+    const questionToolAvailable = hasAskUserQuestionsTool(options.activeTools);
+    const usesWorkflowMcp = usesWorkflowMcpTransport(options.authMode, options.baseUrl);
+    if (!questionToolAvailable) {
+        return {
+            structuredQuestionsAvailable: "false",
+            questionToolAvailable,
+            usesWorkflowMcp,
+            reason: "question-tool-missing",
+        };
+    }
+    if (options.authMode === "externalCli" && !workflowMcpStructuredQuestionsEnabled(options.env)) {
+        return {
+            structuredQuestionsAvailable: "false",
+            questionToolAvailable,
+            usesWorkflowMcp,
+            reason: "workflow-mcp-disabled",
+        };
+    }
+    return {
+        structuredQuestionsAvailable: "true",
+        questionToolAvailable,
+        usesWorkflowMcp,
+        reason: "question-tool-available",
+    };
+}
+export function supportsStructuredQuestions(activeTools, options = {}) {
+    return resolveQuestionTransport({
+        ...options,
+        activeTools,
+    }).structuredQuestionsAvailable === "true";
+}
+export function resolveWorkflowQuestionToolSurface(options) {
+    const questionToolName = options.workflowServerName && !options.workflowExplicitlyBlocked
+        ? toMcpToolName(options.workflowServerName, "ask_user_questions")
+        : undefined;
+    const activeTools = [
+        ...options.exactWorkflowMcpTools,
+        ...options.workflowMcpTools,
+        ...(questionToolName ? [questionToolName] : []),
+    ];
+    const transport = resolveQuestionTransport({
+        activeTools,
+        authMode: "externalCli",
+        baseUrl: "local://claude-code",
+        env: options.env,
+    });
+    const exactQuestionToolAllowed = !!questionToolName && options.exactWorkflowMcpTools.includes(questionToolName);
+    const workflowQuestionsEnabled = transport.structuredQuestionsAvailable === "true" &&
+        (options.workflowMcpTools.length > 0 || exactQuestionToolAllowed);
+    const disallowedTools = options.workflowServerName && transport.questionToolAvailable && !workflowQuestionsEnabled
+        ? [toMcpToolName(options.workflowServerName, "ask_user_questions")]
+        : [];
+    return {
+        ...transport,
+        questionToolName,
+        workflowQuestionsEnabled,
+        disallowedTools,
+    };
+}

package/dist/resources/extensions/gsd/roadmap-slices.js

@@ -191,9 +191,15 @@ export function parseRoadmapSlices(content) {
             const riskMatch = rest.match(/`risk:(\w+)`/);
             const risk = (riskMatch ? riskMatch[1] : "low");
             const depsMatch = rest.match(/`depends:\[([^\]]*)\]`/);
-            const depends = depsMatch && depsMatch[1].trim()
-                ? expandDependencies(depsMatch[1].split(",").map(s => s.trim()))
+            // Recovery fallback: double-bracket form `[[id]]` from serialized bracket-wrapped IDs
+            const fallbackDepsMatch = depsMatch ? null : rest.match(/`depends:\[(\[(?:[^\]]*)\](?:,\[(?:[^\]]*)\])*)\]`/);
+            const rawDepContent = (depsMatch ?? fallbackDepsMatch)?.[1] ?? "";
+            const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+            const RANGE_RE = /^[A-Za-z]+\d+(?:-|\.\.)[A-Za-z]+\d+$/;
+            const rawDepParts = rawDepContent.trim()
+                ? rawDepContent.replace(/\[|\]/g, "").split(",").map(s => s.trim()).filter(s => SLICE_ID_RE.test(s) || RANGE_RE.test(s))
                 : [];
+            const depends = expandDependencies(rawDepParts);
             // ADR-011: the renderer writes a `[sketch]` badge for sketch slices.
             // Parse it back so the is_sketch flag survives a markdown → DB re-import
             // (e.g. /gsd recover); otherwise the flag was silently lost.

package/dist/resources/extensions/gsd/schemas/parsers.js

@@ -6,7 +6,12 @@
 const TEMPLATE_TOKEN_RE = /\{\{[^}]+\}\}/;
 const H2_RE = /^##\s+(.+)$/gm;
 const H3_RE = /^###\s+(.+)$/gm;
-const MILESTONE_LINE_RE = /^-\s+\[([ x])\]\s+(M\d{3}):\s+(.+?)\s+(?:—|--|-)\s+(.+)$/gm;
+// A milestone line is single-line by construction. Every inter-token gap uses
+// horizontal-whitespace classes (`[^\S\n]`) rather than `\s`, because `\s`
+// matches newlines: a line missing a valid separator would otherwise let the
+// `\s+(?:—|--|-)\s+` clause "bridge" onto the NEXT bullet's `- `, consuming it
+// as the separator and silently swallowing the following well-formed milestone.
+const MILESTONE_LINE_RE = /^-[^\S\n]+\[([ x])\][^\S\n]+(M\d{3}):[^\S\n]+(.+?)[^\S\n]+(?:—|--|-)[^\S\n]+(.+)$/gm;
 const SLICE_HEADER_RE = /^###\s+(S\d{2})\s*(?:—|--|-)\s+(.+)$/m;
 const REQUIREMENT_HEADER_RE = /^###\s+(R\d{3})\s*(?:—|--|-)\s+(.+)$/m;
 function splitH2Sections(content) {

package/dist/resources/extensions/gsd/slice-parallel-orchestrator.js

@@ -19,7 +19,8 @@ import { isAbsolute, join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath, removeWorktree } from "./worktree-manager.js";
-import { runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { writeSessionStatus, } from "./session-status-io.js";
 import { hasFileConflict } from "./slice-parallel-conflict.js";
 import { getErrorMessage } from "./error-utils.js";
@@ -108,7 +109,7 @@ function createSliceWorktree(basePath, milestoneId, sliceId) {
     if (hookError) {
         throw new Error(`slice worktree post-create hook failed (${wtName}): ${hookError}`);
     }
-    syncGsdStateToWorktree(basePath, wtPath);
+    syncGsdStateToWorktreeByScope(scopeMilestone(createWorkspace(basePath), milestoneId), scopeMilestone(createWorkspace(wtPath), milestoneId));
     if (!existsSync(join(wtPath, ".gsd"))) {
         throw new Error(`slice worktree preflight failed (${wtName}): missing .gsd in worktree`);
     }

package/dist/resources/extensions/gsd/state-reconciliation/drift/artifact-db.js

@@ -250,7 +250,27 @@ function detectDiskSliceIdDivergenceForMilestone(basePath, milestoneId) {
     }
     return drifts;
 }
-export function detectArtifactDbDrift(_state, ctx) {
+// #442 Phase 1.6: the three artifact/DB drift handlers (disk-slice-id,
+// artifact-db-status, completed-milestone-reopened) each call
+// detectArtifactDbDrift and then filter for their own kind — so the full
+// milestone→slice→task walk + artifact SQL + disk scan would run THREE times
+// per detection pass and discard 2/3 of the work. Memoize the result per
+// DriftContext so the three handlers share one computation. The key is the
+// ctx object, which detectAllDrift rebuilds for every pass (and which is
+// unreferenced once the pass ends, so the WeakMap entry is GC'd) — DB/disk
+// state is immutable within a single pass (repairs run only after detection),
+// so this is behavior-preserving. A fresh ctx (e.g. the maintenance command's
+// inline { basePath, state }) always recomputes.
+const _artifactDbDriftMemo = new WeakMap();
+export function detectArtifactDbDrift(state, ctx) {
+    const cached = _artifactDbDriftMemo.get(ctx);
+    if (cached)
+        return cached;
+    const computed = computeArtifactDbDrift(state, ctx);
+    _artifactDbDriftMemo.set(ctx, computed);
+    return computed;
+}
+function computeArtifactDbDrift(_state, ctx) {
     if (!isDbAvailable())
         return [];
     const drifts = [];

package/dist/resources/extensions/gsd/state.js

@@ -18,8 +18,10 @@ import { logWarning } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { detectPendingEscalation } from './escalation.js';
 import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
-import { isDbAvailable, wasDbOpenAttempted, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
+import { isDbAvailable, getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, getRequirementCounts, getLatestAssessmentByScope, getPendingGateCountForTurn, } from './gsd-db.js';
+import { wasWorkflowDatabaseOpenAttempted } from './db-workspace.js';
 import { formatCompletePhaseNextAction, countUnmappedActiveRequirements } from './requirements-backlog.js';
+import { classifyMilestoneReadiness, readinessNeedsDiscussion, } from './milestone-readiness.js';
 function formatNeedsAttentionBlocker(milestoneId) {
     return [
         `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
@@ -301,7 +303,7 @@ export async function deriveState(basePath, opts) {
         _telemetry.dbDeriveCount++;
     }
     else {
-        if (wasDbOpenAttempted()) {
+        if (wasWorkflowDatabaseOpenAttempted()) {
             logWarning("state", "DB unavailable — refusing implicit markdown state derivation");
         }
         result = {
@@ -396,6 +398,12 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
         const title = stripMilestonePrefix(m.title) || m.id;
         const hasContext = !!resolveMilestoneFile(basePath, m.id, "CONTEXT");
         const hasDraftContext = !hasContext && !!resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
+        const readiness = classifyMilestoneReadiness({
+            status: m.status,
+            hasContext,
+            hasDraftContext,
+            sliceCount: slices.length,
+        });
         if (!activeMilestoneFound) {
             const deps = m.depends_on;
             const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
@@ -403,9 +411,9 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'pending', dependsOn: deps });
                 continue;
             }
-            if (m.status === 'queued' && slices.length === 0 && !hasContext) {
+            if (readiness.kind === 'queued-shell') {
                 if (!firstDeferredQueuedShell) {
-                    firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext };
+                    firstDeferredQueuedShell = { id: m.id, title, deps, hasDraftContext: readiness.hasDraftContext };
                 }
                 registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
                 continue;
@@ -417,7 +425,7 @@ async function buildRegistryAndFindActive(basePath, milestones, completeMileston
                 registry.push({ id: m.id, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
                 continue;
             }
-            if ((m.status === 'needs-discussion' && !hasContext) || hasDraftContext)
+            if (readinessNeedsDiscussion(readiness))
                 activeMilestoneHasDraft = true;
             activeMilestone = { id: m.id, title };
             activeMilestoneSlices = slices;

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

@@ -4,6 +4,17 @@ import { resolveManifest, } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
 import { 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 compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
     const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -25,6 +36,7 @@ export function compileUnitToolContract(unitType) {
             detail: `${unitType} has no closeout workflow tool`,
         };
     }
+    const promptContext = buildPromptContextContract(unitType, manifest);
     return {
         ok: true,
         contract: {
@@ -33,10 +45,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 +54,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 { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.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),
-    };
+    return canonicalWorkflowSurfaceToolName(toolName);
 }
+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-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(),
+    };
+}