@opengsd/gsd-pi 1.1.1-dev.2034b16 → 1.1.1-dev.2de7ea0

package/src/resources/extensions/gsd/mcp-project-config.ts

@@ -1,14 +1,17 @@
-import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { basename, resolve } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  GSD_BROWSER_MCP_SERVER_NAME,
+  resolveBundledGsdBrowserCliPath,
+  resolveGsdBrowserMcpLaunchConfig,
+} from "../shared/gsd-browser-cli.js";
 import { assertSafeDirectory } from "./validate-directory.js";
 import { detectWorkflowMcpLaunchConfig } from "./workflow-mcp.js";
 
 export const GSD_WORKFLOW_MCP_SERVER_NAME = "gsd-workflow";
-export const GSD_BROWSER_MCP_SERVER_NAME = "gsd-browser";
+export { GSD_BROWSER_MCP_SERVER_NAME, resolveBundledGsdBrowserCliPath };
 
 export interface ProjectMcpServerConfig {
   command?: string;
@@ -59,31 +62,6 @@ export function resolveBundledGsdCliPath(env: NodeJS.ProcessEnv = process.env):
   return null;
 }
 
-export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
-  const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
-  if (explicit) return explicit;
-
-  try {
-    const requireFromHere = createRequire(import.meta.url);
-    const packageJsonPath = requireFromHere.resolve("@opengsd/gsd-browser/package.json");
-    const candidate = resolve(packageJsonPath, "..", "bin", "gsd-browser");
-    if (existsSync(candidate)) return candidate;
-  } catch {
-    // Fall through to path candidates for source/dist layouts.
-  }
-
-  const candidates = [
-    resolve(fileURLToPath(new URL("../../../../node_modules/@opengsd/gsd-browser/bin/gsd-browser", import.meta.url))),
-    resolve(fileURLToPath(new URL("../../../../node_modules/.bin/gsd-browser", import.meta.url))),
-  ];
-
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate;
-  }
-
-  return null;
-}
-
 export function buildProjectWorkflowMcpServerConfig(
   projectRoot: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -119,31 +97,12 @@ function buildProjectWorkflowMcpServerSpec(
   };
 }
 
-function parseJsonEnv<T>(env: NodeJS.ProcessEnv, name: string): T | undefined {
-  const raw = env[name];
-  if (!raw) return undefined;
-  try {
-    return JSON.parse(raw) as T;
-  } catch {
-    throw new Error(`Invalid JSON in ${name}`);
-  }
-}
-
 function isEnvDisabled(value: string | undefined): boolean {
   if (!value) return false;
   const normalized = value.trim().toLowerCase();
   return normalized === "0" || normalized === "false" || normalized === "off";
 }
 
