@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.74e8dd1

package/dist/resources/extensions/gsd/gsd-db.js

@@ -37,6 +37,7 @@ import { rowToActiveDecision, rowToActiveRequirement, rowToDecision, rowToRequir
 import { rowToGate } from "./db-gate-rows.js";
 import { rowToArtifact, rowToMilestone } from "./db-milestone-artifact-rows.js";
 import { backupDatabaseBeforeMigration } from "./db-migration-backup.js";
+import { isClosedStatus } from "./status-guards.js";
 import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, applyMigrationV29RepositoryTargets, } from "./db-migration-steps.js";
 import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "./db-memory-fts-schema.js";
 import { createDbOpenState } from "./db-open-state.js";
@@ -1419,15 +1420,47 @@ export function setMilestoneQueueOrder(order) {
         throw err;
     }
 }
+function getMilestoneStatusForUpdate(milestoneId) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    const row = currentDb.prepare("SELECT status FROM milestones WHERE id = :id").get({ ":id": milestoneId });
+    return typeof row?.["status"] === "string" ? row["status"] : null;
+}
+function writeMilestoneStatus(milestoneId, status, completedAt) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb.prepare(`UPDATE milestones SET status = :status, completed_at = :completed_at WHERE id = :id`).run({ ":status": status, ":completed_at": completedAt ?? null, ":id": milestoneId });
+}
 /**
  * Update a milestone's status in the database.
- * Used by park/unpark to keep the DB in sync with the filesystem marker.
- * See: https://github.com/open-gsd/gsd-pi/issues/2694
+ *
+ * Generic status updates may close milestones, park/unpark open milestones, or
+ * advance planned milestones. They may not reopen a closed milestone; callers
+ * must use reopenMilestoneStatus(), which is reserved for gsd_milestone_reopen.
  */
 export function updateMilestoneStatus(milestoneId, status, completedAt) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare(`UPDATE milestones SET status = :status, completed_at = :completed_at WHERE id = :id`).run({ ":status": status, ":completed_at": completedAt ?? null, ":id": milestoneId });
