@opengsd/gsd-pi 1.1.1-dev.a5a2de8 → 1.1.1-dev.b2556262

package/src/resources/extensions/gsd/tool-contract.ts

@@ -9,6 +9,10 @@ import {
 } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
 import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
+import {
+  WHOLE_FILE_OBSERVATION_MAX_BYTES,
+  WHOLE_FILE_OBSERVATION_MAX_LINES,
+} from "./source-observations.js";
 
 export interface UnitToolContract {
   unitType: string;
@@ -19,6 +23,7 @@ export interface UnitToolContract {
   promptObligations: readonly string[];
   validationRules: readonly string[];
   closeoutTools: readonly string[];
+  sourceObservations: UnitSourceObservationContract;
   artifacts: {
     inline: readonly ArtifactKey[];
     excerpt: readonly ArtifactKey[];
@@ -26,6 +31,16 @@ export interface UnitToolContract {
   };
 }
 
+export type UnitSourceObservationContract =
+  | { mode: "none" }
+  | {
+      mode: "whole-file-active-unit";
+      seedFields: readonly ["task.files", "task.inputs"];
+      excludedFields: readonly ["expectedOutput"];
+      maxBytes: number;
+      maxLines: number;
+    };
+
 export type ToolContractResult =
   | { ok: true; contract: UnitToolContract }
   | { ok: false; reason: "unknown-unit-type" | "missing-closeout-tool"; detail: string };
@@ -45,7 +60,7 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
   const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
     .map(([name, reason]) => ({ name, reason }));
   const closeoutTools = requiredWorkflowTools.filter((tool) =>
-    /^gsd_(?:task|slice|milestone|complete|validate|save|summary)/.test(tool),
+    /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool),
   );
 
   if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {
@@ -72,8 +87,10 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
         "unit-manifest-present",
         "workflow-tool-surface-present",
         ...(requiresCloseoutTool(unitType) ? ["closeout-tool-present"] : []),
+        ...(unitType === "execute-task" ? ["source-observation-contract-present"] : []),
       ],
       closeoutTools,
+      sourceObservations: sourceObservationContractForUnit(unitType),
       artifacts: {
         inline: manifest.artifacts.inline,
         excerpt: manifest.artifacts.excerpt,
@@ -83,6 +100,17 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
   };
 }
 
+function sourceObservationContractForUnit(unitType: string): UnitSourceObservationContract {
+  if (unitType !== "execute-task") return { mode: "none" };
+  return {
+    mode: "whole-file-active-unit",
+    seedFields: ["task.files", "task.inputs"],
+    excludedFields: ["expectedOutput"],
+    maxBytes: WHOLE_FILE_OBSERVATION_MAX_BYTES,
+    maxLines: WHOLE_FILE_OBSERVATION_MAX_LINES,
+  };
+}
+
 function requiresCloseoutTool(unitType: string): boolean {
   return /^(execute-task|reactive-execute|complete-slice|validate-milestone|complete-milestone|run-uat|gate-evaluate)$/.test(unitType);
 }

package/src/resources/extensions/gsd/tool-presentation-plan.ts

