@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.97ef11e3

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

@@ -1,6 +1,6 @@
 import { existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { relSliceFile, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile } from "../paths.js";
+import { join, relative } from "node:path";
+import { gsdProjectionRoot, gsdRoot, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -53,6 +53,14 @@ export interface ReassessRoadmapResult {
   roadmapPath: string;
 }
 
+function assessmentDbPathForRenderedFile(basePath: string, absPath: string): string {
+  const projectionRoot = gsdProjectionRoot(basePath);
+  const projectionRel = relative(projectionRoot, absPath);
+  const root = projectionRel && !projectionRel.startsWith("..") && !projectionRel.startsWith("/")
+    ? projectionRoot
+    : gsdRoot(basePath);
+  return `.gsd/${relative(root, absPath).replace(/\\/g, "/")}`;
+}
 
 function validateParams(params: ReassessRoadmapParams): ReassessRoadmapParams {
   if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required");
@@ -119,11 +127,6 @@ export async function handleReassessRoadmap(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
-  // ── Compute assessment artifact path ──────────────────────────────
-  // 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
   // change between the read and the write (#2723).
@@ -207,16 +210,6 @@ export async function handleReassessRoadmap(
         }
       }
 
-      // Record assessment
-      insertAssessment({
-        path: assessmentRelPath,
-        milestoneId: params.milestoneId,
-        sliceId: params.completedSliceId,
-        status: params.verdict,
-        scope: "roadmap",
-        fullContent: params.assessment,
-      });
-
       // Apply slice modifications
       for (const mod of params.sliceChanges.modified) {
         updateSliceFields(params.milestoneId, mod.sliceId, {
@@ -282,6 +275,14 @@ export async function handleReassessRoadmap(
       assessment: params.assessment,
       completedSliceId: params.completedSliceId,
     });
+    insertAssessment({
+      path: assessmentDbPathForRenderedFile(basePath, assessmentResult.assessmentPath),
+      milestoneId: params.milestoneId,
+      sliceId: params.completedSliceId,
+      status: params.verdict,
+      scope: "roadmap",
+      fullContent: params.assessment,
+    });
 
     // ── Remove stale VALIDATION file from disk (#2957) ────────────
     const hasStructuralChanges =

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

@@ -22,7 +22,15 @@ import { logWarning } from "../workflow-logger.js";
 import { debugLog } from "../debug-logger.js";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { resolveMilestonePath, resolveSlicePath, resolveTasksDir, clearPathCache } from "../paths.js";
+import {
+  buildFlatTaskFileName,
+  buildTaskFileName,
+  legacyMilestonesDir,
+  resolveMilestonePath,
+  resolveSlicePath,
+  resolveTasksDir,
+  clearPathCache,
+} from "../paths.js";
 
 export interface ReopenMilestoneParams {
   milestoneId: string;
@@ -69,6 +77,10 @@ export async function handleReopenMilestone(
   // auto-corrects entities back to "complete", making reopen a no-op (#3161).
   try {
     const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacy = !!milestoneDir && (
+      milestoneDir.startsWith(legacyBase + "/") || milestoneDir.startsWith(legacyBase + "\\")
+    );
     if (milestoneDir) {
       const milestoneSummary = join(milestoneDir, `${params.milestoneId}-SUMMARY.md`);
       if (existsSync(milestoneSummary)) unlinkSync(milestoneSummary);
@@ -85,10 +97,17 @@ export async function handleReopenMilestone(
       }
 
       const tasksDir = resolveTasksDir(basePath, params.milestoneId, slice.id);
-      if (tasksDir) {
-        const tasks = getSliceTasks(params.milestoneId, slice.id);
-        for (const task of tasks) {
-          const taskSummary = join(tasksDir, `${task.id}-SUMMARY.md`);
+      const tasks = getSliceTasks(params.milestoneId, slice.id);
+      for (const task of tasks) {
+        const taskSummaries = isLegacy
+          ? (tasksDir ? [join(tasksDir, buildTaskFileName(task.id, "SUMMARY"))] : [])
+          : milestoneDir
+            ? [
+              join(milestoneDir, buildFlatTaskFileName(slice.id, task.id, "SUMMARY")),
+              join(milestoneDir, buildTaskFileName(task.id, "SUMMARY")),
+            ]
+            : [];
+        for (const taskSummary of taskSummaries) {
           if (existsSync(taskSummary)) unlinkSync(taskSummary);
         }
       }

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

@@ -27,7 +27,15 @@ import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
+import {
+  buildFlatTaskFileName,
+  buildTaskFileName,
+  legacyMilestonesDir,
+  resolveMilestonePath,
+  resolveTasksDir,
+  resolveSlicePath,
+  clearPathCache,
+} from "../paths.js";
 
 export interface ReopenSliceParams {
   milestoneId: string;
@@ -80,11 +88,23 @@ export async function handleReopenSlice(
   // Without this, the DB-filesystem reconciler sees SUMMARY.md files and
   // auto-corrects tasks back to "complete", making reopen a no-op (#3161).
   try {
+    const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacy = !!milestoneDir && (
+      milestoneDir.startsWith(legacyBase + "/") || milestoneDir.startsWith(legacyBase + "\\")
+    );
     const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-    if (tasksDir) {
-      const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-      for (const task of tasks) {
-        const summaryPath = join(tasksDir, `${task.id}-SUMMARY.md`);
+    const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+    for (const task of tasks) {
+      const summaryPaths = isLegacy
+        ? (tasksDir ? [join(tasksDir, buildTaskFileName(task.id, "SUMMARY"))] : [])
+        : milestoneDir
+          ? [
+            join(milestoneDir, buildFlatTaskFileName(params.sliceId, task.id, "SUMMARY")),
+            join(milestoneDir, buildTaskFileName(task.id, "SUMMARY")),
+          ]
+          : [];
+      for (const summaryPath of summaryPaths) {
         if (existsSync(summaryPath)) unlinkSync(summaryPath);
       }
     }

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

@@ -25,8 +25,16 @@ import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { writeReopenReason } from "../reopen-reason.js";
 import { existsSync, unlinkSync } from "node:fs";
-import { join, basename, dirname } from "node:path";
-import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
+import { join } from "node:path";
+import {
+  buildFlatTaskFileName,
+  buildTaskFileName,
+  legacyMilestonesDir,
+  resolveMilestonePath,
+  resolveTasksDir,
+  resolveSlicePath,
+  clearPathCache,
+} from "../paths.js";
 
 export interface ReopenTaskParams {
   milestoneId: string;
@@ -113,13 +121,19 @@ export async function handleReopenTask(
   // summary cleanup into tasks/ (#1208).
   try {
     const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
-    if (slicePath) {
-      const isLegacySlice = basename(dirname(slicePath)) === "slices";
-      const summaryDir = isLegacySlice
-        ? (resolveTasksDir(basePath, params.milestoneId, params.sliceId) ?? slicePath)
-        : slicePath;
-      const summaryPath = join(summaryDir, `${params.taskId}-SUMMARY.md`);
-      if (existsSync(summaryPath)) unlinkSync(summaryPath);
+    const milestonePath = resolveMilestonePath(basePath, params.milestoneId);
+    if (milestonePath) {
+      const legacyBase = legacyMilestonesDir(basePath);
+      const isLegacy = milestonePath.startsWith(legacyBase + "/") || milestonePath.startsWith(legacyBase + "\\");
+      const summaryPaths = isLegacy
+        ? [join(resolveTasksDir(basePath, params.milestoneId, params.sliceId) ?? slicePath ?? join(milestonePath, "slices", params.sliceId, "tasks"), buildTaskFileName(params.taskId, "SUMMARY"))]
+        : [
+          join(milestonePath, buildFlatTaskFileName(params.sliceId, params.taskId, "SUMMARY")),
+          join(milestonePath, buildTaskFileName(params.taskId, "SUMMARY")),
+        ];
+      for (const summaryPath of summaryPaths) {
+        if (existsSync(summaryPath)) unlinkSync(summaryPath);
+      }
     }
   } catch (cleanupErr) {
     logWarning("tool", `reopen-task artifact cleanup warning: ${(cleanupErr as Error).message}`);

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

@@ -0,0 +1,160 @@
+import { clearParseCache } from "../files.js";
+import {
+  getSlice,
+  getTask,
+  insertReplanHistory,
+  transaction,
+  upsertTaskPlanning,
+} from "../gsd-db.js";
+import { invalidateStateCache } from "../state.js";
+import { isClosedStatus } from "../status-guards.js";
+import { isNonEmptyString, validateStringArray } from "../validation.js";
+import { renderPlanFromDb, renderTaskPlanFromDb } from "../markdown-renderer.js";
+import { resolveMilestonePath, resolveSlicePath } 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";
+
+export interface ReplanTaskParams {
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  title: string;
+  description: string;
+  estimate: string;
+  files: string[];
+  verify: string;
+  inputs: string[];
+  expectedOutput: string[];
+  reworkBriefRef?: string;
+  fullPlanMd?: string;
+  actorName?: string;
+  triggerReason?: string;
+}
+
+export interface ReplanTaskResult {
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  taskPlanPath: string;
+}
+
+function validateParams(params: ReplanTaskParams): ReplanTaskParams {
+  if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required");
+  if (!isNonEmptyString(params?.sliceId)) throw new Error("sliceId is required");
+  if (!isNonEmptyString(params?.taskId)) throw new Error("taskId is required");
+  if (!isNonEmptyString(params?.title)) throw new Error("title is required");
+  if (!isNonEmptyString(params?.description)) throw new Error("description is required");
+  if (!isNonEmptyString(params?.estimate)) throw new Error("estimate is required");
+  if (!isNonEmptyString(params?.verify)) throw new Error("verify is required");
+  return {
+    ...params,
+    files: validateStringArray(params.files, "files"),
+    inputs: validateStringArray(params.inputs, "inputs"),
+    expectedOutput: validateStringArray(params.expectedOutput, "expectedOutput"),
+  };
+}
+
+function replanSummary(params: ReplanTaskParams): string {
+  const ref = params.reworkBriefRef?.trim();
+  return ref
+    ? `Task ${params.taskId} replanned from rework brief ${ref}`
+    : `Task ${params.taskId} replanned`;
+}
+
+export async function handleReplanTask(
+  rawParams: ReplanTaskParams,
+  basePath: string,
+): Promise<ReplanTaskResult | { error: string }> {
+  let params: ReplanTaskParams;
+  try {
+    params = validateParams(rawParams);
+  } catch (err) {
+    return { error: `validation failed: ${(err as Error).message}` };
+  }
+
+  let guardError: string | null = null;
+  try {
+    transaction(() => {
+      const parentSlice = getSlice(params.milestoneId, params.sliceId);
+      if (!parentSlice) {
+        guardError = `missing parent slice: ${params.milestoneId}/${params.sliceId}`;
+        return;
+      }
+      if (isClosedStatus(parentSlice.status)) {
+        guardError = `cannot replan a task in a closed slice: ${params.sliceId} (status: ${parentSlice.status})`;
+        return;
+      }
+
+      const task = getTask(params.milestoneId, params.sliceId, params.taskId);
+      if (!task) {
+        guardError = `task not found: ${params.milestoneId}/${params.sliceId}/${params.taskId}`;
+        return;
+      }
+      if (isClosedStatus(task.status)) {
+        guardError = `cannot replan completed task ${params.taskId} — use gsd_task_reopen first`;
+        return;
+      }
+
+      upsertTaskPlanning(params.milestoneId, params.sliceId, params.taskId, {
+        title: params.title,
+        description: params.description,
+        estimate: params.estimate,
+        files: params.files,
+        verify: params.verify,
+        inputs: params.inputs,
+        expectedOutput: params.expectedOutput,
+        fullPlanMd: params.fullPlanMd,
+      });
+      insertReplanHistory({
+        milestoneId: params.milestoneId,
+        sliceId: params.sliceId,
+        taskId: params.taskId,
+        summary: replanSummary(params),
+        previousArtifactPath: params.reworkBriefRef ?? null,
+      });
+    });
+  } catch (err) {
+    return { error: `db write failed: ${(err as Error).message}` };
+  }
+
+  if (guardError) return { error: guardError };
+
+  try {
+    const milestonePath = resolveMilestonePath(basePath, params.milestoneId);
+    const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+    const isLegacySliceLayout = Boolean(milestonePath && slicePath && slicePath !== milestonePath);
+    const renderResult = isLegacySliceLayout
+      ? await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId)
+      : await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+    const taskPlanPath = "taskPlanPath" in renderResult ? renderResult.taskPlanPath : renderResult.planPath;
+
+    invalidateStateCache();
+    clearParseCache();
+
+    try {
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
+      writeManifest(basePath);
+      appendEvent(basePath, {
+        cmd: "replan-task",
+        params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId },
+        ts: new Date().toISOString(),
+        actor: "agent",
+        actor_name: params.actorName,
+        trigger_reason: params.triggerReason,
+      });
+    } catch (hookErr) {
+      logWarning("tool", `replan-task post-mutation hook warning: ${(hookErr as Error).message}`);
+    }
+
+    return {
+      milestoneId: params.milestoneId,
+      sliceId: params.sliceId,
+      taskId: params.taskId,
+      taskPlanPath,
+    };
+  } catch (err) {
+    return { error: `render failed: ${(err as Error).message}` };
+  }
+}

package/src/resources/extensions/gsd/tools/rework-brief.ts

@@ -0,0 +1,91 @@
+import { saveReworkBrief, type ReworkBriefFindingInput } from "../gsd-db.js";
+import { isNonEmptyString, validateStringArray } from "../validation.js";
+
+export interface ReworkBriefSaveParams {
+  briefId?: string;
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  findings: ReworkBriefFindingInput[];
+}
+
+export interface ReworkBriefSaveResult {
+  briefId: string;
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  findingCount: number;
+}
+
+function validateFinding(finding: ReworkBriefFindingInput, index: number): ReworkBriefFindingInput {
+  if (!isNonEmptyString(finding?.findingId)) throw new Error(`findings[${index}].findingId is required`);
+  if (finding.severity !== "blocking" && finding.severity !== "advisory") {
+    throw new Error(`findings[${index}].severity must be blocking or advisory`);
+  }
+  if (!isNonEmptyString(finding.description)) throw new Error(`findings[${index}].description is required`);
+  if (!isNonEmptyString(finding.requiredFix)) throw new Error(`findings[${index}].requiredFix is required`);
+
+  const status = finding.status ?? "pending";
+  if (status !== "pending" && status !== "resolved" && status !== "deferred-with-override") {
+    throw new Error(`findings[${index}].status must be pending, resolved, or deferred-with-override`);
+  }
+
+  // A blocking finding is only enforced by gsd_task_complete while it is
+  // `pending` (getUnresolvedBlockingReworkFindingsForTask returns pending rows
+  // only). Persisting a blocking finding as resolved/deferred-with-override
+  // at save time therefore bypasses the completion gate entirely, so require
+  // the same justification a reworkResolution would (evidence for `resolved`,
+  // evidence + decisionRef for `deferred-with-override`). Advisory findings do
+  // not gate completion, so their status is left as-is.
+  if (finding.severity === "blocking" && status !== "pending") {
+    if (!isNonEmptyString(finding.evidence)) {
+      throw new Error(`findings[${index}].evidence is required when a blocking finding is saved as ${status}`);
+    }
+    if (status === "deferred-with-override" && !isNonEmptyString(finding.decisionRef)) {
+      throw new Error(`findings[${index}].decisionRef is required when a blocking finding is saved as deferred-with-override`);
+    }
+  }
+
+  return {
+    ...finding,
+    verificationCommands: validateStringArray(finding.verificationCommands, `findings[${index}].verificationCommands`),
+    status,
+  };
+}
+
+function validateParams(params: ReworkBriefSaveParams): ReworkBriefSaveParams {
+  if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required");
+  if (!isNonEmptyString(params?.sliceId)) throw new Error("sliceId is required");
+  if (!isNonEmptyString(params?.taskId)) throw new Error("taskId is required");
+  if (!Array.isArray(params.findings) || params.findings.length === 0) {
+    throw new Error("findings must be a non-empty array");
+  }
+  return {
+    ...params,
+    findings: params.findings.map(validateFinding),
+  };
+}
+
+export async function handleReworkBriefSave(
+  rawParams: ReworkBriefSaveParams,
+): Promise<ReworkBriefSaveResult | { error: string }> {
+  let params: ReworkBriefSaveParams;
+  try {
+    params = validateParams(rawParams);
+  } catch (err) {
+    return { error: `validation failed: ${(err as Error).message}` };
+  }
+
+  try {
+    const { briefId } = saveReworkBrief(params);
+    return {
+      briefId,
+      milestoneId: params.milestoneId,
+      sliceId: params.sliceId,
+      taskId: params.taskId,
+      findingCount: params.findings.length,
+    };
+  } catch (err) {
+    return { error: `db write failed: ${(err as Error).message}` };
+  }
+}

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

@@ -37,6 +37,10 @@ import type { PlanSliceParams } from "./plan-slice.js";
 import { handlePlanSlice } from "./plan-slice.js";
 import type { ReplanSliceParams } from "./replan-slice.js";
 import { handleReplanSlice } from "./replan-slice.js";
+import type { ReplanTaskParams } from "./replan-task.js";
+import { handleReplanTask } from "./replan-task.js";
+import type { ReworkBriefSaveParams } from "./rework-brief.js";
+import { handleReworkBriefSave } from "./rework-brief.js";
 import type { ReopenMilestoneParams } from "./reopen-milestone.js";
 import { handleReopenMilestone } from "./reopen-milestone.js";
 import type { ReopenSliceParams } from "./reopen-slice.js";
@@ -696,6 +700,8 @@ export type SliceCompleteExecutorParams = CompleteSliceParams;
 export type PlanMilestoneExecutorParams = PlanMilestoneParams;
 export type PlanSliceExecutorParams = PlanSliceParams;
 export type ReplanSliceExecutorParams = ReplanSliceParams;
+export type ReplanTaskExecutorParams = ReplanTaskParams;
+export type ReworkBriefSaveExecutorParams = ReworkBriefSaveParams;
 export type ReopenTaskExecutorParams = ReopenTaskParams;
 export type ReopenSliceExecutorParams = ReopenSliceParams;
 export type ReopenMilestoneExecutorParams = ReopenMilestoneParams;
@@ -1490,6 +1496,92 @@ export async function executePlanSlice(
   }
 }
 
+
+export async function executeReplanTask(
+  params: ReplanTaskExecutorParams,
+  basePath: string = process.cwd(),
+): Promise<ToolExecutionResult> {
+  const dbAvailable = await ensureDbOpen(basePath);
+  if (!dbAvailable) {
+    return {
+      content: [{ type: "text", text: "Error: GSD database is not available. Cannot replan task." }],
+      details: { operation: "replan_task", error: "db_unavailable" },
+      isError: true,
+    };
+  }
+  try {
+    const result = await handleReplanTask(params, basePath);
+    if ("error" in result) {
+      return {
+        content: [{ type: "text", text: `Error replanning task: ${result.error}` }],
+        details: { operation: "replan_task", error: result.error },
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: `Replanned task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
+      details: {
+        operation: "replan_task",
+        milestoneId: result.milestoneId,
+        sliceId: result.sliceId,
+        taskId: result.taskId,
+        taskPlanPath: result.taskPlanPath,
+      },
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError("tool", `replan_task tool failed: ${msg}`, { tool: "gsd_replan_task", error: String(err) });
+    return {
+      content: [{ type: "text", text: `Error replanning task: ${msg}` }],
+      details: { operation: "replan_task", error: msg },
+      isError: true,
+    };
+  }
+}
+
+export async function executeReworkBriefSave(
+  params: ReworkBriefSaveExecutorParams,
+  basePath: string = process.cwd(),
+): Promise<ToolExecutionResult> {
+  const dbAvailable = await ensureDbOpen(basePath);
+  if (!dbAvailable) {
+    return {
+      content: [{ type: "text", text: "Error: GSD database is not available. Cannot save rework brief." }],
+      details: { operation: "rework_brief_save", error: "db_unavailable" },
+      isError: true,
+    };
+  }
+  try {
+    const result = await handleReworkBriefSave(params);
+    if ("error" in result) {
+      return {
+        content: [{ type: "text", text: `Error saving rework brief: ${result.error}` }],
+        details: { operation: "rework_brief_save", error: result.error },
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: `Saved rework brief ${result.briefId} with ${result.findingCount} finding(s)` }],
+      details: {
+        operation: "rework_brief_save",
+        briefId: result.briefId,
+        milestoneId: result.milestoneId,
+        sliceId: result.sliceId,
+        taskId: result.taskId,
+        findingCount: result.findingCount,
+      },
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError("tool", `rework_brief_save tool failed: ${msg}`, { tool: "gsd_rework_brief_save", error: String(err) });
+    return {
+      content: [{ type: "text", text: `Error saving rework brief: ${msg}` }],
+      details: { operation: "rework_brief_save", error: msg },
+      isError: true,
+    };
+  }
+}
+
 export async function executeReplanSlice(
   params: ReplanSliceExecutorParams,
   basePath: string = process.cwd(),

package/src/resources/extensions/gsd/types.ts

@@ -695,6 +695,17 @@ export interface CompleteTaskParams {
     verdict: string;
     durationMs: number;
   }>;
+  /**
+   * Resolution evidence for structured rework findings linked to this task.
+   * All blocking findings must be resolved before completion is accepted.
+   * @optional
+   */
+  reworkResolution?: Array<{
+    findingId: string;
+    status: "resolved" | "deferred-with-override";
+    evidence: string;
+    decisionRef?: string;
+  }>;
   /**
    * Q5 failure-modes section content (what breaks when dependencies fail).
    * Populated → `pass`; omitted/empty → `omitted`.

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -46,6 +46,7 @@ import {
   type ToolsPolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
+import { resolveEffectivePlanningToolsPolicy } from "./planning-subagent-policy.js";
 import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 import type { UnitPromptContextContract } from "./tool-contract.js";
 
@@ -207,6 +208,7 @@ export function composeContextModeInstructions(
 
 export interface ComposeToolSurfaceInstructionOptions {
   readonly renderMode: ContextModeRenderMode;
+  readonly basePath?: string;
 }
 
 const TOOL_SURFACE_GUIDANCE_BY_UNIT: Record<string, string> = {
@@ -226,16 +228,39 @@ const TOOL_SURFACE_GUIDANCE_BY_UNIT: Record<string, string> = {
     "Persist completion only through `gsd_complete_milestone` after verification passes. Do not query `.gsd/gsd.db` directly. Do not write `.gsd/PROJECT.md` or `.gsd/REQUIREMENTS.md` by hand — use `gsd_summary_save` and `gsd_requirement_update`.",
   "replan-slice":
     "Persist replans through `gsd_replan_slice` only. Do not edit `PLAN.md` or task plans directly.",
-  "plan-slice":
-    "Persist planning through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner** for reconnaissance — not implementation agents. Do not edit user source files outside `.gsd/**`.",
-  "refine-slice":
-    "Persist refinements through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner**. Do not edit user source files outside `.gsd/**`.",
-  "plan-milestone":
-    "Persist milestone planning through `gsd_plan_milestone` / `gsd_plan_slice`. Do not edit user source files outside `.gsd/**`.",
   "research-slice":
     "Dispatch subagents only to **scout** or **planner** for reconnaissance. Do not edit user source files outside `.gsd/**`.",
 };
 
+function formatAllowedAgents(agents: readonly string[]): string {
+  return agents.map((agent) => `**${agent}**`).join(", ");
+}
+
+function guidanceForUnitToolsPolicy(unitType: string, policy: ToolsPolicy): string | undefined {
+  if (unitType === "plan-slice") {
+    const dispatch = policy.mode === "planning-dispatch"
+      ? ` Dispatch subagents only to ${formatAllowedAgents(policy.allowedSubagents)} for reconnaissance — not implementation agents.`
+      : " Do not dispatch subagents.";
+    return `Persist planning through \`gsd_plan_slice\` only.${dispatch} Do not edit user source files outside \`.gsd/**\`.`;
+  }
+
+  if (unitType === "refine-slice") {
+    const dispatch = policy.mode === "planning-dispatch"
+      ? ` Dispatch subagents only to ${formatAllowedAgents(policy.allowedSubagents)}.`
+      : " Do not dispatch subagents.";
+    return `Persist refinements through \`gsd_plan_slice\` only.${dispatch} Do not edit user source files outside \`.gsd/**\`.`;
+  }
+
+  if (unitType === "plan-milestone") {
+    const dispatch = policy.mode === "planning-dispatch"
+      ? ` Dispatch subagents only to ${formatAllowedAgents(policy.allowedSubagents)}.`
+      : "";
+    return `Persist milestone planning through \`gsd_plan_milestone\` / \`gsd_plan_slice\`.${dispatch} Do not edit user source files outside \`.gsd/**\`.`;
+  }
+
+  return undefined;
+}
+
 function guidanceForToolsPolicy(policy: ToolsPolicy): string | null {
   switch (policy.mode) {
     case "planning":
@@ -280,8 +305,9 @@ export function composeToolSurfaceInstructions(
   const manifest = resolveManifest(unitType);
   if (!manifest) return "";
 
-  const unitGuidance = TOOL_SURFACE_GUIDANCE_BY_UNIT[unitType];
-  const policyGuidance = unitGuidance ? null : guidanceForToolsPolicy(manifest.tools);
+  const effectiveTools = resolveEffectivePlanningToolsPolicy(unitType, manifest.tools, opts.basePath) ?? manifest.tools;
+  const unitGuidance = guidanceForUnitToolsPolicy(unitType, effectiveTools) ?? TOOL_SURFACE_GUIDANCE_BY_UNIT[unitType];
+  const policyGuidance = unitGuidance ? null : guidanceForToolsPolicy(effectiveTools);
   const forbiddenLine = formatForbiddenWorkflowToolsLine(unitType, unitGuidance);
   const parts = [unitGuidance, policyGuidance, forbiddenLine].filter(
     (part): part is string => typeof part === "string" && part.length > 0,