+    const currentStatus = getMilestoneStatusForUpdate(milestoneId);
+    if (currentStatus && isClosedStatus(currentStatus) && !isClosedStatus(status)) {
+        throw new Error(`Cannot update closed milestone ${milestoneId} from ${currentStatus} to ${status}; use gsd_milestone_reopen for an explicit reopen.`);
+    }
+    writeMilestoneStatus(milestoneId, status, completedAt);
+}
+/**
+ * Explicit closed -> active transition for gsd_milestone_reopen only.
+ */
+export function reopenMilestoneStatus(milestoneId) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    const currentStatus = getMilestoneStatusForUpdate(milestoneId);
+    if (!currentStatus) {
+        throw new Error(`Cannot reopen missing milestone ${milestoneId}`);
+    }
+    if (!isClosedStatus(currentStatus)) {
+        throw new Error(`Cannot reopen milestone ${milestoneId} from status ${currentStatus}; milestone is not closed.`);
+    }
+    writeMilestoneStatus(milestoneId, "active", null);
 }
 export function getActiveMilestoneFromDb() {
     if (!currentDb)
@@ -2240,7 +2273,7 @@ export function deleteArtifactByPath(path) {
 }
 /**
  * Drop hierarchy rows in dependency order inside a transaction. Used by
- * `gsd recover` to rebuild engine state from markdown.
+ * `gsd recover --confirm` to rebuild engine state from markdown.
  */
 export function clearEngineHierarchy() {
     if (!currentDb)

package/dist/resources/extensions/gsd/guided-flow.js

@@ -1908,7 +1908,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const result = await checkMarkdownHierarchyAgainstDb(basePath);
             if (result.action === "recovery-required") {
                 ctx.ui.notify(result.message ??
-                    `Markdown planning artifacts do not match the authoritative DB. Run \`${result.recoveryCommand ?? "/gsd recover"}\` to import markdown explicitly.`, "warning");
+                    `Markdown planning artifacts do not match the authoritative DB. Run \`${result.recoveryCommand ?? "/gsd recover --confirm"}\` to import markdown explicitly.`, "warning");
             }
         }
         catch (err) {

package/dist/resources/extensions/gsd/mcp-filter.js

@@ -24,14 +24,17 @@ function collectServerEntries(servers) {
 export function discoverMcpServers(projectDir) {
     const mcpJsonPath = resolve(projectDir, ".mcp.json");
     const settingsPath = resolve(projectDir, ".claude", "settings.json");
+    const localSettingsPath = resolve(projectDir, ".claude", "settings.local.json");
     const mcpJson = readJsonFile(mcpJsonPath);
     const settings = readJsonFile(settingsPath, true);
+    const localSettings = readJsonFile(localSettingsPath, true);
     const seen = new Set();
     const discovered = [];
     for (const entry of [
         ...collectServerEntries(mcpJson?.mcpServers),
         ...collectServerEntries(mcpJson?.servers),
         ...collectServerEntries(settings?.mcpServers),
+        ...collectServerEntries(localSettings?.mcpServers),
     ]) {
         if (seen.has(entry.name))
             continue;

package/dist/resources/extensions/gsd/mcp-project-config.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -157,6 +157,62 @@ function readExistingConfig(configPath) {
         throw new Error(`Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+function readExistingClaudeCodeSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    const raw = readFileSync(settingsPath, "utf-8");
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${settingsPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function ensureClaudeCodeMcpJsonServersEnabled(projectRoot, serverNames) {
+    const resolvedProjectRoot = resolve(projectRoot);
+    assertSafeDirectory(resolvedProjectRoot);
+    const targetServerNames = [...new Set(serverNames.filter((name) => name.trim().length > 0))];
+    if (targetServerNames.length === 0)
+        return false;
+    const settingsDir = resolve(resolvedProjectRoot, ".claude");
+    const settingsPath = resolve(settingsDir, "settings.local.json");
+    const existing = readExistingClaudeCodeSettings(settingsPath);
+    const enabled = Array.isArray(existing.enabledMcpjsonServers)
+        ? [...existing.enabledMcpjsonServers]
+        : [];
+    const enabledNames = new Set(enabled.filter((value) => typeof value === "string"));
+    let changed = !Array.isArray(existing.enabledMcpjsonServers);
+    for (const serverName of targetServerNames) {
+        if (!enabledNames.has(serverName)) {
+            enabled.push(serverName);
+            enabledNames.add(serverName);
+            changed = true;
+        }
+    }
+    let nextDisabled = existing.disabledMcpjsonServers;
+    if (Array.isArray(existing.disabledMcpjsonServers)) {
+        const blockedNames = new Set(targetServerNames);
+        const filtered = existing.disabledMcpjsonServers.filter((value) => !blockedNames.has(String(value)));
+        if (filtered.length !== existing.disabledMcpjsonServers.length) {
+            nextDisabled = filtered;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return false;
+    const nextSettings = {
+        ...existing,
+        enabledMcpjsonServers: enabled,
+        ...(Array.isArray(existing.disabledMcpjsonServers) ? { disabledMcpjsonServers: nextDisabled } : {}),
+    };
+    mkdirSync(settingsDir, { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`, "utf-8");
+    return true;
+}
+export function ensureClaudeCodeMcpJsonServerEnabled(projectRoot, serverName) {
+    return ensureClaudeCodeMcpJsonServersEnabled(projectRoot, [serverName]);
+}
 export function ensureProjectWorkflowMcpConfig(projectRoot, env = process.env) {
     const resolvedProjectRoot = resolve(projectRoot);
     assertSafeDirectory(resolvedProjectRoot);
@@ -170,10 +226,18 @@ export function ensureProjectWorkflowMcpConfig(projectRoot, env = process.env) {
     };
     const desiredServerNames = Object.keys(desiredServers);
     const alreadyPresent = existsSync(configPath);
-    const unchanged = desiredServerNames.every((serverName) => (JSON.stringify(previousServers[serverName] ?? null)
+    const mcpConfigUnchanged = desiredServerNames.every((serverName) => (JSON.stringify(previousServers[serverName] ?? null)
         === JSON.stringify(desiredServers[serverName])))
         && existing.mcpServers !== undefined;
-    if (unchanged) {
+    if (!mcpConfigUnchanged) {
+        const nextConfig = {
+            ...existing,
+            mcpServers: nextServers,
+        };
+        writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8");
+    }
+    const localSettingsChanged = ensureClaudeCodeMcpJsonServersEnabled(resolvedProjectRoot, desiredServerNames);
+    if (mcpConfigUnchanged && !localSettingsChanged) {
         return {
             configPath,
             serverName: workflowServerName,
@@ -181,11 +245,6 @@ export function ensureProjectWorkflowMcpConfig(projectRoot, env = process.env) {
             status: "unchanged",
         };
     }
-    const nextConfig = {
-        ...existing,
-        mcpServers: nextServers,
-    };
-    writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8");
     return {
         configPath,
         serverName: workflowServerName,

package/dist/resources/extensions/gsd/migration-auto-check.js

@@ -78,9 +78,9 @@ export async function checkMarkdownHierarchyAgainstDb(basePath) {
         markdown,
         beforeDb,
         afterDb: beforeDb,
-        recoveryCommand: "/gsd recover",
+        recoveryCommand: "/gsd recover --confirm",
         message: `Markdown planning artifacts (${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T) ` +
             `do not match the authoritative DB (${beforeDb.milestones}M/${beforeDb.slices}S/${beforeDb.tasks}T). ` +
-            "Runtime startup will not import markdown automatically; run `/gsd recover` if markdown should repopulate the database.",
+            "Runtime startup will not import markdown automatically; run `/gsd recover --confirm` if markdown should repopulate the database.",
     };
 }

package/dist/resources/extensions/gsd/prompts/run-uat.md

@@ -37,7 +37,13 @@ You are the UAT runner. Execute every check defined in `{{uatPath}}` as deeply a
 
 Choose the lightest tool that proves the check honestly:
 
-- Run shell commands with `bash`
+- Run automated checks with `gsd_uat_exec`
+  - Use `uat-artifact-check` as `intent` for static file, grep, structure, or artifact checks.
+  - Use `uat-runtime-check` as `intent` for executing tests, scripts, or runtime assertions.
+  - Use `uat-browser-check` as `intent` for browser interaction or screenshot-backed UI checks.
+  - Use `uat-service-start` as `intent` only when starting or connecting to an app/service.
+  - Use `uat-log-inspection` as `intent` for checking logs or captured output files.
+  - The result-table evidence mode is separate; do not use `artifact`, `runtime`, or `human-follow-up` as `intent`.
 - Run `grep` / `rg` checks against files
 - Run `node` / other script invocations
 - Read files and verify their contents
@@ -48,7 +54,7 @@ Choose the lightest tool that proves the check honestly:
 For each check, record:
 - The check description (from the UAT file)
 - The evidence mode used: `artifact`, `runtime`, or `human-follow-up`
-- The command or action taken
+- The command or action taken, including the `gsd_uat_exec` evidence ID for automated checks
 - The actual result observed
 - `PASS`, `FAIL`, or `NEEDS-HUMAN`
 
@@ -57,7 +63,7 @@ After running all checks, compute the **overall verdict**:
 - `FAIL` — one or more automatable checks failed
 - `PARTIAL` — one or more automatable checks were skipped or returned inconclusive results (not the same as `NEEDS-HUMAN` — use PARTIAL only when the agent itself could not determine pass/fail for a check it was supposed to automate)
 
-Call `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "ASSESSMENT"`, and the full UAT result markdown as `content` — the tool computes the file path and persists to both DB and disk. The content should follow this format:
+Call `gsd_summary_save` with `milestone_id: "{{milestoneId}}"`, `slice_id: "{{sliceId}}"`, `artifact_type: "ASSESSMENT"`, and the full UAT result markdown as `content`. The tool computes the assessment path, persists to DB/disk, and saves the aggregate UAT gate. The content should follow this logical shape:
 
 ```markdown
 ---
@@ -86,6 +92,6 @@ date: <ISO 8601 timestamp>
 
 ---
 
-**You MUST call `gsd_summary_save` with the UAT result content before finishing.**
+**You MUST call `gsd_summary_save` with `artifact_type: "ASSESSMENT"` and the UAT result content before finishing. Do not write the assessment file directly.**
 
 When done, say: "UAT {{sliceId}} complete."

package/dist/resources/extensions/gsd/prompts/system.md

@@ -32,7 +32,7 @@ GSD ships with bundled skills. Installed skills are listed in `<available_skills
 - Never print, echo, log, or restate secrets or credentials. Report only key names and applied/skipped status.
 - Never ask the user to edit `.env` files or set secrets manually. Use `secure_env_collect`.
 - In enduring files, write current state only unless the file is explicitly historical.
-- **Never take outward-facing actions on GitHub or external services without explicit user confirmation.** This includes creating/closing issues, merging/approving/commenting on PRs, pushing remote branches, publishing packages, or any state change outside local filesystem. Read-only listing/viewing/diffing is fine. Present intent and get a clear "yes" first. **Non-bypassable:** no response, ambiguity, or `ask_user_questions` failure means re-ask; never rationalize past the block. Missing "yes" means "no."
+- **Never take outward-facing actions on GitHub or external services without explicit user confirmation.** This includes creating/closing issues, merging/approving/commenting on PRs, pushing remote branches, publishing packages, terragrunt/aws/kubectl mutations, or any state change outside local filesystem. Read-only listing/viewing/diffing is fine. Present intent and get a clear "yes" first. **Non-bypassable:** no response, ambiguity, or `ask_user_questions` failure means re-ask; never rationalize past the block. Missing "yes" means "no."
 
 If a `GSD Skill Preferences` block appears below, treat it as durable guidance for skills to use, prefer, or avoid unless it conflicts with artifact rules, verification, or higher-priority instructions.
 
@@ -160,4 +160,6 @@ Fix root causes, not symptoms. If applying temporary mitigation, label it and pr
 - When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
 - After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats.
 
+  If any next step is destructive/outward-facing, present it via `ask_user_questions` and wait for the user's answer before execution. Do not execute a next-step item from a prior plain-text numbered list without fresh confirmation.
+
 Good narration states a decision or finding: "Three handlers follow a middleware pattern - using that instead of a custom wrapper." Bad narration just announces the next call ("Reading the file now.") or emits compressed planner notes ("Need create plan artifact maybe read existing plans.").

package/dist/resources/extensions/gsd/safety/destructive-guard.js

@@ -16,6 +16,9 @@ const DESTRUCTIVE_PATTERNS = [
     { pattern: /\btruncate\s+table\b/i, label: "SQL truncate" },
     { pattern: /\bchmod\s+777\b/, label: "world-writable permissions" },
     { pattern: /\bcurl\s.*\|\s*(bash|sh|zsh)\b/, label: "pipe to shell" },
+    { pattern: /\bterra(form|grunt)\s+(apply|destroy)/i, label: "IaC apply/destroy" },
+    { pattern: /\baws\s+\w+\s+(delete|create|put|remove|terminate)\b/i, label: "AWS mutation" },
+    { pattern: /\bkubectl\s+(delete|apply)\b/i, label: "kubectl mutation" },
 ];
 /**
  * Classify a bash command for destructive operations.

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;
@@ -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/tool-presentation-plan.js

@@ -0,0 +1,120 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
+export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_journal_query",
+];
+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,
+        ...(options.includeBrowserTools ?? []),
+    ]);
+}
+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: [],
+    };
+}