@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.b1abb545

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

@@ -4,8 +4,10 @@
 import {
   resolveManifest,
   type ArtifactKey,
+  type ComputedArtifactId,
   type ContextModePolicy,
   type ToolsPolicy,
+  type UnitContextManifest,
 } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
 import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
@@ -21,6 +23,7 @@ export interface UnitToolContract {
   requiredWorkflowTools: readonly string[];
   forbiddenWorkflowTools: readonly { name: string; reason: string }[];
   promptObligations: readonly string[];
+  promptContext: UnitPromptContextContract;
   validationRules: readonly string[];
   closeoutTools: readonly string[];
   sourceObservations: UnitSourceObservationContract;
@@ -31,6 +34,22 @@ export interface UnitToolContract {
   };
 }
 
+export interface UnitPromptContextContract {
+  unitType: string;
+  contextMode: ContextModePolicy;
+  toolsPolicy: ToolsPolicy;
+  obligations: readonly string[];
+  sourceObservations: UnitSourceObservationContract;
+  artifacts: {
+    inline: readonly ArtifactKey[];
+    excerpt: readonly ArtifactKey[];
+    onDemand: readonly ArtifactKey[];
+    computed: readonly ComputedArtifactId[];
+    prepend: readonly ComputedArtifactId[];
+  };
+  maxSystemPromptChars: number;
+}
+
 export type UnitSourceObservationContract =
   | { mode: "none" }
   | {
@@ -45,6 +64,22 @@ export type ToolContractResult =
   | { ok: true; contract: UnitToolContract }
   | { ok: false; reason: "unknown-unit-type" | "missing-closeout-tool"; detail: string };
 
+export type UnitContextContractResult =
+  | { ok: true; contract: UnitPromptContextContract }
+  | { ok: false; reason: "unknown-unit-type"; detail: string };
+
+export function compileUnitContextContract(unitType: string): UnitContextContractResult {
+  const manifest = resolveManifest(unitType);
+  if (!manifest) {
+    return {
+      ok: false,
+      reason: "unknown-unit-type",
+      detail: `No Unit manifest is registered for ${unitType}`,
+    };
+  }
+  return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
+}
+
 export function compileUnitToolContract(unitType: string): ToolContractResult {
   const manifest = resolveManifest(unitType);
   const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -71,6 +106,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
     };
   }
 
+  const promptContext = buildPromptContextContract(unitType, manifest);
+
   return {
     ok: true,
     contract: {
@@ -79,10 +116,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
       toolsPolicy: manifest.tools,
       requiredWorkflowTools,
       forbiddenWorkflowTools,
-      promptObligations: [
-        `context-mode:${manifest.contextMode}`,
-        `tools-policy:${manifest.tools.mode}`,
-      ],
+      promptObligations: promptContext.obligations,
+      promptContext,
       validationRules: [
         "unit-manifest-present",
         "workflow-tool-surface-present",
@@ -90,16 +125,59 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
         ...(unitType === "execute-task" ? ["source-observation-contract-present"] : []),
       ],
       closeoutTools,
-      sourceObservations: sourceObservationContractForUnit(unitType),
+      sourceObservations: promptContext.sourceObservations,
       artifacts: {
-        inline: manifest.artifacts.inline,
-        excerpt: manifest.artifacts.excerpt,
-        onDemand: manifest.artifacts.onDemand,
+        inline: promptContext.artifacts.inline,
+        excerpt: promptContext.artifacts.excerpt,
+        onDemand: promptContext.artifacts.onDemand,
       },
     },
   };
 }
 