-function buildBrowserSessionName(projectRoot: string): string {
-  const resolvedProjectRoot = resolve(projectRoot);
-  const base = basename(resolvedProjectRoot)
-    .replace(/[^a-zA-Z0-9._-]+/g, "-")
-    .replace(/^-+|-+$/g, "") || "project";
-  const hash = createHash("sha1").update(resolvedProjectRoot).digest("hex").slice(0, 8);
-  return `gsd-${base}-${hash}`;
-}
-
 export function buildProjectBrowserMcpServerConfig(
   projectRoot: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -157,39 +116,15 @@ function buildProjectBrowserMcpServerSpec(
 ): ProjectMcpServerSpec | null {
   if (isEnvDisabled(env.GSD_BROWSER_MCP_ENABLED)) return null;
 
-  const resolvedProjectRoot = resolve(projectRoot);
-  const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
-  const explicitArgs = parseJsonEnv<unknown>(env, "GSD_BROWSER_MCP_ARGS");
-  const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_BROWSER_MCP_ENV");
-  const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
-  const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
-  const bundledCliPath = !explicitCommand && !explicitCliPath ? resolveBundledGsdBrowserCliPath(env) : null;
-  const command =
-    explicitCommand
-    || explicitCliPath
-    || (bundledCliPath ? process.execPath : undefined)
-    || "gsd-browser";
-  const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
-    ? explicitArgs.map(String)
-    : [
-        ...(bundledCliPath ? [bundledCliPath] : []),
-        "mcp",
-        "--session",
-        buildBrowserSessionName(resolvedProjectRoot),
-        "--identity-scope",
-        "project",
-        "--identity-project",
-        resolvedProjectRoot,
-      ];
-  const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
+  const launch = resolveGsdBrowserMcpLaunchConfig(projectRoot, env);
 
   return {
-    serverName,
+    serverName: launch.serverName,
     server: {
-      command,
-      args,
-      cwd,
-      ...(explicitEnv ? { env: explicitEnv } : {}),
+      command: launch.command,
+      args: launch.args,
+      cwd: launch.cwd,
+      ...(launch.env ? { env: launch.env } : {}),
     },
   };
 }

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -9,6 +9,7 @@ import type {
   HookDispatchResult,
   PreDispatchResult,
   HookStatusEntry,
+  PostUnitGateBlock,
 } from "./types.js";
 import { getOrCreateRegistry, resolveHookArtifactPath } from "./rule-registry.js";
 
@@ -33,10 +34,22 @@ export function isRetryPending(): boolean {
   return getOrCreateRegistry().isRetryPending();
 }
 
-export function consumeRetryTrigger(): { unitType: string; unitId: string; retryArtifact: string } | null {
+export function consumeRetryTrigger(): { unitType: string; unitId: string; retryArtifact?: string } | null {
   return getOrCreateRegistry().consumeRetryTrigger();
 }
 
+export function consumeHookFailure(): { hookName: string; unitType: string; unitId: string; reason: string } | null {
+  return getOrCreateRegistry().consumeHookFailure();
+}
+
+export function isGateBlockPending(): boolean {
+  return getOrCreateRegistry().isGateBlockPending();
+}
+
+export function consumeGateBlock(): PostUnitGateBlock | null {
+  return getOrCreateRegistry().consumeGateBlock();
+}
+
 export function resetHookState(): void {
   getOrCreateRegistry().resetState();
 }

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -29,6 +29,14 @@ const VALID_UOK_TURN_ACTIONS = new Set<"commit" | "snapshot" | "status-only">([
   "snapshot",
   "status-only",
 ]);
+const VALID_POST_UNIT_HOOK_CRITICALITIES = new Set(["advisory", "blocking"]);
+const VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS = new Set([
+  "retry-unit",
+  "retry-task",
+  "queue-task",
+  "queue-slice",
+  "pause",
+]);
 
 export function validatePreferences(preferences: GSDPreferences): {
   preferences: GSDPreferences;
@@ -486,9 +494,37 @@ export function validatePreferences(preferences: GSDPreferences): {
       if (typeof hook.artifact === "string" && hook.artifact.trim()) {
         validHook.artifact = hook.artifact.trim();
       }
+      if (hook.criticality !== undefined) {
+        const criticality = typeof hook.criticality === "string" ? hook.criticality.trim() : "";
+        if (VALID_POST_UNIT_HOOK_CRITICALITIES.has(criticality)) {
+          validHook.criticality = criticality as PostUnitHookConfig["criticality"];
+        } else {
+          errors.push(`post_unit_hooks "${name}" invalid criticality: ${String(hook.criticality)}`);
+        }
+      }
       if (typeof hook.retry_on === "string" && hook.retry_on.trim()) {
         validHook.retry_on = hook.retry_on.trim();
       }
+      if (hook.on_block !== undefined) {
+        if (!hook.on_block || typeof hook.on_block !== "object") {
+          errors.push(`post_unit_hooks "${name}" on_block must be an object`);
+        } else {
+          const onBlock = hook.on_block as unknown as Record<string, unknown>;
+          const action = typeof onBlock.action === "string" ? onBlock.action.trim() : "";
+          if (!VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS.has(action)) {
+            errors.push(`post_unit_hooks "${name}" invalid on_block action: ${String(onBlock.action)}`);
+          } else {
+            validHook.on_block = { action: action as NonNullable<PostUnitHookConfig["on_block"]>["action"] };
+            if (typeof onBlock.artifact === "string" && onBlock.artifact.trim()) {
+              validHook.on_block.artifact = onBlock.artifact.trim();
+            }
+          }
+        }
+      }
+      if (validHook.criticality === "blocking" && !validHook.artifact) {
+        errors.push(`post_unit_hooks "${name}" criticality blocking requires artifact`);
+        continue;
+      }
       if (typeof hook.agent === "string" && hook.agent.trim()) {
         validHook.agent = hook.agent.trim();
       }

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -33,6 +33,10 @@ function hasRequiredExtensionAssets(rootDir: string, exists: ExistsFn = existsSy
   );
 }
 
+function isSourceExtensionDir(moduleDir: string): boolean {
+  return moduleDir.replaceAll("\\", "/").endsWith("/src/resources/extensions/gsd");
+}
+
 export function resolveExtensionDirFromCandidates(
   moduleDir: string,
   agentGsdDir: string,
@@ -41,6 +45,10 @@ export function resolveExtensionDirFromCandidates(
   const moduleUsable = hasRequiredExtensionAssets(moduleDir, exists);
   const agentUsable = hasRequiredExtensionAssets(agentGsdDir, exists);
 
+  // Source checkouts must use their own prompt tree. Otherwise local tests and
+  // dev runs can silently render stale prompts from ~/.gsd/agent/extensions/gsd.
+  if (moduleUsable && isSourceExtensionDir(moduleDir)) return moduleDir;
+
   // Prefer the user-local extension tree when both are valid. This avoids
   // leaking npm/global-install paths into prompts on Windows.
   if (agentUsable) return agentGsdDir;

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

@@ -63,35 +63,53 @@ 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 assessment path, persists to DB/disk, and saves the aggregate UAT gate. The content should follow this logical shape:
+Call `gsd_uat_result_save` once after all checks are complete. The tool computes the assessment path, persists to DB/disk, saves attempt history, and saves the aggregate UAT gate.
 
-```markdown
----
-sliceId: {{sliceId}}
-uatType: {{uatType}}
-verdict: PASS | FAIL | PARTIAL
-date: <ISO 8601 timestamp>
----
-
-# UAT Result — {{sliceId}}
-
-## Checks
+Pass these top-level fields:
 
-| Check | Mode | Result | Notes |
-|-------|------|--------|-------|
-| <check description> | artifact / runtime / human-follow-up | PASS / FAIL / NEEDS-HUMAN | <observed output, evidence, or reason> |
-
-## Overall Verdict
-
-<PASS / FAIL / PARTIAL> — <one sentence summary>
+```ts
+milestoneId: "{{milestoneId}}",
+sliceId: "{{sliceId}}",
+uatType: "{{uatType}}",
+verdict: "PASS" | "FAIL" | "PARTIAL",
+notes: "<one sentence overall verdict rationale>",
+```
 
-## Notes
+Use this exact `presentation` shape in the save call so the audit can verify the run-uat tool surface without retrying missing fields one by one:
+
+```ts
+presentation: {
+  surface: "mcp",
+  presentedTools: [
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_journal_query",
+  ],
+  blockedTools: [
+    { name: "gsd_exec", reason: "forbidden during run-uat" },
+    { name: "gsd_summary_save", reason: "forbidden during run-uat" },
+    { name: "gsd_save_gate_result", reason: "forbidden during run-uat" },
+  ],
+}
+```
 
-<any additional context, errors encountered, screenshots/logs gathered, or manual follow-up still required>
+Pass `checks` with this logical shape:
+
+```ts
+checks: [{
+  id: "<stable check id>",
+  description: "<check description from the UAT file>",
+  mode: "artifact" | "runtime" | "browser" | "human-follow-up",
+  result: "PASS" | "FAIL" | "NEEDS-HUMAN",
+  evidence: [{ kind: "gsd_uat_exec", ref: "<evidence id>" }],
+  notes: "<observed output, evidence, reason, or manual follow-up>",
+}]
 ```
 
 ---
 
-**You MUST call `gsd_summary_save` with `artifact_type: "ASSESSMENT"` and the UAT result content before finishing. Do not write the assessment file directly.**
+**You MUST call `gsd_uat_result_save` before finishing. Do not write the assessment file directly, and do not call `gsd_summary_save` as a substitute.**
 
 When done, say: "UAT {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -33,7 +33,7 @@ Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directo
 Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
 **Reviewer C - Assessment & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md` for criteria. Check slice SUMMARY and ASSESSMENT files under `.gsd/milestones/{{milestoneId}}/slices/`; UAT files are specs, not evidence. Verify each criterion maps to passing evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If a planned browser/UAT class has no ASSESSMENT with browser/runtime actions and assertions, return NEEDS-ATTENTION. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered by evidence, NEEDS-ATTENTION if gaps exist."
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md` for criteria. Check slice SUMMARY and ASSESSMENT files under `.gsd/milestones/{{milestoneId}}/slices/`; UAT files are specs, not evidence. Verify each criterion maps to passing evidence. Then review the inlined `Verification Classes (from planning)` table. For every planned row in that table, output a `Verification Classes` table with columns `Class | Planned Check | Evidence | Verdict`. Preserve every planned non-empty class row; do not summarize, rename, combine, or omit planned classes. The first cell of each row must be exactly `Contract`, `Integration`, `Operational`, or `UAT` when that class is present in planning. If a planned class lacks evidence, still include its canonical row and mark the verdict NEEDS-ATTENTION or FAIL. If a planned browser/UAT class has no ASSESSMENT with browser/runtime actions and assertions, return NEEDS-ATTENTION. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered by evidence, NEEDS-ATTENTION if gaps exist."
 
 ### Step 2 - Synthesize Findings
 
@@ -71,8 +71,8 @@ reviewers: 3
 <if verdict is not pass: specific actions required>
 ```
 
-Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If you include verification-class analysis, pass it in `verificationClasses`.
-Extract the `Verification Classes` subsection from Reviewer C and pass it verbatim in `verificationClasses` so the persisted validation output uses the canonical class names `Contract`, `Integration`, `Operational`, and `UAT`.
+Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If planning included verification classes, pass a complete canonical table in `verificationClasses`.
+Set `verificationClasses` to the `Verification Classes` subsection from Reviewer C. It must include one canonical row for every non-empty planned class from `Verification Classes (from planning)`: `Contract`, `Integration`, `Operational`, and/or `UAT`. If Reviewer C omitted a planned class, reconstruct the missing row from the planning table, set Evidence to the gap, and use NEEDS-ATTENTION or FAIL. Do not call `gsd_validate_milestone` with a partial `verificationClasses` table.
 
 **DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` - the engine owns the WAL connection. Use `gsd_milestone_status` for milestone and slice state. Data is already inlined or available via `gsd_*` tools. Direct DB access risks WAL corruption and bypasses validation.