@@ -2,12 +2,15 @@
 // File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
 
 import {
+  RUN_UAT_BROWSER_TOOL_NAMES,
   RUN_UAT_READ_ONLY_TOOL_NAMES,
   RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
   RUN_UAT_WORKFLOW_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
+import { uatTypeIncludesBrowser } from "./uat-policy.js";
 
 export {
+  RUN_UAT_BROWSER_TOOL_NAMES,
   RUN_UAT_READ_ONLY_TOOL_NAMES,
   RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
   RUN_UAT_WORKFLOW_TOOL_NAMES,
@@ -32,6 +35,13 @@ export interface ToolPresentationPlan {
   diagnostics: string[];
 }
 
+export interface RunUatResultPresentation {
+  surface: ToolPresentationSurface;
+  presentedTools: string[];
+  blockedTools: Array<{ name: string; reason: string }>;
+  toolPresentationPlanId: string;
+}
+
 export const RUN_UAT_FORBIDDEN_TOOL_NAMES = [
   "edit",
   "write",
@@ -114,16 +124,41 @@ export function buildRunUatCanonicalToolNames(options: { includeBrowserTools?: r
   ]);
 }
 
+// UAT modes whose run-uat instructions direct the runner to exercise the live
+// app in a browser. These modes receive the browser tool surface so the runner
+// can actually drive the page instead of silently deferring browser checks to a
+// human. See run-uat.md automation rules: `browser-executable`, `live-runtime`,
+// and `mixed` are all told to drive a browser/runtime path, and
+// `human-experience` is told to capture screenshots. Without this, a webpage
+// UAT classified as anything but `browser-executable` had no browser tools and
+// downgraded its live checks to NEEDS-HUMAN (M001/S03 regression).
+export function runUatBrowserToolsForType(uatType: string | undefined): readonly string[] {
+  return uatTypeIncludesBrowser(uatType) ? RUN_UAT_BROWSER_TOOL_NAMES : [];
+}
+
+export function runUatPresentationSurfaceForType(uatType: string | undefined): ToolPresentationSurface {
+  return uatTypeIncludesBrowser(uatType) ? "hybrid" : "mcp";
+}
+
+export function buildRunUatPresentationForType(
+  uatType: string | undefined,
+  options: {
+    surface?: ToolPresentationSurface;
+    presentedTools?: readonly string[];
+  } = {},
+): RunUatResultPresentation {
+  return buildRunUatResultPresentation({
+    ...options,
+    surface: options.surface ?? runUatPresentationSurfaceForType(uatType),
+    includeBrowserTools: runUatBrowserToolsForType(uatType),
+  });
+}
+
 export function buildRunUatResultPresentation(options: {
   surface?: ToolPresentationSurface;
   includeBrowserTools?: readonly string[];
   presentedTools?: readonly string[];
-} = {}): {
-  surface: ToolPresentationSurface;
-  presentedTools: string[];
-  blockedTools: Array<{ name: string; reason: string }>;
-  toolPresentationPlanId: string;
-} {
+} = {}): RunUatResultPresentation {
   const presentedTools = options.presentedTools
     ? dedupe(options.presentedTools)
     : buildRunUatCanonicalToolNames({ includeBrowserTools: options.includeBrowserTools });

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -35,6 +35,7 @@ import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../path
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
+import { getDeclaredUatType, shouldEscalateArtifactUatToBrowser } from "../uat-policy.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb } from "../markdown-renderer.js";
 import { parseRoadmap } from "../parsers-legacy.js";
@@ -342,6 +343,34 @@ export async function handleCompleteSlice(
     return { error: `slice verification indicates blocked/failed state — do not complete a slice that has not passed verification. Address the blockers and re-verify first.` };
   }
 
+  // ── Browser/web UAT classification gate ────────────────────────────────
+  // A UAT that drives a running web UI (opening a page in a browser,
+  // navigating to a page/localhost) must declare a browser-capable mode so the
+  // run-uat runner surfaces browser tools and actually launches a browser.
+  // Otherwise the browser checks get silently deferred to a human and the slice
+  // passes on static checks alone (M001/S03 regression). `browser-executable`,
+  // `live-runtime`, and `mixed` all receive browser tools (see
+  // UAT_MODE_POLICIES); only the non-browser modes are rejected here.
+  //
+  // Reuse the canonical hasBrowserRequiredText detector (also used by dispatch
+  // and milestone validation): it skips Not-Proven/Out-of-Scope disclaimer
+  // sections and only treats verbs like navigate/open as web when they sit next
+  // to browser/page/localhost — avoiding false positives on CLI/file/API steps.
+  //
+  // Only `artifact-driven` is gated. It is the one mode that performs no
+  // execution at all (static/file checks), so a browser-requiring UAT under it
+  // genuinely defers verification to a human. Every other mode has a real
+  // verification path: `runtime-executable` runs browser test commands like
+  // `npx playwright test` via gsd_uat_exec, and live-runtime/mixed/
+  // browser-executable receive browser tools (UAT_MODE_POLICIES).
+  const uatContent = params.uatContent || "";
+  const declaredUatMode = getDeclaredUatType(uatContent);
+  if (shouldEscalateArtifactUatToBrowser(uatContent)) {
+    return {
+      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but declares "UAT mode: artifact-driven", which only runs static/file checks and would defer the browser work to a human. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
+    };
+  }
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -1,8 +1,9 @@
 import { existsSync, rmSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
+import { getGateIdsForTurn } from "../gate-registry.js";
 import {
   transaction,
   getMilestone,
@@ -17,14 +18,14 @@ import {
   deleteTask,
   deleteArtifactByPath,
 } from "../gsd-db.js";
-import type { GateId } from "../types.js";
+import type { GateEvaluationConfig, GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
-import { validatePlanningPathScope } from "../planning-path-scope.js";
+import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
 import { checkFilePathConsistency, checkTaskOrdering } from "../pre-execution-checks.js";
 import type { TaskRow } from "../db-task-slice-rows.js";
 import { buildTaskFileName, gsdProjectionRoot } from "../paths.js";
@@ -163,9 +164,27 @@ function validateParams(params: PlanSliceParams): PlanSliceParams {
   };
 }
 
-function loadRepositoryRegistry(basePath: string): RepositoryRegistry {
+function loadPlanningContext(basePath: string): {
+  repositoryRegistry: RepositoryRegistry;
+  gateEvaluation?: GateEvaluationConfig;
+} {
   const loaded = loadEffectiveGSDPreferences(basePath);
-  return createRepositoryRegistryFromPreferences(basePath, loaded?.preferences);
+  return {
+    repositoryRegistry: createRepositoryRegistryFromPreferences(basePath, loaded?.preferences),
+    gateEvaluation: loaded?.preferences?.gate_evaluation,
+  };
+}
+
+function resolveGateEvaluateSliceGates(config: GateEvaluationConfig | undefined): GateId[] {
+  const ownedGateIds = [...getGateIdsForTurn("gate-evaluate")];
+  if (!config?.slice_gates?.length) return ownedGateIds;
+  const owned = new Set<string>(ownedGateIds);
+  return config.slice_gates.filter((gateId): gateId is GateId => owned.has(gateId));
+}
+
+function resolveTaskGates(config: GateEvaluationConfig | undefined): GateId[] {
+  if (config?.task_gates === false) return [];
+  return [...getGateIdsForTurn("execute-task")];
 }
 
 function validateReferencedRepositories(
@@ -238,11 +257,21 @@ function toTaskRows(params: PlanSliceParams, defaultTargets: string[]): TaskRow[
   }));
 }
 
-function validateTaskPathsBeforePersist(params: PlanSliceParams, basePath: string, defaultTargets: string[]): string | null {
+function validateTaskPathsBeforePersist(
+  params: PlanSliceParams,
+  basePath: string,
+  defaultTargets: string[],
+  allowedRoots: string[],
+): string | null {
   const taskRows = toTaskRows(params, defaultTargets);
+  const baseRoot = resolve(basePath);
+  const additionalRoots = allowedRoots
+    .map((root) => resolve(root))
+    .filter((root) => root !== baseRoot);
+  const context = additionalRoots.length > 0 ? { additionalRoots } : undefined;
   const checks = [
-    ...checkFilePathConsistency(taskRows, basePath),
-    ...checkTaskOrdering(taskRows, basePath),
+    ...checkFilePathConsistency(taskRows, basePath, context),
+    ...checkTaskOrdering(taskRows, basePath, context),
   ];
   const blocking = checks.filter((check) => !check.passed && check.blocking);
 
@@ -265,8 +294,11 @@ export async function handlePlanSlice(
   }
 
   let repositoryRegistry: RepositoryRegistry;
+  let gateEvaluation: GateEvaluationConfig | undefined;
   try {
-    repositoryRegistry = loadRepositoryRegistry(basePath);
+    const context = loadPlanningContext(basePath);
+    repositoryRegistry = context.repositoryRegistry;
+    gateEvaluation = context.gateEvaluation;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { error: `validation failed: ${message}` };
@@ -279,6 +311,16 @@ export async function handlePlanSlice(
 
   const allowedAbsoluteRoots = resolveAllowedRootsForPathScope(params, repositoryRegistry, defaultTargets);
 
+  const pathOnlyError = validatePathOnlyPlanningFields(
+    params.tasks.map((task, index) => ({
+      field: `tasks[${index}].expectedOutput`,
+      values: task.expectedOutput,
+    })),
+  );
+  if (pathOnlyError) {
+    return { error: `validation failed: ${pathOnlyError}` };
+  }
+
   const pathScopeError = validatePlanningPathScope(
     basePath,
     params.tasks.flatMap((task, index) => [
@@ -292,7 +334,7 @@ export async function handlePlanSlice(
     return { error: `validation failed: ${pathScopeError}` };
   }
 
-  const pathError = validateTaskPathsBeforePersist(params, basePath, defaultTargets);
+  const pathError = validateTaskPathsBeforePersist(params, basePath, defaultTargets, allowedAbsoluteRoots);
   if (pathError) {
     return { error: `pre-execution validation failed:\n${pathError}` };
   }
@@ -384,11 +426,11 @@ export async function handlePlanSlice(
 
       // Seed quality gate rows inside the transaction — all-or-nothing with
       // the plan data so a crash can't leave orphaned gates without tasks.
-      const sliceGates: GateId[] = ["Q3", "Q4"];
+      const sliceGates = resolveGateEvaluateSliceGates(gateEvaluation);
       for (const gid of sliceGates) {
         insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "slice" });
       }
-      const taskGates: GateId[] = ["Q5", "Q6", "Q7"];
+      const taskGates = resolveTaskGates(gateEvaluation);
       for (const task of params.tasks) {
         for (const gid of taskGates) {
           insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: task.taskId });

package/src/resources/extensions/gsd/tools/plan-task.ts

@@ -8,7 +8,7 @@ import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
-import { validatePlanningPathScope } from "../planning-path-scope.js";
+import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
 
 export interface PlanTaskParams {
   milestoneId: string;
@@ -67,6 +67,13 @@ export async function handlePlanTask(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
+  const pathOnlyError = validatePathOnlyPlanningFields([
+    { field: "expectedOutput", values: params.expectedOutput },
+  ]);
+  if (pathOnlyError) {
+    return { error: `validation failed: ${pathOnlyError}` };
+  }
+
   const pathScopeError = validatePlanningPathScope(basePath, [
     { field: "files", values: params.files },
     { field: "inputs", values: params.inputs },