@opengsd/gsd-pi 1.1.1-dev.3ea310e → 1.1.1-dev.595401e

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/complete-task.ts

@@ -12,7 +12,7 @@
 
 import { join } from "node:path";
 
-import type { CompleteTaskParams } from "../types.js";
+import type { CompleteTaskParams, EscalationArtifact } from "../types.js";
 import { isClosedStatus } from "../status-guards.js";
 import {
   transaction,
@@ -48,6 +48,14 @@ export interface CompleteTaskResult {
   sliceId: string;
   milestoneId: string;
   summaryPath: string;
+  escalation?: {
+    artifactPath: string;
+    question: string;
+    options: EscalationArtifact["options"];
+    recommendation: string;
+    recommendationRationale: string;
+    continueWithDefault: boolean;
+  };
   /**
    * True when this call re-completed an already-closed task from a turn that
    * had been superseded by timeout recovery or cancellation. The underlying
@@ -407,9 +415,18 @@ export async function handleCompleteTask(
   // 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: CompleteTaskResult["escalation"] | undefined;
   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 as Error).message}`;
       logWarning("tool", msg);
@@ -477,6 +494,7 @@ export async function handleCompleteTask(
     sliceId: params.sliceId,
     milestoneId: params.milestoneId,
     summaryPath,
+    ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
     ...(projectionStale ? { stale: true } : {}),
   };
 }

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`,

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -78,18 +78,10 @@ function getRequiredVerificationClasses(milestoneId: string): string[] {
   return required;
 }
 
-async function collectPersistedBrowserEvidence(basePath: string, milestoneId: string): Promise<string> {
-  const chunks: string[] = [];
-  for (const slice of getMilestoneSlices(milestoneId)) {
-    const artifactPath = `milestones/${milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-    const artifact = getArtifact(artifactPath);
-    if (artifact?.full_content) chunks.push(artifact.full_content);
-
-    const assessmentPath = resolveSliceFile(basePath, milestoneId, slice.id, "ASSESSMENT");
-    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-    if (assessmentContent) chunks.push(assessmentContent);
-  }
-  return chunks.join("\n\n");
+function hasRuntimeExecutableUatEvidenceText(text: string): boolean {
+  if (!/\buatType:\s*runtime-executable\b/i.test(text)) return false;
+  if (!/\bverdict:\s*PASS\b/i.test(text)) return false;
+  return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
 }
 
 async function browserEvidenceGateRequiresAttention(
@@ -114,7 +106,38 @@ async function browserEvidenceGateRequiresAttention(
   ]);
   if (!hasBrowserRequiredText(requirementText)) return false;
 
-  const persistedEvidence = await collectPersistedBrowserEvidence(basePath, params.milestoneId);
+  // Collect per-slice evidence so the runtime bypass is checked independently
+  // for each slice. Concatenating all slices before checking would allow runtime
+  // evidence from one slice to cover another slice's browser requirements.
+  const sliceEvidencePairs: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
+  for (const slice of slices) {
+    const chunks: string[] = [];
+    const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+    const artifact = getArtifact(artifactPath);
+    if (artifact?.full_content) chunks.push(artifact.full_content);
+    const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+    if (assessmentContent) chunks.push(assessmentContent);
+    sliceEvidencePairs.push({
+      sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+      evidenceText: chunks.join("\n\n"),
+    });
+  }
+  const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
+
+  // Runtime bypass: each slice whose own requirement text has browser-observable
+  // criteria must have its own runtime-executable UAT evidence. When no individual
+  // slice has slice-level browser requirements (e.g., they come from milestone-level
+  // fields only), fall back to checking whether any slice has runtime evidence.
+  const browserRequiringSlices = sliceEvidencePairs.filter((s) =>
+    hasBrowserRequiredText(s.sliceRequirementText),
+  );
+  const runtimeBypasses =
+    browserRequiringSlices.length > 0
+      ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
+      : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
+  if (runtimeBypasses) return false;
+
   const validationEvidence = compactTextParts([
     params.successCriteriaChecklist,
     params.verificationClasses,
@@ -184,14 +207,22 @@ export async function handleValidateMilestone(
   const requiredClasses = getRequiredVerificationClasses(params.milestoneId);
   if (requiredClasses.length > 0) {
     const verificationClasses = params.verificationClasses ?? "";
-    const missingClass = requiredClasses.find(
+    const missingClasses = requiredClasses.filter(
       (className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses),
     );
-    if (missingClass) {
+    if (missingClasses.length === 1) {
+      const missingClass = missingClasses[0];
       return {
         error: `verificationClasses must include canonical row "${missingClass}" because this milestone planned ${missingClass.toLowerCase()} verification`,
       };
     }
+    if (missingClasses.length > 1) {
+      const quotedClasses = missingClasses.map((className) => `"${className}"`).join(", ");
+      const plannedClasses = missingClasses.map((className) => className.toLowerCase()).join(", ");
+      return {
+        error: `verificationClasses must include canonical rows ${quotedClasses} because this milestone planned ${plannedClasses} verification`,
+      };
+    }
   }
 
   const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);