+function buildPromptContextContract(
+  unitType: string,
+  manifest: UnitContextManifest,
+): UnitPromptContextContract {
+  const sourceObservations = sourceObservationContractForUnit(unitType);
+  return {
+    unitType,
+    contextMode: manifest.contextMode,
+    toolsPolicy: manifest.tools,
+    obligations: promptContextObligations(manifest, sourceObservations),
+    sourceObservations,
+    artifacts: {
+      inline: manifest.artifacts.inline,
+      excerpt: manifest.artifacts.excerpt,
+      onDemand: manifest.artifacts.onDemand,
+      computed: manifest.artifacts.computed ?? [],
+      prepend: manifest.prepend ?? [],
+    },
+    maxSystemPromptChars: manifest.maxSystemPromptChars,
+  };
+}
+
+function promptContextObligations(
+  manifest: UnitContextManifest,
+  sourceObservations: UnitSourceObservationContract,
+): string[] {
+  const obligations = [
+    `context-mode:${manifest.contextMode}`,
+    `tools-policy:${manifest.tools.mode}`,
+    artifactObligation("context-inline", manifest.artifacts.inline),
+    artifactObligation("context-excerpt", manifest.artifacts.excerpt),
+    artifactObligation("context-on-demand", manifest.artifacts.onDemand),
+  ];
+  if (sourceObservations.mode !== "none") {
+    obligations.push(`source-observations:${sourceObservations.mode}`);
+  }
+  return obligations;
+}
+
+function artifactObligation(label: string, artifacts: readonly ArtifactKey[]): string {
+  return `${label}:${artifacts.length > 0 ? artifacts.join(",") : "none"}`;
+}
+
 function sourceObservationContractForUnit(unitType: string): UnitSourceObservationContract {
   if (unitType !== "execute-task") return { mode: "none" };
   return {

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

@@ -7,7 +7,10 @@ import {
   RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
   RUN_UAT_WORKFLOW_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
+import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
+import { createToolSurfaceSnapshot, type ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
 
 export {
   RUN_UAT_BROWSER_TOOL_NAMES,
@@ -33,6 +36,7 @@ export interface ToolPresentationPlan {
   blockedToolNames: Array<{ name: string; reason: string }>;
   aliases: Array<{ requested: string; canonical: string }>;
   diagnostics: string[];
+  toolSurface: ToolSurfaceSnapshot;
 }
 
 export interface RunUatResultPresentation {
@@ -62,44 +66,14 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
   "Grep",
 ] as const;
 
-const WORKFLOW_ALIAS_TO_CANONICAL: Record<string, string> = {
-  gsd_save_decision: "gsd_decision_save",
-  gsd_update_requirement: "gsd_requirement_update",
-  gsd_save_requirement: "gsd_requirement_save",
-  gsd_save_summary: "gsd_summary_save",
-  gsd_generate_milestone_id: "gsd_milestone_generate_id",
-  gsd_milestone_plan: "gsd_plan_milestone",
-  gsd_slice_plan: "gsd_plan_slice",
-  gsd_task_plan: "gsd_plan_task",
-  gsd_slice_replan: "gsd_replan_slice",
-  gsd_complete_slice: "gsd_slice_complete",
-  gsd_milestone_complete: "gsd_complete_milestone",
-  gsd_milestone_validate: "gsd_validate_milestone",
-  gsd_roadmap_reassess: "gsd_reassess_roadmap",
-  gsd_complete_task: "gsd_task_complete",
-  gsd_reopen_task: "gsd_task_reopen",
-  gsd_reopen_slice: "gsd_slice_reopen",
-  gsd_reopen_milestone: "gsd_milestone_reopen",
-};
-
 export function canonicalWorkflowToolName(toolName: string): string {
-  const mcp = parseMcpToolName(toolName);
-  const baseName = mcp?.tool ?? toolName;
-  return WORKFLOW_ALIAS_TO_CANONICAL[baseName] ?? baseName;
+  return canonicalWorkflowSurfaceToolName(toolName);
 }
 
-export function parseMcpToolName(toolName: string): { server: string; tool: string } | null {
-  if (!toolName.startsWith("mcp__")) return null;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  if (toolSeparator < 0) return null;
-  return {
-    server: toolName.slice("mcp__".length, toolSeparator),
-    tool: toolName.slice(toolSeparator + 2),
-  };
-}
+export { parseMcpToolName } from "./mcp-tool-name.js";
 
 export function toWorkflowMcpToolName(serverName: string, toolName: string): string {
-  return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+  return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));
 }
 
 function dedupe(values: readonly string[]): string[] {
@@ -212,6 +186,14 @@ export function resolveToolPresentationPlan(options: {
           : name
       )
     : allowedToolNames;
+  const toolSurface = createToolSurfaceSnapshot({
+    source: "presentation-plan",
+    phase: options.phase,
+    modelFacingToolNames: options.availableToolNames ?? requested,
+    registeredToolNames: options.availableToolNames ?? requested,
+    scopedToolNames: allowedToolNames,
+    presentedToolNames,
+  });
 
   if (options.phase === "run-uat") {
     for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
@@ -228,5 +210,6 @@ export function resolveToolPresentationPlan(options: {
     blockedToolNames,
     aliases,
     diagnostics: [],
+    toolSurface,
   };
 }

package/src/resources/extensions/gsd/tool-surface-snapshot.ts

@@ -0,0 +1,47 @@
+// Project/App: gsd-pi
+// File Purpose: Typed snapshots for model-facing, registered, scoped, and presented tool surfaces.
+
+export type ToolSurfaceSnapshotSource =
+  | "runtime-scope"
+  | "dispatch-scope"
+  | "provider-adjustment"
+  | "presentation-plan";
+
+export interface ToolSurfaceSnapshot {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames: string[];
+  registeredToolNames: string[];
+  scopedToolNames: string[];
+  presentedToolNames: string[];
+  capturedAt: number;
+}
+
+export interface ToolSurfaceSnapshotInput {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames?: readonly string[];
+  registeredToolNames?: readonly string[];
+  scopedToolNames?: readonly string[];
+  presentedToolNames?: readonly string[];
+  capturedAt?: number;
+}
+
+function dedupeToolNames(toolNames: readonly string[] | undefined): string[] {
+  return [...new Set(toolNames ?? [])];
+}
+
+export function createToolSurfaceSnapshot(input: ToolSurfaceSnapshotInput): ToolSurfaceSnapshot {
+  return {
+    source: input.source,
+    unitType: input.unitType,
+    phase: input.phase,
+    modelFacingToolNames: dedupeToolNames(input.modelFacingToolNames),
+    registeredToolNames: dedupeToolNames(input.registeredToolNames),
+    scopedToolNames: dedupeToolNames(input.scopedToolNames),
+    presentedToolNames: dedupeToolNames(input.presentedToolNames),
+    capturedAt: input.capturedAt ?? Date.now(),
+  };
+}

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

@@ -1,25 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Plans milestone roadmap state through DB-backed workflow tools.
 
-import { clearParseCache } from "../files.js";
-import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray, validateTitle } from "../validation.js";
-import {
-  transaction,
-  getMilestone,
-  getMilestoneSlices,
-  getSlice,
-  insertMilestone,
-  insertSlice,
-  upsertMilestonePlanning,
-  upsertSlicePlanning,
-} from "../gsd-db.js";
-import { invalidateStateCache } from "../state.js";
-import { renderRoadmapFromDb } 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 { persistMilestonePlan } from "../milestone-planning-persistence.js";
 
 export interface PlanMilestoneSliceInput {
   sliceId: string;
@@ -115,11 +98,21 @@ function validateProofStrategy(value: unknown): Array<{ riskOrUnknown: string; r
   });
 }
 
+const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+
 function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
   if (!Array.isArray(value) || value.length === 0) {
     throw new Error("slices must be a non-empty array");
   }
 
+  // Pre-collect all slice IDs so depends cross-validation can reference the full set.
+  const allSliceIds = new Set<string>(
+    (value as unknown[])
+      .filter((e): e is Record<string, unknown> => !!e && typeof e === "object")
+      .map(e => e.sliceId)
+      .filter((id): id is string => isNonEmptyString(id)),
+  );
+
   const seen = new Set<string>();
   return value.map((entry, index) => {
     if (!entry || typeof entry !== "object") {
@@ -154,8 +147,13 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     const titleIssue = validateTitle(title);
     if (titleIssue) throw new Error(`slices[${index}].title is invalid: ${titleIssue}`);
     if (!isNonEmptyString(risk)) throw new Error(`slices[${index}].risk must be a non-empty string`);
-    if (!Array.isArray(depends) || depends.some((item) => !isNonEmptyString(item))) {
-      throw new Error(`slices[${index}].depends must be an array of non-empty strings`);
+    if (!Array.isArray(depends) || depends.some((item) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+      throw new Error(`slices[${index}].depends must be an array of valid slice IDs (e.g. "S01")`);
+    }
+    for (const dep of depends as string[]) {
+      if (!allSliceIds.has(dep)) {
+        throw new Error(`slices[${index}].depends references unknown slice "${dep}" — check that it is defined in the same milestone`);
+      }
     }
     if (!isNonEmptyString(demo)) throw new Error(`slices[${index}].demo must be a non-empty string`);
     if (!isNonEmptyString(goal)) throw new Error(`slices[${index}].goal must be a non-empty string`);
@@ -227,144 +225,5 @@ export async function handlePlanMilestone(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
-  // Guards must be inside the transaction so the state they check cannot
-  // change between the read and the write (#2723).
-  let guardError: string | null = null;
-
-  try {
-    transaction(() => {
-      const existingMilestone = getMilestone(params.milestoneId);
-      if (existingMilestone && isClosedStatus(existingMilestone.status)) {
-        guardError = `cannot re-plan milestone ${params.milestoneId}: it is already complete`;
-        return;
-      }
-
-      // Guard: refuse to re-plan a milestone that would drop completed slices (#2960).
-      // Allow re-planning when all completed slices are still present in the
-      // incoming plan — their status is preserved below (#2558). Block only when
-      // the new plan omits a completed slice, which could shadow completed work.
-      const existingSlices = getMilestoneSlices(params.milestoneId);
-      const completedSlices = existingSlices.filter(s => isClosedStatus(s.status));
-      if (completedSlices.length > 0) {
-        const incomingSliceIds = new Set(params.slices.map(s => s.sliceId));
-        const droppedCompleted = completedSlices.filter(s => !incomingSliceIds.has(s.id));
-        if (droppedCompleted.length > 0) {
-          guardError = `cannot re-plan milestone ${params.milestoneId}: ${droppedCompleted.length} completed slice(s) would be dropped (${droppedCompleted.map(s => s.id).join(", ")}). Use gsd_reassess_roadmap to modify the roadmap.`;
-          return;
-        }
-      }
-
-      // Validate depends_on: all dependencies must exist and be complete
-      if (params.dependsOn && params.dependsOn.length > 0) {
-        for (const depId of params.dependsOn) {
-          const dep = getMilestone(depId);
-          if (!dep) {
-            guardError = `depends_on references unknown milestone: ${depId}`;
-            return;
-          }
-          if (!isClosedStatus(dep.status)) {
-            guardError = `depends_on milestone ${depId} is not yet complete (status: ${dep.status})`;
-            return;
-          }
-        }
-      }
-
-      insertMilestone({
-        id: params.milestoneId,
-        title: params.title,
-        status: params.status ?? "active",
-        depends_on: params.dependsOn ?? [],
-      });
-
-      upsertMilestonePlanning(params.milestoneId, {
-        title: params.title,
-        status: params.status ?? "active",
-        depends_on: params.dependsOn ?? [],
-        vision: params.vision,
-        successCriteria: params.successCriteria,
-        keyRisks: params.keyRisks,
-        proofStrategy: params.proofStrategy,
-        verificationContract: params.verificationContract,
-        verificationIntegration: params.verificationIntegration,
-        verificationOperational: params.verificationOperational,
-        verificationUat: params.verificationUat,
-        definitionOfDone: params.definitionOfDone,
-        requirementCoverage: params.requirementCoverage,
-        boundaryMapMarkdown: params.boundaryMapMarkdown,
-      });
-
-      for (let i = 0; i < params.slices.length; i++) {
-        const slice = params.slices[i]!;
-        // Preserve completed/done status on re-plan (#2558).
-        // Without this, a re-plan after milestone transition would reset
-        // already-completed slices back to "pending".
-        const existing = getSlice(params.milestoneId, slice.sliceId);
-        const status = existing && (existing.status === "complete" || existing.status === "done")
-          ? existing.status
-          : "pending";
-        insertSlice({
-          id: slice.sliceId,
-          milestoneId: params.milestoneId,
-          title: slice.title,
-          status,
-          risk: slice.risk,
-          depends: slice.depends,
-          demo: slice.demo,
-          sequence: i + 1, // Preserve agent-ordered sequence (#3356)
-          // ADR-011: pass undefined through so ON CONFLICT preserves existing values
-          // when the caller omitted the fields on a re-plan.
-          isSketch: slice.isSketch,
-          sketchScope: slice.sketchScope,
-        });
-        upsertSlicePlanning(params.milestoneId, slice.sliceId, {
-          goal: slice.goal,
-          successCriteria: slice.successCriteria,
-          proofLevel: slice.proofLevel,
-          integrationClosure: slice.integrationClosure,
-          observabilityImpact: slice.observabilityImpact,
-        });
-      }
-    });
-  } catch (err) {
-    return { error: `db write failed: ${(err as Error).message}` };
-  }
-
-  if (guardError) {
-    return { error: guardError };
-  }
-
-  let roadmapPath: string;
-  try {
-    const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);
-    roadmapPath = renderResult.roadmapPath;
-  } catch (renderErr) {
-    logWarning("tool", `plan_milestone — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}`);
-    invalidateStateCache();
-    return { error: `render failed: ${(renderErr as Error).message}` };
-  }
-
-  invalidateStateCache();
-  clearParseCache();
-
-  // ── Post-mutation hook: projections, manifest, event log ───────────────
-  try {
-    await renderAllProjections(basePath, params.milestoneId);
-    writeManifest(basePath);
-    appendEvent(basePath, {
-      cmd: "plan-milestone",
-      params: { milestoneId: params.milestoneId },
-      ts: new Date().toISOString(),
-      actor: "agent",
-      actor_name: params.actorName,
-      trigger_reason: params.triggerReason,
-    });
-  } catch (hookErr) {
-    logWarning("tool", `plan-milestone post-mutation hook warning: ${(hookErr as Error).message}`);
-  }
-
-  return {
-    milestoneId: params.milestoneId,
-    roadmapPath,
-  };
+  return persistMilestonePlan(params, basePath);
 }

package/src/resources/extensions/gsd/tools/reassess-roadmap.ts

@@ -75,12 +75,19 @@ function validateParams(params: ReassessRoadmapParams): ReassessRoadmapParams {
     throw new Error("sliceChanges.removed must be an array");
   }
 
+  const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+
   // Validate each modified slice
   for (let i = 0; i < params.sliceChanges.modified.length; i++) {
     const s = params.sliceChanges.modified[i];
     if (!s || typeof s !== "object") throw new Error(`sliceChanges.modified[${i}] must be an object`);
     if (!isNonEmptyString(s.sliceId)) throw new Error(`sliceChanges.modified[${i}].sliceId is required`);
     if (!isNonEmptyString(s.title)) throw new Error(`sliceChanges.modified[${i}].title is required`);
+    if (s.depends !== undefined) {
+      if (!Array.isArray(s.depends) || s.depends.some((item: unknown) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+        throw new Error(`sliceChanges.modified[${i}].depends must be an array of valid slice IDs (e.g. "S01")`);
+      }
+    }
   }
 
   // Validate each added slice
@@ -89,6 +96,11 @@ function validateParams(params: ReassessRoadmapParams): ReassessRoadmapParams {
     if (!s || typeof s !== "object") throw new Error(`sliceChanges.added[${i}] must be an object`);
     if (!isNonEmptyString(s.sliceId)) throw new Error(`sliceChanges.added[${i}].sliceId is required`);
     if (!isNonEmptyString(s.title)) throw new Error(`sliceChanges.added[${i}].title is required`);
+    if (s.depends !== undefined) {
+      if (!Array.isArray(s.depends) || s.depends.some((item: unknown) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+        throw new Error(`sliceChanges.added[${i}].depends must be an array of valid slice IDs (e.g. "S01")`);
+      }
+    }
   }
 
   return params;
@@ -166,6 +178,37 @@ export async function handleReassessRoadmap(
         }
       }
 
+      // Cross-milestone depends validation — effective slice ID set after this reassessment
+      const removedIds = new Set<string>(params.sliceChanges.removed);
+      const effectiveSliceIds = new Set<string>(
+        existingSlices.map(s => s.id).filter(id => !removedIds.has(id)),
+      );
+      for (const added of params.sliceChanges.added) {
+        effectiveSliceIds.add(added.sliceId);
+      }
+      for (let i = 0; i < params.sliceChanges.modified.length; i++) {
+        const mod = params.sliceChanges.modified[i]!;
+        if (mod.depends !== undefined) {
+          for (const dep of mod.depends) {
+            if (!effectiveSliceIds.has(dep)) {
+              guardError = `sliceChanges.modified[${i}].depends references unknown slice "${dep}" — check that it is defined in this milestone`;
+              return;
+            }
+          }
+        }
+      }
+      for (let i = 0; i < params.sliceChanges.added.length; i++) {
+        const added = params.sliceChanges.added[i]!;
+        if (added.depends !== undefined) {
+          for (const dep of added.depends) {
+            if (!effectiveSliceIds.has(dep)) {
+              guardError = `sliceChanges.added[${i}].depends references unknown slice "${dep}" — check that it is defined in this milestone`;
+              return;
+            }
+          }
+        }
+      }
+
       // Record assessment
       insertAssessment({
         path: assessmentRelPath,