@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

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

@@ -8,9 +8,8 @@ import {
   type ExecSandboxRequest,
   type ExecSandboxResult,
 } from "../exec-sandbox.js";
-import { realpathSync } from "node:fs";
-import path from "node:path";
 import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
+import { bashReferencesProjectRootOutsideWorktree } from "../worktree-shell-guard.js";
 import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecToolParams {
@@ -32,6 +31,7 @@ export interface ExecToolDeps {
   env?: NodeJS.ProcessEnv;
   now?: () => Date;
   generateId?: () => string;
+  signal?: AbortSignal;
 }
 
 export type UatExecIntent =
@@ -75,7 +75,7 @@ const UAT_EXEC_INTENT_ALIASES: Record<string, UatExecIntent> = {
 export function buildExecOptions(
   baseDir: string,
   cfg: ContextModeConfig | undefined,
-  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId">,
+  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId" | "signal">,
 ): ExecSandboxOptions {
   const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg!.exec_env_allowlist! : EXEC_DEFAULTS.envAllowlist;
   const stdoutCap = clampNumber(
@@ -188,121 +188,6 @@ function isToolExecutionResult(value: unknown): value is ToolExecutionResult {
   return typeof value === "object" && value !== null && Array.isArray((value as { content?: unknown }).content);
 }
 
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function normalizeScanPath(value: string): string {
-  const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
-  return normalized.startsWith("/private/var/")
-    ? normalized.slice("/private".length)
-    : normalized;
-}
-
-function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
-  const normalizedBase = normalizeScanPath(baseDir);
-  const marker = "/.gsd/worktrees/";
-  const markerIndex = normalizedBase.indexOf(marker);
-  if (markerIndex <= 0) return null;
-  return {
-    originalRoot: normalizedBase.slice(0, markerIndex),
-    worktreeRoot: normalizedBase,
-  };
-}
-
-function pathInside(parent: string, target: string): boolean {
-  const parentWithSep = parent.endsWith("/") ? parent : `${parent}/`;
-  return target === parent || target.startsWith(parentWithSep);
-}
-
-function comparablePathVariants(value: string): string[] {
-  const variants = new Set<string>();
-  const normalized = normalizeScanPath(path.resolve(value));
-  variants.add(normalized);
-  try {
-    variants.add(normalizeScanPath(realpathSync(normalized)));
-  } catch {
-    // Nonexistent paths are still compared lexically.
-  }
-  if (normalized.startsWith("/private/var/")) {
-    variants.add(normalized.replace(/^\/private\/var\//, "/var/"));
-  } else if (normalized.startsWith("/var/")) {
-    variants.add(`/private${normalized}`);
-  }
-  return [...variants];
-}
-
-function pathInsideAny(parents: readonly string[], targets: readonly string[]): boolean {
-  return targets.some((target) => parents.some((parent) => pathInside(parent, target)));
-}
-
-function stripWrappingQuotes(value: string): string {
-  const trimmed = value.trim();
-  if (trimmed.length < 2) return trimmed;
-  const first = trimmed[0];
-  const last = trimmed[trimmed.length - 1];
-  if ((first === "'" || first === '"' || first === "`") && last === first) {
-    return trimmed.slice(1, -1).trim();
-  }
-  return trimmed;
-}
-
-function extractPathLikeValues(script: string): string[] {
-  const values: string[] = [];
-  const push = (candidate: string) => {
-    const cleaned = stripWrappingQuotes(candidate).trim();
-    if (!cleaned) return;
-    values.push(cleaned);
-  };
-  const pushQuotedLiterals = (source: string, depth = 0) => {
-    for (const match of source.matchAll(/(["'`])((?:\\.|(?!\1).)*)\1/g)) {
-      push(match[2]);
-      if (depth < 2 && /["'`]/.test(match[2])) {
-        pushQuotedLiterals(match[2], depth + 1);
-      }
-    }
-  };
-
-  for (const match of script.matchAll(/(?:^|[;\n\r]|\&\&|\|\|)\s*cd\s+([^\n\r;|&]+)/g)) {
-    push(match[1]);
-  }
-  for (const match of script.matchAll(/process\.chdir\(\s*([^\n\r;]+?)\s*\)/g)) {
-    push(match[1]);
-    pushQuotedLiterals(match[1]);
-  }
-  pushQuotedLiterals(script);
-  return values;
-}
-
-function resolvesToOriginalRootOutsideWorktree(script: string, baseDir: string): boolean {
-  const parsed = parseWorktreeBase(baseDir);
-  if (!parsed) return false;
-
-  const normalizedWorktree = normalizeScanPath(path.resolve(parsed.worktreeRoot));
-  const normalizedOriginalRoot = normalizeScanPath(path.resolve(parsed.originalRoot));
-  const worktreeRoots = comparablePathVariants(normalizedWorktree);
-  const originalRoots = comparablePathVariants(normalizedOriginalRoot);
-  for (const value of extractPathLikeValues(script)) {
-    const resolved = comparablePathVariants(path.resolve(normalizedWorktree, value));
-    if (pathInsideAny(originalRoots, resolved) && !pathInsideAny(worktreeRoots, resolved)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function scriptReferencesOriginalRootFromWorktree(script: string, baseDir: string): boolean {
-  const parsed = parseWorktreeBase(baseDir);
-  if (!parsed) return false;
-  const normalizedScript = script.replace(/\\/g, "/");
-  return comparablePathVariants(parsed.originalRoot).some((originalRoot) => {
-    const originalRootPattern = new RegExp(
-      `${escapeRegExp(originalRoot)}(?=$|[\\s'"\\\`;)&|<>]|/(?!\\.gsd/worktrees(?:/|$)))`,
-    );
-    return originalRootPattern.test(normalizedScript);
-  });
-}
-
 export async function executeGsdExec(
   params: ExecToolParams,
   deps: ExecToolDeps,
@@ -316,10 +201,7 @@ export async function executeGsdExec(
   if (Buffer.byteLength(script, "utf8") > 200_000) {
     return paramError("script exceeds the 200 KB length limit");
   }
-  if (
-    resolvesToOriginalRootOutsideWorktree(script, deps.baseDir)
-    || scriptReferencesOriginalRootFromWorktree(script, deps.baseDir)
-  ) {
+  if (bashReferencesProjectRootOutsideWorktree(script, deps.baseDir)) {
     return paramError(
       "script references the original project root while running inside a milestone worktree; use the active worktree path or relative paths",
     );
@@ -328,7 +210,7 @@ export async function executeGsdExec(
   const opts = buildExecOptions(
     deps.baseDir,
     deps.preferences?.context_mode,
-    { env: deps.env, now: deps.now, generateId: deps.generateId },
+    { env: deps.env, now: deps.now, generateId: deps.generateId, signal: deps.signal },
   );
   const run = deps.run ?? runExecSandbox;
 
@@ -427,6 +309,8 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       exit_code: result.exit_code,
       signal: result.signal,
       timed_out: result.timed_out,
+      aborted: result.aborted === true,
+      force_resolved: result.force_resolved,
       duration_ms: result.duration_ms,
       stdout_bytes: result.stdout_bytes,
       stderr_bytes: result.stderr_bytes,
@@ -436,11 +320,16 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       stderr_path: result.stderr_path,
       meta_path: result.meta_path,
     },
-    isError: result.timed_out || result.signal !== null || result.exit_code !== 0,
+    isError: result.aborted === true || result.timed_out || result.signal !== null || result.exit_code !== 0,
   };
 }
 
 function formatExit(result: ExecSandboxResult): string {
+  // force_resolved means a non-closing (D-state) child was force-resolved past its
+  // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+  if (result.aborted && result.force_resolved) return "aborted(force-killed)";
+  if (result.aborted) return "aborted";
+  if (result.force_resolved) return "timeout(force-killed)";
   if (result.timed_out) return "timeout";
   if (result.signal) return `signal:${result.signal}`;
   if (result.exit_code === null) return "null";

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/plan-slice.ts

@@ -21,13 +21,13 @@ import {
 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 { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
-import { checkFilePathConsistency, checkTaskOrdering } from "../pre-execution-checks.js";
+import { runTaskPathChecks } from "../pre-execution-checks.js";
 import type { TaskRow } from "../db-task-slice-rows.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { buildTaskFileName, gsdProjectionRoot } from "../paths.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets, type RepositoryRegistry } from "../repository-registry.js";
@@ -268,11 +268,16 @@ function validateTaskPathsBeforePersist(
   const additionalRoots = allowedRoots
     .map((root) => resolve(root))
     .filter((root) => root !== baseRoot);
-  const context = additionalRoots.length > 0 ? { additionalRoots } : undefined;
-  const checks = [
-    ...checkFilePathConsistency(taskRows, basePath, context),
-    ...checkTaskOrdering(taskRows, basePath, context),
-  ];
+  const resolvedCanonicalRoot = resolve(resolveWorktreeProjectRoot(basePath));
+  const canonicalProjectRoot = resolvedCanonicalRoot !== baseRoot ? resolvedCanonicalRoot : undefined;
+  const hasContext = additionalRoots.length > 0 || canonicalProjectRoot !== undefined;
+  const context = hasContext
+    ? {
+        ...(additionalRoots.length > 0 ? { additionalRoots } : {}),
+        ...(canonicalProjectRoot !== undefined ? { canonicalProjectRoot } : {}),
+      }
+    : undefined;
+  const checks = runTaskPathChecks(taskRows, basePath, context);
   const blocking = checks.filter((check) => !check.passed && check.blocking);
 
   if (blocking.length === 0) return null;
@@ -460,9 +465,8 @@ export async function handlePlanSlice(
     invalidateStateCache();
     clearParseCache();
 
-    // ── Post-mutation hook: projections, manifest, event log ─────────────
+    // ── Post-mutation hook: manifest, event log ─────────────────────────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-slice",

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

@@ -3,8 +3,9 @@ import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderTaskPlanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { renderTaskPlanFromDb, renderPlanFromDb } from "../markdown-renderer.js";
+import { resolveSliceFile, resolveTasksDir } from "../paths.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -137,12 +138,27 @@ export async function handlePlanTask(
 
   try {
     const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
+
+    // Flat-phase: tasks live as checkboxes in the slice plan's <tasks> block,
+    // not as standalone TID-PLAN.md files. Re-render the slice plan so the
+    // new/updated task appears in the plan file that gsd-core reads.
+    // Guard: resolveTasksDir is null in flat-phase (no tasks/ subdir exists);
+    //        only sync if a slice plan already exists (guards pre-plan-slice calls).
+    try {
+      const tDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+      if (!tDir && resolveSliceFile(basePath, params.milestoneId, params.sliceId, "PLAN")) {
+        await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+      }
+    } catch (syncErr) {
+      logWarning("tool", `plan-task: slice-plan sync failed: ${(syncErr as Error).message}`);
+    }
+
     invalidateStateCache();
     clearParseCache();
 
     // ── Post-mutation hook: projections, manifest, event log ─────────────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-task",

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

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { existsSync, unlinkSync } from "node:fs";
+import { relSliceFile, relMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -16,7 +17,7 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -75,12 +76,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 +97,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;
@@ -107,12 +120,9 @@ export async function handleReassessRoadmap(
   }
 
   // ── Compute assessment artifact path ──────────────────────────────
-  // Assessment lives in the completed slice's directory
-  const assessmentRelPath = join(
-    ".gsd", "milestones", params.milestoneId,
-    "slices", params.completedSliceId,
-    `${params.completedSliceId}-ASSESSMENT.md`,
-  );
+  // Assessment lives in the completed slice's directory.
+  // Use relSliceFile so the path is layout-aware (flat-phase or legacy).
+  const assessmentRelPath = relSliceFile(basePath, params.milestoneId, params.completedSliceId, "ASSESSMENT");
 
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
@@ -166,6 +176,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,
@@ -233,6 +274,9 @@ export async function handleReassessRoadmap(
   // ── Render artifacts ──────────────────────────────────────────────
   try {
     const roadmapResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+    if ("skipped" in roadmapResult) {
+      return { error: `roadmap render skipped: milestone ${params.milestoneId} has no planned slices` };
+    }
     const assessmentResult = await renderAssessmentFromDb(basePath, params.milestoneId, params.completedSliceId, {
       verdict: params.verdict,
       assessment: params.assessment,
@@ -246,10 +290,8 @@ export async function handleReassessRoadmap(
       params.sliceChanges.removed.length > 0;
 
     if (hasStructuralChanges) {
-      const validationFile = join(
-        basePath, ".gsd", "milestones", params.milestoneId,
-        `${params.milestoneId}-VALIDATION.md`,
-      );
+      // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md; legacy → milestones/MID/MID-VALIDATION.md
+      const validationFile = join(basePath, relMilestoneFile(basePath, params.milestoneId, "VALIDATION"));
       try {
         if (existsSync(validationFile)) unlinkSync(validationFile);
       } catch (e) {
@@ -263,7 +305,7 @@ export async function handleReassessRoadmap(
 
     // ── Post-mutation hook: projections, manifest, event log ─────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "reassess-roadmap",