@opengsd/gsd-pi 1.1.1-dev.3ea310e → 1.1.1-dev.74e8dd1

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -30,6 +30,7 @@ import {
   executeSliceComplete,
   executeSliceReopen,
   executeValidateMilestone,
+  executeUatResultSave,
 } from "../tools/workflow-tool-executors.ts";
 
 function makeTmpBase(): string {
@@ -504,6 +505,88 @@ test("executePlanSlice marks validation failures with isError", async () => {
   }
 });
 
+test("executeUatResultSave accepts gsd_uat_exec evidence written in a milestone worktree", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const browserTimelineDir = join(base, ".artifacts", "browser", "session");
+  const evidenceId = "worktree-uat-evidence";
+  const browserTimelinePath = join(browserTimelineDir, "s02-uat-browser-timeline.json");
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S02", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    mkdirSync(browserTimelineDir, { recursive: true });
+    writeFileSync(browserTimelinePath, JSON.stringify({ summary: "browser timeline evidence" }), "utf-8");
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S02",
+          checkId: "UAT-01",
+          intent: "uat-runtime-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S02",
+      uatType: "runtime-executable",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Runtime path C:\\tmp|uat evidence was captured in the active worktree",
+        mode: "runtime",
+        result: "PASS",
+        evidence: [
+          { kind: "gsd_uat_exec", ref: evidenceId },
+          { kind: "browser", ref: browserTimelinePath },
+        ],
+        notes: "Worktree-local gsd_uat_exec metadata should resolve with backslash \\ and pipe |.",
+      }],
+      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" },
+        ],
+      },
+      notes: "UAT passed with worktree-local evidence.",
+    }, worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.operation, "save_uat_result");
+    assert.equal(result.details.verdict, "PASS");
+    assert.ok(
+      existsSync(join(base, ".gsd", "uat", "M001", "S02", "attempt-1.json")),
+      "attempt JSON should be persisted under the authoritative project .gsd",
+    );
+    const assessment = readFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-ASSESSMENT.md"),
+      "utf-8",
+    );
+    assert.match(assessment, /Runtime path C:\\\\tmp\\\|uat evidence/);
+    assert.match(assessment, /backslash \\\\ and pipe \\\|/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSliceComplete coerces string enrichment entries and writes summary/UAT artifacts", async () => {
   const base = makeTmpBase();
   try {

package/src/resources/extensions/gsd/tests/write-gate-planning-unit.test.ts

@@ -27,6 +27,10 @@ const PLANNING_DISPATCH_REVIEW: ToolsPolicy = {
 const READ_ONLY: ToolsPolicy = { mode: 'read-only' };
 const ALL: ToolsPolicy = { mode: 'all' };
 const VERIFICATION: ToolsPolicy = { mode: 'verification' };
+const VERIFICATION_UAT: ToolsPolicy = {
+  mode: 'verification',
+  allowedSubagents: ['mnemo', 'scout', 'reviewer', 'tester'],
+};
 const DOCS: ToolsPolicy = {
   mode: 'docs',
   allowedPathGlobs: ['docs/**', 'README.md', 'README.*.md', 'CHANGELOG.md', '*.md'],
@@ -469,6 +473,27 @@ test('verification-mode: run-uat still blocks subagent dispatch', () => {
   assert.match(r.reason!, /subagent dispatch is not permitted/);
 });
 
+test('verification-mode: run-uat allows explicit UAT specialist subagents', () => {
+  for (const agent of ['mnemo', 'scout', 'reviewer', 'tester']) {
+    const r = shouldBlockPlanningUnit('subagent', '', BASE, 'run-uat', VERIFICATION_UAT, [agent]);
+    assert.strictEqual(r.block, false, `expected ${agent} to be allowed: ${r.reason}`);
+  }
+});
+
+test('verification-mode: run-uat blocks implementation-tier subagents', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'run-uat', VERIFICATION_UAT, ['worker']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"worker"/);
+  assert.match(r.reason!, /read-only specialists/);
+});
+
+test('verification-mode: run-uat blocks read-only specialists not listed by policy', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'run-uat', VERIFICATION_UAT, ['security']);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /"security"/);
+  assert.match(r.reason!, /ToolsPolicy\.allowedSubagents|permitted agents for this unit/);
+});
+
 // ─── read-only mode ───────────────────────────────────────────────────────
 
 test('read-only: blocks any edit even to .gsd/', () => {

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -20,6 +20,7 @@ export interface ExecToolParams {
   cmd?: unknown;
   code?: unknown;
   purpose?: string;
+  metadata?: Record<string, unknown>;
   timeout_ms?: number;
 }
 
@@ -33,6 +34,44 @@ export interface ExecToolDeps {
   generateId?: () => string;
 }
 
+export type UatExecIntent =
+  | "uat-artifact-check"
+  | "uat-runtime-check"
+  | "uat-browser-check"
+  | "uat-service-start"
+  | "uat-log-inspection";
+
+export interface UatExecToolParams extends ExecToolParams {
+  milestoneId?: unknown;
+  sliceId?: unknown;
+  checkId?: unknown;
+  intent?: unknown;
+  expected?: unknown;
+}
+
+const UAT_EXEC_INTENTS: readonly UatExecIntent[] = [
+  "uat-artifact-check",
+  "uat-runtime-check",
+  "uat-browser-check",
+  "uat-service-start",
+  "uat-log-inspection",
+] as const;
+
+const UAT_EXEC_INTENT_ALIASES: Record<string, UatExecIntent> = {
+  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: string,
   cfg: ContextModeConfig | undefined,
@@ -112,6 +151,39 @@ function normalizeScript(params: ExecToolParams): string | ToolExecutionResult {
   return paramError("script is required and must be a non-empty string");
 }
 
+function normalizeRequiredString(value: unknown, field: string): string | ToolExecutionResult {
+  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: unknown): UatExecIntent | ToolExecutionResult {
+  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 as readonly string[]).includes(normalized)) return normalized as UatExecIntent;
+  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: string): string | null {
+  const patterns: Array<{ re: RegExp; reason: string }> = [
+    { 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: unknown): value is ToolExecutionResult {
   return typeof value === "object" && value !== null && Array.isArray((value as { content?: unknown }).content);
 }
@@ -266,6 +338,7 @@ export async function executeGsdExec(
         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,
@@ -281,6 +354,63 @@ export async function executeGsdExec(
   }
 }
 
+export async function executeUatExec(
+  params: UatExecToolParams,
+  deps: ExecToolDeps,
+): Promise<ToolExecutionResult> {
+  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: ExecSandboxResult): ToolExecutionResult {
   const headerLines = [
     `gsd_exec[${result.id}] runtime=${result.runtime} exit=${formatExit(result)} duration=${result.duration_ms}ms`,