@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.9ad8ae33

package/dist/cli-style.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Terminal presentation helpers for CLI-side notices on stderr — warnings,
+ * hints, and names. Pairs with the extension-side glyph set in
+ * resources/extensions/shared/ui.ts. Adopt incrementally: banner-shaped CLI
+ * surfaces (worktree banners today; update checks et al. as they're touched)
+ * should render through these instead of ad-hoc chalk.
+ */
+/** Dim "[gsd] " line tag that prefixes CLI banner lines. */
+export declare function gsdTag(): string;
+/** A yellow warning fragment. */
+export declare function warn(text: string): string;
+/** A dim "what to do next" hint fragment. */
+export declare function hint(text: string): string;
+/** A cyan user-supplied name (worktree, branch, file). */
+export declare function name(text: string): string;
+/** One banner line: tagged warning followed by a tagged hint line. */
+export declare function bannerLines(warning: string, hintText: string): string;

package/dist/cli-style.js

@@ -0,0 +1,28 @@
+/**
+ * Terminal presentation helpers for CLI-side notices on stderr — warnings,
+ * hints, and names. Pairs with the extension-side glyph set in
+ * resources/extensions/shared/ui.ts. Adopt incrementally: banner-shaped CLI
+ * surfaces (worktree banners today; update checks et al. as they're touched)
+ * should render through these instead of ad-hoc chalk.
+ */
+import chalk from 'chalk';
+/** Dim "[gsd] " line tag that prefixes CLI banner lines. */
+export function gsdTag() {
+    return chalk.dim('[gsd] ');
+}
+/** A yellow warning fragment. */
+export function warn(text) {
+    return chalk.yellow(text);
+}
+/** A dim "what to do next" hint fragment. */
+export function hint(text) {
+    return chalk.dim(text);
+}
+/** A cyan user-supplied name (worktree, branch, file). */
+export function name(text) {
+    return chalk.cyan(text);
+}
+/** One banner line: tagged warning followed by a tagged hint line. */
+export function bannerLines(warning, hintText) {
+    return gsdTag() + warning + '\n' + gsdTag() + hint(hintText) + '\n\n';
+}

package/dist/cli.js

@@ -524,7 +524,7 @@ const authStorage = AuthStorage.create(authFilePath);
 markStartup('AuthStorage.create');
 loadStoredEnvKeys(authStorage);
 migratePiCredentials(authStorage);
-// Resolve models.json path with fallback to ~/.pi/agent/models.json
+// Resolve models.json path
 const { resolveModelsJsonPath } = await import('./models-resolver.js');
 const modelsJsonPath = resolveModelsJsonPath();
 const modelRegistry = ModelRegistry.create(authStorage, modelsJsonPath);

package/dist/headless-events.d.ts

@@ -5,6 +5,10 @@
  * and classifies commands as quick (single-turn) vs long-running.
  *
  * Also defines exit code constants and the status→exit-code mapping function.
+ *
+ * The stop/pause notice vocabulary itself (prefixes + message classifiers)
+ * lives in the Stop Notice module — the same module the emitters format with,
+ * so wording stays in lockstep with detection.
  */
 export declare const EXIT_SUCCESS = 0;
 export declare const EXIT_ERROR = 1;
@@ -42,8 +46,6 @@ export declare function mapStatusToExitCode(status: string): number;
  *
  * Blocked detection is separate — checked via isBlockedNotification.
  */
-export declare const PAUSED_PREFIXES: string[];
-export declare const TERMINAL_PREFIXES: string[];
 export declare const IDLE_TIMEOUT_MS = 15000;
 export declare const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120000;
 export declare function canonicalHeadlessToolName(toolName: string | undefined): string;

package/dist/headless-events.js

@@ -5,7 +5,13 @@
  * and classifies commands as quick (single-turn) vs long-running.
  *
  * Also defines exit code constants and the status→exit-code mapping function.
+ *
+ * The stop/pause notice vocabulary itself (prefixes + message classifiers)
+ * lives in the Stop Notice module — the same module the emitters format with,
+ * so wording stays in lockstep with detection.
  */
+import { isBlockedNoticeMessage, isManualResolutionNotice, isPauseNotice, isTerminalNotice, } from './resources/extensions/gsd/stop-notice.js';
+import { canonicalToolName } from './resources/extensions/gsd/engine-hook-contract.js';
 // ---------------------------------------------------------------------------
 // Exit Code Constants
 // ---------------------------------------------------------------------------
@@ -65,40 +71,19 @@ export function mapStatusToExitCode(status) {
  *
  * Blocked detection is separate — checked via isBlockedNotification.
  */
-export const PAUSED_PREFIXES = ['auto-mode paused', 'step-mode paused'];
-export const TERMINAL_PREFIXES = [
-    'auto-mode stopped',
-    'step-mode stopped',
-    'auto-mode complete',
-    'no active milestone',
-    'auto-mode idle',
-];
 export const IDLE_TIMEOUT_MS = 15_000;
 // new-milestone is a long-running creative task where the LLM may pause
 // between tool calls (e.g. after mkdir, before writing files). Use a
 // longer idle timeout to avoid killing the session prematurely (#808).
 export const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120_000;
 const INTERACTIVE_HEADLESS_TOOLS = new Set(['ask_user_questions', 'secure_env_collect']);
+// Delegates to the shared normalizer seam (engine-hook-contract.ts) instead of
+// a hand-rolled parser. Behavior differs from the old parser only on malformed
+// MCP names: `mcp____tool` (empty server) and `mcp__server__` (empty tool) are
+// now returned unchanged rather than partially stripped — neither can match a
+// real tool name, so detection behavior is unaffected.
 export function canonicalHeadlessToolName(toolName) {
-    const name = String(toolName ?? '');
-    if (!name.startsWith('mcp__'))
-        return name;
-    const toolSeparator = name.indexOf('__', 'mcp__'.length);
-    return toolSeparator >= 0 ? name.slice(toolSeparator + 2) : name;
-}
-function isManualResolutionNotification(message) {
-    return (message.includes('resolve manually and re-run /gsd auto') ||
-        message.includes('resolve conflicts manually and run /gsd auto to resume') ||
-        message.includes('resolve and run /gsd auto to resume'));
-}
-function isNonBlockingPauseNotification(message) {
-    return message.includes('idempotent advance: unit already active');
-}
-function isPauseNotification(message) {
-    return PAUSED_PREFIXES.some((prefix) => message.startsWith(prefix));
-}
-function isPauseNotificationRequiringIntervention(message) {
-    return isPauseNotification(message) && !isNonBlockingPauseNotification(message);
+    return canonicalToolName(String(toolName ?? ''));
 }
 function getCommandBlockContent(event) {
     if (event.type !== 'message_start' && event.type !== 'message_end')
@@ -122,20 +107,15 @@ export function isTerminalNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
     const message = String(event.message ?? '').toLowerCase();
-    return (TERMINAL_PREFIXES.some((prefix) => message.startsWith(prefix)) ||
-        isPauseNotification(message) ||
-        isManualResolutionNotification(message));
+    return isTerminalNotice(message) || isPauseNotice(message) || isManualResolutionNotice(message);
 }
 export function isBlockedNotification(event) {
     if (isBlockingCommandBlock(event))
         return true;
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
-    const message = String(event.message ?? '').toLowerCase();
     // Recoverable pauses need operator intervention in headless mode.
-    return (message.includes('blocked:') ||
-        isPauseNotificationRequiringIntervention(message) ||
-        isManualResolutionNotification(message));
+    return isBlockedNoticeMessage(String(event.message ?? '').toLowerCase());
 }
 export function isMilestoneReadyNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')

package/dist/mcp-server.js

@@ -29,6 +29,7 @@ function isPlainObject(value) {
 // built via a template string so TypeScript's NodeNext resolver treats them as
 // `any` and skips static checking.
 const MCP_PKG = '@modelcontextprotocol/sdk';
+import { sanitizeSchemaForMoonshot } from '@gsd/pi-ai';
 export function mcpSdkSpecifier(subpath) {
     return `${MCP_PKG}/${subpath}.js`;
 }
@@ -65,7 +66,7 @@ export async function startMcpServer(options) {
         tools: tools.map((t) => ({
             name: t.name,
             description: t.description,
-            inputSchema: t.parameters,
+            inputSchema: sanitizeSchemaForMoonshot(t.parameters),
         })),
     }));
     // tools/call — execute the requested tool and return content blocks.

package/dist/models-resolver.d.ts

@@ -1,20 +1,10 @@
 /**
- * Models.json resolution with fallback to ~/.pi/agent/models.json
+ * Models.json resolution for GSD.
  *
- * GSD uses ~/.gsd/agent/models.json, but for a smooth migration/development
- * experience, this module provides resolution logic that:
- *
- * 1. Reads ~/.gsd/agent/models.json if it exists
- * 2. Falls back to ~/.pi/agent/models.json if GSD file doesn't exist
- * 3. Merges both files if both exist (GSD takes precedence)
+ * Uses ~/.gsd/agent/models.json exclusively.
  */
 /**
- * Resolve the path to models.json with fallback logic.
- *
- * Priority:
- * 1. ~/.gsd/agent/models.json (exists) → return this path
- * 2. ~/.pi/agent/models.json (exists) → return this path (fallback)
- * 3. Neither exists → return GSD path (will be created)
+ * Resolve the path to models.json.
  *
  * @returns The path to use for models.json
  */

package/dist/models-resolver.js

@@ -1,35 +1,16 @@
 /**
- * Models.json resolution with fallback to ~/.pi/agent/models.json
+ * Models.json resolution for GSD.
  *
- * GSD uses ~/.gsd/agent/models.json, but for a smooth migration/development
- * experience, this module provides resolution logic that:
- *
- * 1. Reads ~/.gsd/agent/models.json if it exists
- * 2. Falls back to ~/.pi/agent/models.json if GSD file doesn't exist
- * 3. Merges both files if both exist (GSD takes precedence)
+ * Uses ~/.gsd/agent/models.json exclusively.
  */
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { agentDir } from './app-paths.js';
 const GSD_MODELS_PATH = join(agentDir, 'models.json');
-const PI_MODELS_PATH = join(homedir(), '.pi', 'agent', 'models.json');
 /**
- * Resolve the path to models.json with fallback logic.
- *
- * Priority:
- * 1. ~/.gsd/agent/models.json (exists) → return this path
- * 2. ~/.pi/agent/models.json (exists) → return this path (fallback)
- * 3. Neither exists → return GSD path (will be created)
+ * Resolve the path to models.json.
  *
  * @returns The path to use for models.json
  */
 export function resolveModelsJsonPath() {
-    if (existsSync(GSD_MODELS_PATH)) {
-        return GSD_MODELS_PATH;
-    }
-    if (existsSync(PI_MODELS_PATH)) {
-        return PI_MODELS_PATH;
-    }
     return GSD_MODELS_PATH;
 }

package/dist/resource-loader.d.ts

@@ -22,6 +22,9 @@ export declare function readManagedResourceVersion(agentDir: string): string | n
  * directory (e.g. pre-install verification).
  */
 export declare function computeResourceFingerprint(rootDir?: string): string;
+export declare function setGsdBrowserPackageSkillPathForTests(skillPath: string | null | undefined): void;
+export declare function collectGsdBrowserPackageSkillReferences(content: string): string[];
+export declare function hasStaleGsdBrowserPackageSkill(skillsDir: string): boolean;
 export declare function getNewerManagedResourceVersion(agentDir: string, currentVersion: string): string | null;
 /**
  * Syncs a single bundled resource directory into the agent directory.
@@ -49,18 +52,20 @@ export declare function reconcileMergedNodeModules(agentNodeModules: string, hoi
 /** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
 export declare function mergedFingerprint(hoisted: string, internal: string): string;
 /**
- * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
+ * Initializes managed resources under agentDir (~/.gsd/agent/).
  *
  * - extensions/ → ~/.gsd/agent/extensions/   (overwrite when version changes)
  * - shared/     → ~/.gsd/agent/shared/       (overwrite when version changes)
  * - agents/     → ~/.gsd/agent/agents/        (overwrite when version changes)
  * - skills/     → ~/.gsd/agent/skills/        (overwrite when version changes)
+ * - gsd-browser skill → ~/.gsd/agent/skills/gsd-browser/ from @opengsd/gsd-browser
  * - GSD-WORKFLOW.md → ~/.gsd/agent/GSD-WORKFLOW.md (fallback for env var miss)
  *
- * Skips the copy when the managed-resources.json version matches the current
- * GSD version, avoiding ~128ms of synchronous cpSync on every startup.
- * After `npm update -g @glittercowboy/gsd`, versions will differ and the
- * copy runs once to land the new resources.
+ * Skips the full copy only when the managed-resources.json version, content
+ * fingerprint, and package-owned gsd-browser skill all match the current
+ * install, avoiding ~128ms of synchronous cpSync on steady-state startup.
+ * After `npm update -g @opengsd/gsd-pi`, versions will differ and the copy
+ * runs once to land the new resources.
  *
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */

package/dist/resource-loader.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
@@ -24,6 +25,10 @@ const resourcesDir = resolveBundledResourcesDirFromPackageRoot(packageRoot);
 const bundledExtensionsDir = join(resourcesDir, 'extensions');
 const resourceVersionManifestName = 'managed-resources.json';
 const resourceFingerprintFileName = '.managed-resources-content-hash';
+const gsdBrowserSkillName = 'gsd-browser';
+const requireFromResourceLoader = createRequire(import.meta.url);
+const gsdBrowserSkillReferenceDirs = ['docs', 'scripts', 'gsd-browser-skill'];
+let gsdBrowserPackageSkillPathForTests;
 export { discoverExtensionEntryPaths } from './extension-discovery.js';
 export function getExtensionKey(entryPath, extensionsDir) {
     const relPath = relative(extensionsDir, entryPath);
@@ -153,6 +158,111 @@ function getCurrentResourceFingerprint() {
     }
     return computeResourceFingerprint();
 }
+function resolveGsdBrowserPackageSkillPath() {
+    if (gsdBrowserPackageSkillPathForTests !== undefined) {
+        return gsdBrowserPackageSkillPathForTests;
+    }
+    try {
+        return requireFromResourceLoader.resolve('@opengsd/gsd-browser/SKILL.md');
+    }
+    catch {
+        return null;
+    }
+}
+export function setGsdBrowserPackageSkillPathForTests(skillPath) {
+    gsdBrowserPackageSkillPathForTests = skillPath;
+}
+export function collectGsdBrowserPackageSkillReferences(content) {
+    const refs = new Set();
+    const referencePattern = /`((?:\.\/)?(?:docs|scripts|gsd-browser-skill)\/[^`\s]+)`/g;
+    for (const match of content.matchAll(referencePattern)) {
+        const ref = normalizeGsdBrowserPackageSkillReference(match[1]);
+        if (ref)
+            refs.add(ref);
+    }
+    return [...refs].sort();
+}
+function normalizeGsdBrowserPackageSkillReference(ref) {
+    if (!ref)
+        return null;
+    const normalized = ref
+        .replace(/^\.\//, '')
+        .replace(/[),.;:]+$/, '');
+    if (normalized.includes('..') || normalized.startsWith('/'))
+        return null;
+    if (!gsdBrowserSkillReferenceDirs.some(dir => normalized === dir || normalized.startsWith(`${dir}/`))) {
+        return null;
+    }
+    return normalized;
+}
+function readGsdBrowserPackageSkillBundle(sourceSkillPath) {
+    const skillContent = readFileSync(sourceSkillPath);
+    const files = new Map([['SKILL.md', skillContent]]);
+    const supportRefs = collectGsdBrowserPackageSkillReferences(skillContent.toString('utf-8'));
+    const sourceDir = dirname(sourceSkillPath);
+    for (const relPath of supportRefs) {
+        const sourcePath = join(sourceDir, relPath);
+        if (existsSync(sourcePath)) {
+            files.set(relPath, readFileSync(sourcePath));
+        }
+    }
+    return files;
+}
+export function hasStaleGsdBrowserPackageSkill(skillsDir) {
+    const targetDir = join(skillsDir, gsdBrowserSkillName);
+    const sourceSkillPath = resolveGsdBrowserPackageSkillPath();
+    // Package unresolvable. syncGsdBrowserPackageSkill is a no-op in this case
+    // (it preserves any existing managed skill), so reporting "stale" here
+    // would drive a full resource resync on every launch that the sync cannot
+    // actually satisfy. Keep the existing managed skill in place until the
+    // package becomes resolvable again or the manifest fingerprint changes.
+    if (!sourceSkillPath)
+        return false;
+    try {
+        const sourceDir = dirname(sourceSkillPath);
+        const skillContent = readFileSync(sourceSkillPath, 'utf-8');
+        for (const [relPath, content] of readGsdBrowserPackageSkillBundle(sourceSkillPath)) {
+            const targetPath = join(targetDir, relPath);
+            if (!existsSync(targetPath) || !readFileSync(targetPath).equals(content)) {
+                return true;
+            }
+        }
+        // Only flag SKILL.md references when sync can actually correct them.
+        // The bundle loop above already covers "source has it, target missing".
+        // A reference the package itself does not ship (source missing) is only
+        // worth a resync if the target still has a stale copy that sync should
+        // clean up; missing on both sides is the steady state when upstream
+        // omits files referenced from SKILL.md and is not actionable here.
+        for (const relPath of collectGsdBrowserPackageSkillReferences(skillContent)) {
+            const sourcePath = join(sourceDir, relPath);
+            const targetPath = join(targetDir, relPath);
+            if (!existsSync(sourcePath) && existsSync(targetPath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function syncGsdBrowserPackageSkill(skillsDir) {
+    const targetDir = join(skillsDir, gsdBrowserSkillName);
+    const sourceSkillPath = resolveGsdBrowserPackageSkillPath();
+    if (!sourceSkillPath)
+        return;
+    makeTreeWritable(targetDir);
+    rmSync(targetDir, { recursive: true, force: true });
+    for (const [relPath, content] of readGsdBrowserPackageSkillBundle(sourceSkillPath)) {
+        const targetPath = join(targetDir, relPath);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, content);
+        if (relPath.startsWith('scripts/') && relPath.endsWith('.sh')) {
+            chmodSync(targetPath, 0o755);
+        }
+    }
+    makeTreeWritable(targetDir);
+}
 function collectFileEntries(dir, root, out) {
     if (!existsSync(dir))
         return;
@@ -557,18 +667,20 @@ function pruneRemovedBundledExtensions(manifest, agentDir) {
     removeFileIfStale('env-utils.js');
 }
 /**
- * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
+ * Initializes managed resources under agentDir (~/.gsd/agent/).
  *
  * - extensions/ → ~/.gsd/agent/extensions/   (overwrite when version changes)
  * - shared/     → ~/.gsd/agent/shared/       (overwrite when version changes)
  * - agents/     → ~/.gsd/agent/agents/        (overwrite when version changes)
  * - skills/     → ~/.gsd/agent/skills/        (overwrite when version changes)
+ * - gsd-browser skill → ~/.gsd/agent/skills/gsd-browser/ from @opengsd/gsd-browser
  * - GSD-WORKFLOW.md → ~/.gsd/agent/GSD-WORKFLOW.md (fallback for env var miss)
  *
- * Skips the copy when the managed-resources.json version matches the current
- * GSD version, avoiding ~128ms of synchronous cpSync on every startup.
- * After `npm update -g @glittercowboy/gsd`, versions will differ and the
- * copy runs once to land the new resources.
+ * Skips the full copy only when the managed-resources.json version, content
+ * fingerprint, and package-owned gsd-browser skill all match the current
+ * install, avoiding ~128ms of synchronous cpSync on steady-state startup.
+ * After `npm update -g @opengsd/gsd-pi`, versions will differ and the copy
+ * runs once to land the new resources.
  *
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
@@ -603,11 +715,13 @@ export function initResources(agentDir, skillsDir = join(agentDir, 'skills')) {
         const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(extensionsDir, bundledExtensionsDir);
         const hasMissingSharedFiles = hasMissingBundledResourceFiles(join(agentDir, 'shared'), join(resourcesDir, 'shared'));
         const hasMissingSkillFiles = hasMissingBundledResourceFiles(skillsDir, join(resourcesDir, 'skills'));
+        const hasStaleGsdBrowserSkill = hasStaleGsdBrowserPackageSkill(skillsDir);
         if (manifest.contentHash &&
             manifest.contentHash === currentHash &&
             !hasStaleExtensionFiles &&
             !hasMissingSharedFiles &&
-            !hasMissingSkillFiles) {
+            !hasMissingSkillFiles &&
+            !hasStaleGsdBrowserSkill) {
             return;
         }
     }
@@ -616,6 +730,7 @@ export function initResources(agentDir, skillsDir = join(agentDir, 'skills')) {
     syncResourceDir(join(resourcesDir, 'shared'), join(agentDir, 'shared'));
     syncResourceDir(join(resourcesDir, 'agents'), join(agentDir, 'agents'));
     syncResourceDir(join(resourcesDir, 'skills'), skillsDir);
+    syncGsdBrowserPackageSkill(skillsDir);
     // Sync GSD-WORKFLOW.md to agentDir as a fallback for when GSD_WORKFLOW_PATH
     // env var is not set (e.g. fork/dev builds, alternative entry points).
     const workflowSrc = join(resourcesDir, 'GSD-WORKFLOW.md');
@@ -701,9 +816,8 @@ function collectRelativeFiles(rootDir) {
     return files;
 }
 /**
- * Constructs a DefaultResourceLoader that loads extensions from both
- * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).
- * This allows users to use extensions from either location.
+ * Constructs a DefaultResourceLoader that loads extensions from
+ * ~/.gsd/agent/extensions/ (GSD's default) only.
  */
 // Cache bundled extension keys at module load — avoids re-scanning the extensions
 // directory in buildResourceLoader() (already scanned by loader.ts for env var).
@@ -718,19 +832,8 @@ export async function buildResourceLoader(agentDir, options = {}) {
     const { DefaultResourceLoader } = await loadPiCodingAgentModule();
     const { sortExtensionPaths } = await import('./extension-sort.js');
     const registry = loadRegistry();
-    const piAgentDir = join(homedir(), '.pi', 'agent');
-    const piExtensionsDir = join(piAgentDir, 'extensions');
     const bundledKeys = getBundledExtensionKeys();
-    const piExtensionPaths = discoverExtensionEntryPaths(piExtensionsDir)
-        .filter((entryPath) => !bundledKeys.has(getExtensionKey(entryPath, piExtensionsDir)))
-        .filter((entryPath) => {
-        const manifest = readManifestFromEntryPath(entryPath);
-        if (!manifest)
-            return true;
-        return isExtensionEnabled(registry, manifest.id);
-    });
     const additionalExtensionPaths = [
-        ...piExtensionPaths,
         ...(options.additionalExtensionPaths ?? []),
     ];
     return new DefaultResourceLoader({

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-749698fd346380ec
+8183c5e5a7ba71fa

package/dist/resources/GSD-WORKFLOW.md

@@ -470,13 +470,13 @@ key_decisions: []
 
 **After a slice completes:**
 1. Write slice `S##-SUMMARY.md` (compresses all task summaries).
