@opengsd/gsd-pi 1.8.1 → 1.9.0

package/src/resources/extensions/gsd/tests/write-gate-seam.test.ts

@@ -26,6 +26,7 @@ import { tmpdir } from "node:os";
 
 import { registerHooks } from "../bootstrap/register-hooks.ts";
 import {
+  _setWriteGateInterleaveHookForTest,
   childWriteGateAdapter,
   clearDiscussionFlowState,
   getPendingGate,
@@ -36,6 +37,9 @@ import {
   setPendingGate,
   type WriteGateSnapshot,
 } from "../bootstrap/write-gate.ts";
+import { acquireSyncLock, releaseSyncLock } from "../sync-lock.ts";
+
+const WRITE_GATE_LOCK_NAME = "write-gate.lock";
 
 function makeTempDir(prefix: string): string {
   const dir = join(
@@ -356,3 +360,51 @@ test("seam: mutateWriteGateState reset path drops stale pendingGateId on a corru
   assert.equal(persisted.pendingGateId, null, "stale pending id must not be persisted after a corrupt-snapshot reconcile");
   assert.deepEqual(persisted.verifiedDepthMilestones, ["M099"]);
 });
+
+// ── (f) cross-process lock closes the read-merge-write lost-update window ────
+
+test("seam: read-merge-write holds the write-gate lock across the whole critical section", (t) => {
+  const dir = makeTempDir("lock-held");
+  t.after(() => {
+    _setWriteGateInterleaveHookForTest(null);
+    cleanup(dir);
+  });
+
+  // Fire inside the host's critical section, standing in for the OTHER process
+  // attempting to enter its own read-merge-write. The lock must lock it out.
+  let peerAcquiredMidSection: boolean | null = null;
+  _setWriteGateInterleaveHookForTest((lockRoot) => {
+    const res = acquireSyncLock(lockRoot, 0, WRITE_GATE_LOCK_NAME);
+    peerAcquiredMidSection = res.acquired;
+    if (res.acquired) releaseSyncLock(lockRoot, WRITE_GATE_LOCK_NAME);
+  });
+
+  markDepthVerified("M001", dir);
+
+  assert.equal(
+    peerAcquiredMidSection,
+    false,
+    "a concurrent process must be locked out of the read-merge-write section — this is what prevents the lost-update",
+  );
+  // The lock is released after the mutation, and the mutation still took effect.
+  assert.ok(loadWriteGateSnapshot(dir).verifiedDepthMilestones.includes("M001"));
+  assert.equal(acquireSyncLock(dir, 0, WRITE_GATE_LOCK_NAME).acquired, true, "lock released after mutation");
+  releaseSyncLock(dir, WRITE_GATE_LOCK_NAME);
+});
+
+test("seam: gate mutation fails OPEN when a live peer holds the lock (never blocks/refuses)", (t) => {
+  const dir = makeTempDir("lock-fail-open");
+  t.after(() => cleanup(dir));
+
+  // A live peer holds the lock (its own PID → never stolen as stale).
+  assert.equal(acquireSyncLock(dir, 0, WRITE_GATE_LOCK_NAME).acquired, true);
+  try {
+    // Host arms a gate while contended: fail-open means it proceeds anyway.
+    const armed = setPendingGate(GATE, dir);
+    assert.equal(armed, true, "arm must succeed (fail-open) even though the lock is held");
+    assert.equal(getPendingGate(dir), GATE);
+    assert.equal(readDiskRaw(dir).pendingGateId, GATE, "fail-open still persists the mutation");
+  } finally {
+    releaseSyncLock(dir, WRITE_GATE_LOCK_NAME);
+  }
+});

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

@@ -29,6 +29,10 @@ import {
   deleteVerificationEvidence,
   saveGateResult,
   getPendingGatesForTurn,
+  getUnresolvedBlockingReworkFindingsForTask,
+  getBlockingReworkFindingsForTask,
+  applyReworkResolutions,
+  type ReworkFindingStatus,
 } from "../gsd-db.js";
 import { getWorkflowDatabasePath, ensureWorkflowDbAtPath } from "../db-workspace.js";
 import { getGatesForTurn } from "../gate-registry.js";
@@ -185,6 +189,70 @@ export function normalizeListParam(value: unknown): string[] {
  * Build a TaskRow-shaped object from CompleteTaskParams so the unified
  * renderSummaryContent() can be used at completion time (#2720).
  */
+
+function normalizeReworkResolution(params: CompleteTaskParams): Array<{
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  findingId: string;
+  status: "resolved" | "deferred-with-override";
+  evidence: string;
+  decisionRef?: string;
+}> {
+  return (params.reworkResolution ?? []).map((resolution) => ({
+    milestoneId: params.milestoneId,
+    sliceId: params.sliceId,
+    taskId: params.taskId,
+    findingId: resolution.findingId,
+    status: resolution.status,
+    evidence: resolution.evidence,
+    decisionRef: resolution.decisionRef,
+  }));
+}
+
+function unresolvedReworkError(missingFindingIds: string[]): string {
+  const plural = missingFindingIds.length === 1 ? "finding" : "findings";
+  return `unresolved blocking rework ${plural}: ${missingFindingIds.join(", ")} — provide reworkResolution entries with status resolved and evidence, or status deferred-with-override with evidence and decisionRef, before completing the task`;
+}
+
+function satisfiesBlockingReworkFinding(resolution: ReturnType<typeof normalizeReworkResolution>[number]): boolean {
+  if (resolution.evidence.trim().length === 0) return false;
+  if (resolution.status === "resolved") return true;
+  return (resolution.decisionRef ?? "").trim().length > 0;
+}
+
+/**
+ * Snapshot of a rework finding's status/evidence as it existed *before* this
+ * completion applied its reworkResolution. Captured inside the completion
+ * transaction so the compensating rollback paths can restore the exact prior
+ * state.
+ */
+type ReworkFindingSnapshot = {
+  milestoneId: string;
+  sliceId: string;
+  taskId: string;
+  findingId: string;
+  status: ReworkFindingStatus;
+  evidence: string;
+  decisionRef?: string;
+};
+
+/**
+ * Restore rework findings to their pre-completion state.
+ *
+ * The completion transaction flips blocking findings to resolved/
+ * deferred-with-override via applyReworkResolutions. When a later projection
+ * or escalation write fails and we compensate by reverting the task to
+ * `pending`, we must also revert those findings. Otherwise a retry sees no
+ * unresolved blocking findings (getUnresolvedBlockingReworkFindingsForTask
+ * only returns `pending` rows) and completes the task with the blocking gate
+ * silently skipped.
+ */
+function revertAppliedReworkResolutions(snapshot: ReworkFindingSnapshot[]): void {
+  if (snapshot.length === 0) return;
+  applyReworkResolutions(snapshot);
+}
+
 function paramsToTaskRow(params: CompleteTaskParams, completedAt: string): TaskRow {
   return {
     milestone_id: params.milestoneId,
@@ -271,6 +339,7 @@ export async function handleCompleteTask(
   let guardError: string | null = null;
   let summaryMd = "";
   let repairTaskSummaryRow: TaskRow | null = null;
+  let appliedReworkSnapshot: ReworkFindingSnapshot[] = [];
   const rollbackDbPath = getWorkflowDatabasePath();
 
   // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
@@ -282,6 +351,8 @@ export async function handleCompleteTask(
   // no escalation recorded, and the loop would silently advance past it.
   // The filesystem write happens later (after side effects) because that's
   // the cheapest ordering and validation is where 99% of failures live.
+  const reworkResolutions = normalizeReworkResolution(params);
+
   let validatedEscalationArtifact: ReturnType<typeof buildEscalationArtifact> | null = null;
   let escalationWriteEnabled = false;
   if (params.escalation) {
@@ -323,6 +394,20 @@ export async function handleCompleteTask(
     }
 
     const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
+    const unresolvedRework = getUnresolvedBlockingReworkFindingsForTask(params.milestoneId, params.sliceId, params.taskId);
+    const resolvedFindingIds = new Set(
+      reworkResolutions
+        .filter(satisfiesBlockingReworkFinding)
+        .map((resolution) => resolution.findingId),
+    );
+    const missingFindingIds = unresolvedRework
+      .filter((finding) => !resolvedFindingIds.has(finding.finding_id))
+      .map((finding) => finding.finding_id);
+    if (missingFindingIds.length > 0) {
+      guardError = unresolvedReworkError(missingFindingIds);
+      return;
+    }
+
     if (existingTask && isClosedStatus(existingTask.status)) {
       // Stale-turn path: a timed-out turn that was superseded by recovery
       // can still reach this code when its LLM call eventually returns and
@@ -378,6 +463,38 @@ export async function handleCompleteTask(
       fullSummaryMd: summaryMd,
     });
 
+    // Only persist resolutions that actually satisfy the evidence
+    // requirement. The guard above admits a finding as long as ONE satisfying
+    // entry exists, but applyReworkResolutions writes by findingId and lets the
+    // last entry win. Persisting every entry would let a later non-satisfying
+    // duplicate (empty evidence, or deferred-with-override without decisionRef)
+    // overwrite a valid resolution and leave the finding non-pending without
+    // acceptable evidence. Filtering with the same predicate the guard uses
+    // keeps the applied set and the gate consistent.
+    const resolutionsToApply = reworkResolutions.filter(satisfiesBlockingReworkFinding);
+    if (resolutionsToApply.length > 0) {
+      // Snapshot the pre-resolution state of the findings we're about to
+      // change so a compensating rollback can restore them exactly (see
+      // revertAppliedReworkResolutions).
+      const resolvedFindingIdsForSnapshot = new Set(resolutionsToApply.map((r) => r.findingId));
+      appliedReworkSnapshot = getBlockingReworkFindingsForTask(
+        params.milestoneId,
+        params.sliceId,
+        params.taskId,
+      )
+        .filter((finding) => resolvedFindingIdsForSnapshot.has(finding.finding_id))
+        .map((finding) => ({
+          milestoneId: params.milestoneId,
+          sliceId: params.sliceId,
+          taskId: params.taskId,
+          findingId: finding.finding_id,
+          status: finding.status,
+          evidence: finding.evidence,
+          decisionRef: finding.decision_ref,
+        }));
+      applyReworkResolutions(resolutionsToApply);
+    }
+
     for (const evidence of (params.verificationEvidence ?? [])) {
       insertVerificationEvidence({
         taskId: params.taskId,
@@ -459,6 +576,7 @@ export async function handleCompleteTask(
       ensureWorkflowDbAtPath(rollbackDbPath);
       deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
       updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, "pending");
+      revertAppliedReworkResolutions(appliedReworkSnapshot);
       invalidateStateCache();
       rollbackSucceeded = true;
     } catch (rollbackErr) {
@@ -559,6 +677,7 @@ export async function handleCompleteTask(
         try {
           deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
           updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
+          revertAppliedReworkResolutions(appliedReworkSnapshot);
           invalidateStateCache();
           logWarning(
             "tool",
@@ -580,6 +699,7 @@ export async function handleCompleteTask(
       try {
         deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
         updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
+        revertAppliedReworkResolutions(appliedReworkSnapshot);
         invalidateStateCache();
         logWarning(
           "tool",

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

@@ -5,7 +5,7 @@ import { getGateIdsForTurn } from "../gate-registry.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning, insertGateRow, setSliceSketchFlag } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb, renderPlanFromDb } from "../markdown-renderer.js";
-import { resolveTasksDir } from "../paths.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";
@@ -255,21 +255,19 @@ 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).
+    const milestonePath = resolveMilestonePath(basePath, params.milestoneId);
+    const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+    const isLegacySliceLayout = Boolean(milestonePath && slicePath && slicePath !== milestonePath);
+    let renderedPath: string;
     let slicePlanSynced = false;
-    try {
-      const tDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-      if (!tDir) {
-        await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
-        slicePlanSynced = true;
-      }
-    } catch (syncErr) {
-      logWarning("tool", `plan-task: slice-plan sync failed: ${(syncErr as Error).message}`);
+
+    if (isLegacySliceLayout) {
+      const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
+      renderedPath = renderResult.taskPlanPath;
+    } else {
+      const renderResult = await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+      renderedPath = renderResult.planPath;
+      slicePlanSynced = true;
     }
 
     if (slicePlanSynced) {
@@ -299,7 +297,7 @@ export async function handlePlanTask(
       milestoneId: params.milestoneId,
       sliceId: params.sliceId,
       taskId: params.taskId,
-      taskPlanPath: renderResult.taskPlanPath,
+      taskPlanPath: renderedPath,
     };
   } catch (err) {
     return { error: `render failed: ${(err as Error).message}` };

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/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}` };
+  }
+}