@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.75048e7

package/dist/resources/extensions/gsd/skill-activation.js

@@ -41,6 +41,16 @@ function tokenizeSkillContext(...parts) {
     }
     return tokens;
 }
+function tokenizeUnitType(unitType) {
+    const tokens = new Set();
+    const value = unitType?.trim().toLowerCase();
+    if (!value)
+        return tokens;
+    tokens.add(value);
+    tokens.add(value.replace(/[-_]+/g, " "));
+    tokens.add(value.replace(/[-_\s]+/g, ""));
+    return tokens;
+}
 function skillMatchesContext(skill, contextTokens) {
     const haystacks = [
         skill.name.toLowerCase(),
@@ -63,13 +73,20 @@ function ruleMatchesContext(when, contextTokens) {
     const whenTokens = tokenizeSkillContext(when);
     return [...whenTokens].some(token => contextTokens.has(token) || [...contextTokens].some(ctx => ctx.includes(token) || token.includes(ctx)));
 }
-function resolveSkillRuleMatches(prefs, contextTokens, base) {
+function ruleMatchesUnitType(when, unitType) {
+    if (!unitType)
+        return false;
+    const whenTokens = tokenizeSkillContext(when);
+    const unitTokens = tokenizeUnitType(unitType);
+    return [...unitTokens].some(token => whenTokens.has(token));
+}
+function resolveSkillRuleMatches(prefs, contextTokens, base, unitType) {
     if (!prefs?.skill_rules?.length)
         return { include: [], avoid: [] };
     const include = [];
     const avoid = [];
     for (const rule of prefs.skill_rules) {
-        if (!ruleMatchesContext(rule.when, contextTokens))
+        if (!ruleMatchesContext(rule.when, contextTokens) && !ruleMatchesUnitType(rule.when, unitType))
             continue;
         include.push(...resolvePreferenceSkillNames([...(rule.use ?? []), ...(rule.prefer ?? [])], base));
         avoid.push(...resolvePreferenceSkillNames(rule.avoid ?? [], base));
@@ -141,7 +158,7 @@ export function buildSkillActivationBlock(params) {
     for (const name of resolvePreferenceSkillNames(prefs?.always_use_skills ?? [], params.base)) {
         matched.add(name);
     }
-    const ruleMatches = resolveSkillRuleMatches(prefs, contextTokens, params.base);
+    const ruleMatches = resolveSkillRuleMatches(prefs, contextTokens, params.base, params.unitType);
     for (const name of ruleMatches.include)
         matched.add(name);
     for (const name of ruleMatches.avoid)

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

@@ -313,7 +313,8 @@ export function repairArtifactDbDrift(record, ctx) {
     throw new Error(`Artifact/DB status drift in ${record.milestoneId}` +
         `${record.sliceId ? `/${record.sliceId}` : ""}` +
         `${record.taskId ? `/${record.taskId}` : ""}: ${record.reason}. ` +
-        "Runtime will not silently import completion artifacts into DB state; run explicit recovery/repair after review.");
+        "Runtime will not silently import completion artifacts into DB state. " +
+        "Run `/gsd rebuild markdown` after review to quarantine stale projections and re-render from the DB; use `/gsd recover --confirm` only when markdown should repopulate a lost or corrupt DB.");
 }
 export function describeArtifactDbDriftBlocker(record) {
     if (record.kind === "disk-slice-id-divergence") {
@@ -329,7 +330,8 @@ export function describeArtifactDbDriftBlocker(record) {
     return (`Artifact/DB status drift in ${record.milestoneId}` +
         `${record.sliceId ? `/${record.sliceId}` : ""}` +
         `${record.taskId ? `/${record.taskId}` : ""}: ${record.reason}. ` +
-        "Runtime will not silently import completion artifacts into DB state; run explicit recovery/repair after review.");
+        "Runtime will not silently import completion artifacts into DB state. " +
+        "Run `/gsd rebuild markdown` after review to quarantine stale projections and re-render from the DB; use `/gsd recover --confirm` only when markdown should repopulate a lost or corrupt DB.");
 }
 export const diskSliceIdDivergenceHandler = {
     kind: "disk-slice-id-divergence",

package/dist/resources/extensions/gsd/state-reconciliation/drift/project-md.js

@@ -36,7 +36,7 @@ export function detectUnregisteredMilestoneDrift(_state, ctx) {
  */
 export function repairUnregisteredMilestone(record, _ctx) {
     throw new Error(`Milestone ${record.milestoneId} exists only as markdown projection. ` +
-        "Runtime reconciliation will not import markdown into the authoritative DB; run `/gsd recover` if this markdown should repopulate the database.");
+        "Runtime reconciliation will not import markdown into the authoritative DB; run `/gsd recover --confirm` if this markdown should repopulate the database.");
 }
 export const unregisteredMilestoneHandler = {
     kind: "unregistered-milestone",

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

@@ -4,7 +4,7 @@
 // checkboxes) and the DB slice rows for that milestone, then re-renders the
 // ROADMAP projection from the authoritative DB rows.
 import { existsSync, readFileSync } from "node:fs";
-import { getMilestone, getMilestoneSlices, isDbAvailable, } from "../../gsd-db.js";
+import { getMilestone, getMilestoneSlices, getSliceTasks, isDbAvailable, } from "../../gsd-db.js";
 import { renderRoadmapFromDb } from "../../markdown-renderer.js";
 import { findMilestoneIds } from "../../milestone-ids.js";
 import { parseRoadmap } from "../../parsers-legacy.js";
@@ -18,6 +18,15 @@ function arraysEqual(a, b) {
             return false;
     return true;
 }
+function getSlicesReadyForDivergenceCheck(milestoneId, dbSlices) {
+    const ready = new Set();
+    for (const slice of dbSlices) {
+        if (isClosedStatus(slice.status) || getSliceTasks(milestoneId, slice.id).length > 0) {
+            ready.add(slice.id);
+        }
+    }
+    return ready;
+}
 function milestoneHasDivergence(basePath, milestoneId) {
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     if (!roadmapPath || !existsSync(roadmapPath))
@@ -31,6 +40,10 @@ function milestoneHasDivergence(basePath, milestoneId) {
     }
     const dbSlices = getMilestoneSlices(milestoneId);
     const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+    const readySliceIds = getSlicesReadyForDivergenceCheck(milestoneId, dbSlices);
+    if (dbSlices.length > 0 && readySliceIds.size === 0) {
+        return false;
+    }
     const roadmapSliceIds = new Set();
     for (let i = 0; i < roadmap.slices.length; i++) {
         const roadmapSlice = roadmap.slices[i];
@@ -39,6 +52,8 @@ function milestoneHasDivergence(basePath, milestoneId) {
         const dbSlice = dbSliceMap.get(roadmapSlice.id);
         if (!dbSlice)
             return true; // Roadmap has a slice the DB doesn't.
+        if (!readySliceIds.has(dbSlice.id))
+            continue;
         if (dbSlice.sequence !== expectedSequence)
             return true;
         if (!arraysEqual(dbSlice.depends, roadmapSlice.depends))
@@ -47,6 +62,8 @@ function milestoneHasDivergence(basePath, milestoneId) {
             return true;
     }
     for (const dbSlice of dbSlices) {
+        if (!readySliceIds.has(dbSlice.id))
+            continue;
         if (!roadmapSliceIds.has(dbSlice.id))
             return true;
     }

package/dist/resources/extensions/gsd/state-reconciliation/index.js

@@ -2,6 +2,7 @@
 // File Purpose: ADR-017 drift-driven State Reconciliation Module entry point.
 // reconcileBeforeDispatch runs before every Dispatch decision and worker spawn.
 import { deriveState as defaultDeriveState, invalidateStateCache as defaultInvalidate, } from "../state.js";
+import { clearParseCache as defaultClearParseCache } from "../files.js";
 import { ReconciliationFailedError, } from "./errors.js";
 import { DRIFT_REGISTRY } from "./registry.js";
 export { ReconciliationFailedError } from "./errors.js";
@@ -10,6 +11,7 @@ const MAX_PASSES = 2;
 const defaultDeps = {
     invalidateStateCache: defaultInvalidate,
     deriveState: defaultDeriveState,
+    clearParseCache: defaultClearParseCache,
 };
 /**
  * Drift-driven pre-dispatch reconciliation per ADR-017.
@@ -27,6 +29,7 @@ const defaultDeps = {
  */
 export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
     const registry = deps.registry ?? DRIFT_REGISTRY;
+    const clearParseCache = deps.clearParseCache ?? defaultClearParseCache;
     const repaired = [];
     for (let pass = 0; pass < MAX_PASSES; pass++) {
         deps.invalidateStateCache();
@@ -67,6 +70,9 @@ export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
                 failures.push({ drift: record, cause });
             }
         }
+        if (repairedThisPass) {
+            clearParseCache();
+        }
         if (blockers.length > 0) {
             let blockerState = stateSnapshot;
             if (repairedThisPass) {

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

@@ -35,7 +35,7 @@ function formatNeedsRemediationBlocker(milestoneId) {
     return [
         `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
         `Fix options:`,
-        `1. Add remediation slices with \`gsd_reassess_roadmap\`, then run \`/gsd auto\``,
+        `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
         `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
         `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
     ].join("\n");
@@ -204,10 +204,16 @@ export function invalidateStateCache() {
 /**
  * Returns the ID of the first incomplete milestone, or null if all are complete.
  */
+function getRequestedMilestoneLock() {
+    const lock = process.env.GSD_MILESTONE_LOCK?.trim();
+    return lock || undefined;
+}
 export async function getActiveMilestoneId(basePath) {
-    // Parallel worker isolation. Normal DB state derivation remains DB-only;
-    // lock env vars are execution routing for explicit worker processes.
-    const milestoneLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_MILESTONE_LOCK : undefined;
+    // Milestone-scoped execution. Parallel workers and explicit solo commands
+    // such as `/gsd auto M002` both set GSD_MILESTONE_LOCK; state derivation must
+    // honor it so recovery/adoption sees the requested milestone, not the first
+    // open milestone in queue order.
+    const milestoneLock = getRequestedMilestoneLock();
     if (milestoneLock) {
         if (isDbAvailable()) {
             const locked = getAllMilestones().find(m => m.id === milestoneLock);
@@ -573,7 +579,7 @@ function checkReplanTrigger(basePath, milestoneId, sliceId) {
 export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
     const requirements = getRequirementCounts();
     const allMilestones = getAllMilestones();
-    const milestoneLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_MILESTONE_LOCK : undefined;
+    const milestoneLock = getRequestedMilestoneLock();
     const milestones = milestoneLock
         ? allMilestones.filter(m => m.id === milestoneLock)
         : allMilestones;
@@ -718,8 +724,8 @@ export async function deriveStateFromDb(basePath, artifactReadRoot = basePath) {
         }
     }
     // ADR-011 Phase 2: pause-on-escalation takes precedence over dispatching the
-    // next task. `awaiting_review` tasks (continueWithDefault=true) are NOT
-    // surfaced here — they let the loop continue.
+    // next task. `awaiting_review` tasks (continueWithDefault=true) still pause
+    // here so silence is never treated as consent.
     //
     // We do NOT gate this on `phases.mid_execution_escalation` — creation of
     // new escalations is gated at the write site (tools/complete-task.ts:315),
@@ -779,13 +785,10 @@ export async function _deriveStateImpl(basePath, opts) {
     const diskIds = findMilestoneIds(basePath);
     const customOrder = loadQueueOrder(basePath);
     const milestoneIds = sortByQueueOrder(diskIds, customOrder);
-    // ── Parallel worker isolation ──────────────────────────────────────────
-    // When GSD_PARALLEL_WORKER and GSD_MILESTONE_LOCK are set, this process is a parallel worker
-    // scoped to a single milestone. Filter the milestone list so this worker
-    // only sees its assigned milestone (all others are treated as if they
-    // don't exist). This gives each worker complete isolation without
-    // modifying any other state derivation logic.
-    const milestoneLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_MILESTONE_LOCK : undefined;
+    // ── Milestone-scoped execution ─────────────────────────────────────────
+    // Parallel workers and explicit solo recovery both scope auto-mode to one
+    // milestone through GSD_MILESTONE_LOCK.
+    const milestoneLock = getRequestedMilestoneLock();
     if (milestoneLock && milestoneIds.includes(milestoneLock)) {
         milestoneIds.length = 0;
         milestoneIds.push(milestoneLock);

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

@@ -132,14 +132,16 @@
   Verify field rules:
   - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
   - MUST NOT use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`
+  - For absence checks, use `! grep -q "pattern" file` or `! rg -q "pattern" file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches
   - MUST NOT use inline `node -e` assertions for verification; put assertions in a real test file and run it with `node --test` or a package test script
   - For content/document tasks: verify file existence, section count, YAML validity, or word count
     NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
   - If no command can verify the output, write: "Manual review — file exists and is non-empty"
   - BAD: `python3 -m pytest tests/ -q --tb=short 2>&1 | tail -5`
+  - BAD: `grep -c "old_api" src/index.ts`
   - BAD: "Sections 3.1 and 3.2 exist with exact formulas. Zero TBD/TODO."
   - GOOD: `python3 -m pytest tests/ -q --tb=short`
-  - GOOD: `node --test tests/verify-doc.test.js`, `grep -q "Required heading" doc.md`, `test -s doc.md`
+  - GOOD: `node --test tests/verify-doc.test.js`, `grep -q "Required heading" doc.md`, `! grep -q "old_api" src/index.ts`, `test -s doc.md`
 
   Integration closure rule:
   - At least one slice in any multi-boundary milestone should perform real composition/wiring, not just contract hardening

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

@@ -2,8 +2,10 @@
 // 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";
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
+    const surfaceContract = getUnitToolSurfaceContract(unitType);
     if (!manifest) {
         return {
             ok: false,
@@ -12,6 +14,8 @@ export function compileUnitToolContract(unitType) {
         };
     }
     const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(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)/.test(tool));
     if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {
         return {
@@ -27,6 +31,7 @@ export function compileUnitToolContract(unitType) {
             contextMode: manifest.contextMode,
             toolsPolicy: manifest.tools,
             requiredWorkflowTools,
+            forbiddenWorkflowTools,
             promptObligations: [
                 `context-mode:${manifest.contextMode}`,
                 `tools-policy:${manifest.tools.mode}`,

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

@@ -0,0 +1,143 @@
+// 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";
+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",
+    "write",
+    "gsd_exec",
+    "gsd_summary_save",
+    "gsd_save_gate_result",
+    "search-the-web",
+    "WebSearch",
+    "Bash",
+    "Write",
+    "Edit",
+    "mcp__gsd-workflow__*",
+];
+export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
+    "Read",
+    "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),
+    };
+}
+export function toWorkflowMcpToolName(serverName, toolName) {
+    return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
+function addBlockedTool(blocked, name, reason) {
+    if (!blocked.some((entry) => entry.name === name)) {
+        blocked.push({ name, reason });
+    }
+}
+export function buildRunUatCanonicalToolNames(options = {}) {
+    return dedupe([
+        ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+        ...RUN_UAT_READ_ONLY_TOOL_NAMES,
+        ...(options.includeBrowserTools ?? []),
+    ]);
+}
+export function runUatBrowserToolsForType(uatType) {
+    return uatType === "browser-executable" ? RUN_UAT_BROWSER_TOOL_NAMES : [];
+}
+export function runUatPresentationSurfaceForType(uatType) {
+    return uatType === "browser-executable" ? "hybrid" : "mcp";
+}
+export function buildRunUatPresentationForType(uatType, options = {}) {
+    return buildRunUatResultPresentation({
+        ...options,
+        surface: options.surface ?? runUatPresentationSurfaceForType(uatType),
+        includeBrowserTools: runUatBrowserToolsForType(uatType),
+    });
+}
+export function buildRunUatResultPresentation(options = {}) {
+    const presentedTools = options.presentedTools
+        ? dedupe(options.presentedTools)
+        : buildRunUatCanonicalToolNames({ includeBrowserTools: options.includeBrowserTools });
+    const blockedTools = RUN_UAT_FORBIDDEN_TOOL_NAMES
+        .filter((toolName) => !toolName.includes("*"))
+        .map((name) => ({ name, reason: "forbidden during run-uat" }));
+    return {
+        surface: options.surface ?? "mcp",
+        presentedTools,
+        blockedTools,
+        toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+    };
+}
+export function resolveToolPresentationPlan(options) {
+    const requested = options.requestedToolNames ?? (options.phase === "run-uat"
+        ? buildRunUatCanonicalToolNames({ includeBrowserTools: options.includeBrowserTools })
+        : []);
+    const available = new Set(options.availableToolNames ?? requested);
+    const aliases = [];
+    const blockedToolNames = [];
+    const allowed = [];
+    for (const name of requested) {
+        const canonical = canonicalWorkflowToolName(name);
+        if (canonical !== name)
+            aliases.push({ requested: name, canonical });
+        if (!available.has(name) && !available.has(canonical)) {
+            addBlockedTool(blockedToolNames, canonical, "not registered or provider-incompatible");
+            continue;
+        }
+        allowed.push(canonical);
+    }
+    const allowedToolNames = dedupe(allowed);
+    const workflowServerName = options.workflowMcpServerName || "gsd-workflow";
+    const presentedToolNames = options.surface === "claude-code-sdk" || options.surface === "mcp"
+        ? allowedToolNames.map((name) => name.startsWith("gsd_") || name === "ask_user_questions"
+            ? toWorkflowMcpToolName(workflowServerName, name)
+            : name)
+        : allowedToolNames;
+    if (options.phase === "run-uat") {
+        for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
+            addBlockedTool(blockedToolNames, forbidden, "forbidden during run-uat");
+        }
+    }
+    return {
+        phase: options.phase,
+        surface: options.surface,
+        model: options.model,
+        allowedToolNames,
+        presentedToolNames,
+        blockedToolNames,
+        aliases,
+        diagnostics: [],
+    };
+}

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

@@ -158,7 +158,7 @@ ${params.narrative}
 
 ## Verification
 
-${params.verification}
+${params.verification ?? ""}
 
 ## Requirements Advanced
 
@@ -351,6 +351,20 @@ export async function handleCompleteSlice(params, basePath) {
             if (parsed.length > 0)
                 effectiveParams.requirementsInvalidated = parsed;
         }
+        if (effectiveParams.verification === undefined) {
+            const headingLine = "## Verification\n\n";
+            const start = existingSummaryMd.indexOf(headingLine);
+            if (start !== -1) {
+                const contentStart = start + headingLine.length;
+                const nextHeading = existingSummaryMd.indexOf("\n\n## ", contentStart);
+                const prior = nextHeading === -1
+                    ? existingSummaryMd.slice(contentStart)
+                    : existingSummaryMd.slice(contentStart, nextHeading);
+                const trimmed = prior.trim();
+                if (trimmed)
+                    effectiveParams.verification = trimmed;
+            }
+        }
     }
     // Render summary markdown
     const summaryMd = renderSliceSummaryMarkdown(effectiveParams);

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

@@ -314,9 +314,18 @@ export async function handleCompleteTask(params, basePath) {
     // overwrite it; gate rows are UPSERT-keyed per task and will also be
     // overwritten. This restores the invariant that deriveState() sees a
     // consistent "task not done" view so the loop re-dispatches the task.
+    let escalationMetadata;
     if (validatedEscalationArtifact) {
         try {
-            writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+            const escalationPath = writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+            escalationMetadata = {
+                artifactPath: escalationPath,
+                question: validatedEscalationArtifact.question,
+                options: validatedEscalationArtifact.options,
+                recommendation: validatedEscalationArtifact.recommendation,
+                recommendationRationale: validatedEscalationArtifact.recommendationRationale,
+                continueWithDefault: validatedEscalationArtifact.continueWithDefault,
+            };
         }
         catch (escalationErr) {
             const msg = `complete-task escalation write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${escalationErr.message}`;
@@ -378,6 +387,7 @@ export async function handleCompleteTask(params, basePath) {
         sliceId: params.sliceId,
         milestoneId: params.milestoneId,
         summaryPath,
+        ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
         ...(projectionStale ? { stale: true } : {}),
     };
 }

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -5,6 +5,27 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { isContextModeEnabled } from "../preferences-types.js";
 import { contextModeDisabledResult } from "./context-mode-tool-result.js";
+const UAT_EXEC_INTENTS = [
+    "uat-artifact-check",
+    "uat-runtime-check",
+    "uat-browser-check",
+    "uat-service-start",
+    "uat-log-inspection",
+];
+const UAT_EXEC_INTENT_ALIASES = {
+    artifact: "uat-artifact-check",
+    "artifact-driven": "uat-artifact-check",
+    runtime: "uat-runtime-check",
+    "runtime-executable": "uat-runtime-check",
+    "live-runtime": "uat-runtime-check",
+    browser: "uat-browser-check",
+    "browser-executable": "uat-browser-check",
+    service: "uat-service-start",
+    "service-start": "uat-service-start",
+    log: "uat-log-inspection",
+    logs: "uat-log-inspection",
+    "log-inspection": "uat-log-inspection",
+};
 export function buildExecOptions(baseDir, cfg, extras) {
     const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg.exec_env_allowlist : EXEC_DEFAULTS.envAllowlist;
     const stdoutCap = clampNumber(cfg?.exec_stdout_cap_bytes, EXEC_DEFAULTS.stdoutCapBytes, 4_096, 16_777_216);
@@ -73,6 +94,39 @@ function normalizeScript(params) {
     }
     return paramError("script is required and must be a non-empty string");
 }
+function normalizeRequiredString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return paramError(`${field} is required and must be a non-empty string`);
+    }
+    return value.trim();
+}
+function normalizeUatIntent(value) {
+    if (typeof value !== "string") {
+        return paramError(`intent is required and must be one of: ${UAT_EXEC_INTENTS.join(", ")}`);
+    }
+    const normalized = value.trim().toLowerCase();
+    if (UAT_EXEC_INTENTS.includes(normalized))
+        return normalized;
+    const alias = UAT_EXEC_INTENT_ALIASES[normalized];
+    if (alias)
+        return alias;
+    return paramError(`invalid intent "${value}" — must be one of: ${UAT_EXEC_INTENTS.join(", ")}`);
+}
+function rejectUatScript(script) {
+    const patterns = [
+        { re: /\b(?:npm|pnpm|yarn|bun)\s+(?:i|install|add|remove|update|upgrade)\b/i, reason: "package dependency mutation is not allowed during UAT" },
+        { re: /\b(?:pip|pip3|python\s+-m\s+pip)\s+install\b/i, reason: "package dependency mutation is not allowed during UAT" },
+        { re: /\bgit\s+(?:add|commit|push|reset|checkout|switch|merge|rebase|clean|rm|mv|tag|branch)\b/i, reason: "git mutations are not allowed during UAT" },
+        { re: /\brm\s+-[^\n\r;|&]*r[^\n\r;|&]*f\b/i, reason: "destructive filesystem cleanup is not allowed during UAT" },
+        { re: /\b(?:env|printenv)\b(?:\s|$)/i, reason: "dumping environment variables is not allowed during UAT" },
+        { re: /\bcat\s+\.env(?:\b|\.|$)/i, reason: "reading credential files is not allowed during UAT" },
+    ];
+    for (const pattern of patterns) {
+        if (pattern.re.test(script))
+            return pattern.reason;
+    }
+    return null;
+}
 function isToolExecutionResult(value) {
     return typeof value === "object" && value !== null && Array.isArray(value.content);
 }
@@ -207,6 +261,7 @@ export async function executeGsdExec(params, deps) {
             runtime,
             script,
             ...(typeof params.purpose === "string" ? { purpose: params.purpose } : {}),
+            ...(params.metadata && typeof params.metadata === "object" ? { metadata: params.metadata } : {}),
             ...(typeof params.timeout_ms === "number" ? { timeout_ms: params.timeout_ms } : {}),
         }, opts);
         return formatResult(result);
@@ -220,6 +275,60 @@ export async function executeGsdExec(params, deps) {
         };
     }
 }
+export async function executeUatExec(params, deps) {
+    const milestoneId = normalizeRequiredString(params.milestoneId, "milestoneId");
+    if (isToolExecutionResult(milestoneId))
+        return milestoneId;
+    const sliceId = normalizeRequiredString(params.sliceId, "sliceId");
+    if (isToolExecutionResult(sliceId))
+        return sliceId;
+    const checkId = normalizeRequiredString(params.checkId, "checkId");
+    if (isToolExecutionResult(checkId))
+        return checkId;
+    const intent = normalizeUatIntent(params.intent);
+    if (isToolExecutionResult(intent))
+        return intent;
+    const script = normalizeScript(params);
+    if (isToolExecutionResult(script))
+        return script;
+    const rejected = rejectUatScript(script);
+    if (rejected) {
+        return {
+            content: [{ type: "text", text: `Error: gsd_uat_exec blocked command — ${rejected}` }],
+            details: { operation: "gsd_uat_exec", error: "uat_exec_policy_block", reason: rejected },
+            isError: true,
+        };
+    }
+    const result = await executeGsdExec({
+        ...params,
+        script,
+        purpose: typeof params.purpose === "string" && params.purpose.trim().length > 0
+            ? params.purpose
+            : `UAT ${milestoneId}/${sliceId}/${checkId} (${intent})`,
+        metadata: {
+            kind: "uat_exec",
+            milestoneId,
+            sliceId,
+            checkId,
+            intent,
+            ...(typeof params.expected === "string" && params.expected.trim().length > 0
+                ? { expected: params.expected.trim() }
+                : {}),
+        },
+    }, deps);
+    const details = result.details ?? {};
+    return {
+        ...result,
+        details: {
+            ...details,
+            operation: "gsd_uat_exec",
+            milestoneId,
+            sliceId,
+            checkId,
+            intent,
+        },
+    };
+}
 function formatResult(result) {
     const headerLines = [
         `gsd_exec[${result.id}] runtime=${result.runtime} exit=${formatExit(result)} duration=${result.duration_ms}ms`,

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

@@ -268,15 +268,9 @@ export async function handlePlanSlice(rawParams, basePath) {
             for (const taskId of omittedTaskIds) {
                 deleteTask(params.milestoneId, params.sliceId, taskId);
             }
+            const existingTaskById = new Map(existingTasks.map((task) => [task.id, task]));
             for (const task of params.tasks) {
-                insertTask({
-                    id: task.taskId,
-                    sliceId: params.sliceId,
-                    milestoneId: params.milestoneId,
-                    title: task.title,
-                    status: "pending",
-                });
-                upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, {
+                const planning = {
                     title: task.title,
                     description: task.description,
                     estimate: task.estimate,
@@ -287,7 +281,18 @@ export async function handlePlanSlice(rawParams, basePath) {
                     observabilityImpact: task.observabilityImpact ?? "",
                     fullPlanMd: task.fullPlanMd,
                     targetRepositories: task.targetRepositories ?? params.targetRepositories ?? defaultTargets,
-                });
+                };
+                const existingTask = existingTaskById.get(task.taskId);
+                if (!existingTask || !isClosedStatus(existingTask.status)) {
+                    insertTask({
+                        id: task.taskId,
+                        sliceId: params.sliceId,
+                        milestoneId: params.milestoneId,
+                        title: task.title,
+                        status: "pending",
+                    });
+                }
+                upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, planning);
             }
             // Seed quality gate rows inside the transaction — all-or-nothing with
             // the plan data so a crash can't leave orphaned gates without tasks.