-2. Write slice `S##-UAT.md` — a non-blocking human test script derived from the slice's must-haves and demo sentence. The agent does NOT wait for UAT results.
+2. Write slice `S##-UAT.md` — a human test script derived from the slice's must-haves and demo sentence.
 3. Mark the slice checkbox in `M###-ROADMAP.md` as `[x]`.
 4. Update `STATE.md` with new position.
 5. Update milestone `M###-SUMMARY.md` with the completed slice's contributions.
-6. Continue to next slice immediately. The user tests the UAT whenever convenient.
-7. If the user reports UAT failures later, create fix tasks in the current or a new slice.
-8. If all slices done → milestone complete.
+6. Continue to next slice immediately. UAT can run after slice completion; automatic milestone closure requires each slice assessment to record `PASS`.
+7. If UAT is missing or non-PASS at milestone closeout, run `/gsd dispatch uat`, request a slice-specific UAT rerun when needed, or create remediation work with `/gsd dispatch reassess`.
+8. If all slices are done and UAT plus milestone validation pass → milestone complete.
 
 ---
 
@@ -605,6 +605,7 @@ Commit types: `feat`, `fix`, `test`, `refactor`, `docs`, `perf`, `chore`
 |---------|-----|
 | Bad task | Revert the task commit on the active branch |
 | Bad milestone squash | Revert the squash commit on the integration branch |
+| UAT missing or non-PASS at closeout | Run `/gsd dispatch uat`, request a slice-specific UAT rerun when needed, or create remediation work with `/gsd dispatch reassess` |
 | UAT failure after merge | Create follow-up fix tasks in the current or next milestone |
 
 ---