@opengsd/gsd-pi 1.7.0 → 1.8.1-dev.897b3c90

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -1698,6 +1698,10 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
                     `Safety: task ${sTid} claimed passing verification that failed in recorded execution`,
                     "error",
                   );
+                  const gitActionResult = await runCloseoutGitAction(pctx, s.currentUnit);
+                  if (gitActionResult === "dispatched") {
+                    return "dispatched";
+                  }
                   await pauseAuto(ctx, pi);
                   return "dispatched";
                 }

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -28,7 +28,7 @@ import type { GSDPreferences } from "./preferences.js";
 import { join, basename, relative, sep } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary, type MinimalModelRegistry } from "./context-budget.js";
-import { getGateResults, getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
+import { getBlockingReworkFindingsForTask, getGateResults, getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
 import {
   GATE_REGISTRY,
   assertGateCoverage,
@@ -106,6 +106,34 @@ function resolveSummaryBudgetChars(): number {
   return resolvePromptBudgets().summaryBudgetChars;
 }
 
+
+function renderBlockingReworkFindingsBlock(mid: string, sid: string, tid: string): string {
+  const findings = getBlockingReworkFindingsForTask(mid, sid, tid)
+    .filter((finding) => finding.status === "pending");
+  if (findings.length === 0) return "";
+
+  const lines = [
+    "## Blocking Rework Findings (non-optional)",
+    "",
+    "This task has structured blocking rework findings. Address every finding before calling `gsd_task_complete`. Include `reworkResolution` entries with each `findingId`, `status: \"resolved\"`, and concrete evidence. If deferring a finding, use `status: \"deferred-with-override\"` with concrete evidence and `decisionRef`.",
+    "",
+  ];
+  for (const finding of findings) {
+    lines.push(`### ${finding.finding_id} (${finding.severity})`);
+    lines.push(`- Status: ${finding.status}`);
+    lines.push(`- Finding: ${finding.description}`);
+    lines.push(`- Required fix: ${finding.required_fix}`);
+    if (finding.verification_commands.length > 0) {
+      lines.push("- Required verification:");
+      for (const command of finding.verification_commands) {
+        lines.push(`  - \`${command}\``);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trim();
+}
+
 function formatProjectClassificationForPlanning(classification: ProjectClassification): string {
   const sampleFiles = classification.contentFiles.slice(0, 8);
   const sample = sampleFiles.length > 0 ? sampleFiles.map((file) => `\`${file}\``).join(", ") : "(none)";
@@ -2745,6 +2773,15 @@ export async function buildExecuteTaskPrompt(
     logWarning("prompt", `reopen reason injection failed: ${(reopenErr as Error).message}`);
   }
 
+  const reworkFindingsBlock = renderBlockingReworkFindingsBlock(mid, sid, tid);
+  if (reworkFindingsBlock) {
+    const block = reworkFindingsBlock + "\n\n---\n\n";
+    phaseAnchorSection = phaseAnchorSection
+      ? `${block}${phaseAnchorSection}`
+      : block;
+    trackPromptContext(contextTelemetry, "rework-findings", "inline", reworkFindingsBlock);
+  }
+
   // ADR-011 Phase 2: inject any resolved-but-unapplied escalation override
   // into this task's prompt. Claim is atomic via DB UPDATE WHERE IS NULL, so
   // if a parallel build already injected it, we skip. Feature-gated by

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

@@ -19,7 +19,7 @@ import type {
   SessionMessageEntry,
 } from "@gsd/pi-coding-agent";
 
-import { deriveState } from "./state.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import {
   buildRequirementsBacklogSummaryLines,
   countUnmappedActiveRequirements,
@@ -443,6 +443,9 @@ function captureMilestoneLockEnv(milestoneId: string | null): void {
   } else {
     delete process.env.GSD_MILESTONE_LOCK;
   }
+  // The derive cache is keyed on basePath only; GSD_MILESTONE_LOCK changes
+  // what deriveState computes, so a lock flip must not serve a cached result.
+  invalidateStateCache();
 }
 
 function restoreMilestoneLockEnv(): void {
@@ -457,6 +460,7 @@ function restoreMilestoneLockEnv(): void {
   s.previousMilestoneLockEnv = null;
   s.hadMilestoneLockEnv = false;
   s.milestoneLockEnvCaptured = false;
+  invalidateStateCache();
 }
 
 /**

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -771,12 +771,12 @@ export function registerDbTools(pi: ExtensionAPI): void {
     name: "gsd_plan_task",
     label: "Plan Task",
     description:
-      "Write task planning state to the GSD database, render tasks/T##-PLAN.md from DB, and clear caches after a successful render.",
-    promptSnippet: "Plan a task via DB write + task PLAN render + cache invalidation",
+      "Write task planning state to the GSD database, render the slice PLAN from DB, and clear caches after a successful render.",
+    promptSnippet: "Plan a task via DB write + slice PLAN render + cache invalidation",
     promptGuidelines: [
-      "Use gsd_plan_task for task planning instead of writing tasks/T##-PLAN.md directly.",
+      "Use gsd_plan_task for task planning instead of writing task PLAN files directly.",
       "Keep parameters flat and provide the full task planning payload.",
-      "The tool validates input, requires an existing parent slice, writes task planning data, renders the task PLAN file from DB, and clears both state and parse caches after success.",
+      "The tool validates input, requires an existing parent slice, writes task planning data, renders the slice PLAN file from DB, and clears both state and parse caches after success.",
       "Use the canonical name gsd_plan_task; gsd_task_plan is only an alias.",
     ],
     parameters: Type.Object({
@@ -860,6 +860,15 @@ export function registerDbTools(pi: ExtensionAPI): void {
         }),
         { description: "Array of verification evidence entries (structured objects only)" },
       )),
+      reworkResolution: Type.Optional(Type.Array(
+        Type.Object({
+          findingId: Type.String({ description: "Rework finding ID being resolved (e.g. F1)" }),
+          status: StringEnum(["resolved", "deferred-with-override"], { description: "Resolution status for this finding" }),
+          evidence: Type.String({ description: "Concrete evidence that the required fix was completed" }),
+          decisionRef: Type.Optional(Type.String({ description: "Decision reference required for deferred-with-override findings" })),
+        }),
+        { description: "Resolution evidence for structured rework findings linked to this task" },
+      )),
       // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
       actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
       triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered (e.g. 'task verified after retry')" })),
@@ -1180,6 +1189,84 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   registerWorkflowTool(pi, replanSliceTool);
 
+  // ─── gsd_replan_task ───────────────────────────────────────────────────
+
+  const replanTaskExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const { executeReplanTask } = await loadWorkflowExecutors();
+    return executeReplanTask(params, resolveWorkflowToolBasePath(_ctx, params));
+  };
+
+  const replanTaskTool = {
+    name: "gsd_replan_task",
+    label: "Replan Task",
+    description:
+      "Update one pending task's planning contract after rework without touching sibling tasks. " +
+      "Completed tasks are structurally protected. Re-renders the task/slice PLAN projection and records replan history.",
+    promptSnippet: "Replan one pending GSD task after rework",
+    promptGuidelines: [
+      "Use gsd_replan_task when a reopened pending task needs its title, description, files, verify, inputs, or expectedOutput updated for rework.",
+      "The task must already exist and be pending; completed tasks are rejected.",
+      "Set reworkBriefRef when a structured rework brief triggered the task replan.",
+    ],
+    parameters: Type.Object({
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+      taskId: Type.String({ description: "Task ID (e.g. T01)" }),
+      title: Type.String({ description: "Updated task title" }),
+      description: Type.String({ description: "Updated task description incorporating rework scope" }),
+      estimate: Type.String({ description: "Updated task estimate string" }),
+      files: Type.Array(Type.String(), { description: "Updated files likely touched" }),
+      verify: Type.String({ description: "Updated verification command or block" }),
+      inputs: Type.Array(Type.String(), { description: "Updated input files or references" }),
+      expectedOutput: Type.Array(Type.String(), { description: "Updated files this task creates or overwrites" }),
+      reworkBriefRef: Type.Optional(Type.String({ description: "Rework brief ID/reference that triggered this task replan" })),
+      actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail" })),
+      triggerReason: Type.Optional(Type.String({ description: "Caller-provided reason this action was triggered" })),
+    }),
+    execute: replanTaskExecute,
+  };
+
+  registerWorkflowTool(pi, replanTaskTool);
+
+  // ─── gsd_rework_brief_save ─────────────────────────────────────────────
+
+  const reworkBriefSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const { executeReworkBriefSave } = await loadWorkflowExecutors();
+    return executeReworkBriefSave(params, resolveWorkflowToolBasePath(_ctx, params));
+  };
+
+  const reworkBriefSaveTool = {
+    name: "gsd_rework_brief_save",
+    label: "Save Rework Brief",
+    description:
+      "Persist a structured rework brief for a task. Blocking findings are enforced by gsd_task_complete until resolved with evidence.",
+    promptSnippet: "Persist structured task rework findings",
+    promptGuidelines: [
+      "Use gsd_rework_brief_save when post-unit checks produce task rework findings.",
+      "Use severity 'blocking' for findings that must be resolved before gsd_task_complete succeeds.",
+      "Each finding needs a stable findingId, requiredFix, and verificationCommands.",
+    ],
+    parameters: Type.Object({
+      briefId: Type.Optional(Type.String({ description: "Stable brief ID; omitted defaults to RB-<milestone>-<slice>-<task>" })),
+      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+      sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+      taskId: Type.String({ description: "Task ID (e.g. T01)" }),
+      findings: Type.Array(Type.Object({
+        findingId: Type.String({ description: "Stable finding ID (e.g. F1)" }),
+        severity: StringEnum(["blocking", "advisory"], { description: "Whether this finding blocks task completion" }),
+        description: Type.String({ description: "What was found" }),
+        requiredFix: Type.String({ description: "What must change" }),
+        verificationCommands: Type.Array(Type.String(), { description: "Commands that must pass after the fix" }),
+        status: Type.Optional(StringEnum(["pending", "resolved", "deferred-with-override"], { description: "Finding status; defaults to pending" })),
+        evidence: Type.Optional(Type.String({ description: "Resolution evidence when already resolved" })),
+        decisionRef: Type.Optional(Type.String({ description: "Decision reference for deferred-with-override" })),
+      }), { description: "Structured rework findings for this task" }),
+    }),
+    execute: reworkBriefSaveExecute,
+  };
+
+  registerWorkflowTool(pi, reworkBriefSaveTool);
+
   // ─── gsd_reassess_roadmap (gsd_roadmap_reassess alias) ─────────────────
 
   const reassessRoadmapExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -10,6 +10,7 @@ import { loadJsonFileOrNull } from "../json-persistence.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
+import { acquireSyncLock, releaseSyncLock } from "../sync-lock.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
 import { bashReferencesProjectRootOutsideWorktree } from "../worktree-shell-guard.js";
@@ -364,12 +365,63 @@ export function refreshWriteGateStateFromDisk(basePath: string): WriteGateSnapsh
   return currentWriteGateSnapshot(basePath);
 }
 
+const WRITE_GATE_LOCK_NAME = "write-gate.lock";
+
+/**
+ * Test-only seam: fires once inside the held cross-process lock (after acquire,
+ * before the read-merge-write body) with the resolved lock root. Lets a
+ * regression test observe that a concurrent process is genuinely locked out of
+ * the critical section. Production leaves it null. Follows the repo's
+ * `_setGhAvailableForTest` naming convention.
+ */
+let interleaveHookForTest: ((lockRoot: string) => void) | null = null;
+export function _setWriteGateInterleaveHookForTest(fn: ((lockRoot: string) => void) | null): void {
+  interleaveHookForTest = fn;
+}
+
+/**
+ * Serialize the read-merge-write critical section across the two processes
+ * that share the snapshot file (extension host + workflow MCP child). Atomic
+ * rename prevents torn files but not lost updates: without this lock the host
+ * can read the snapshot, the child can arm a gate and persist, then the host's
+ * later persist overwrites `pendingGateId`/`activeQueuePhase` (last-writer-wins
+ * fields) and silently drops the armed HARD-BLOCK gate.
+ *
+ * Fail-OPEN by contract: if a live peer holds the lock we proceed WITHOUT it —
+ * exactly the racy-but-functional behavior that shipped before this lock — and
+ * log once. The lock shrinks the race window to ~zero; it must never block,
+ * throw, or refuse a gate mutation. The lock is skipped entirely when snapshot
+ * persistence is off (no disk file, no cross-process seam).
+ */
+function withWriteGateLock<T>(basePath: string, fn: () => T): T {
+  if (!shouldPersistWriteGateSnapshot()) return fn();
+  const lockRoot = resolveWriteGateSnapshotRoot(basePath);
+  // Materialize `.gsd/` (including a dangling external-state symlink target)
+  // before locking. acquireSyncLock's own mkdir does NOT follow a symlink to
+  // create its target, so without this the O_EXCL open lands on a missing
+  // parent and the lock silently fails open — leaving the seam unserialized
+  // for exactly the external-state projects that need it. This is the same
+  // directory the persist path ensures anyway.
+  try { ensureWriteGateSnapshotDirectory(basePath); } catch { /* best-effort; acquire fails-open below */ }
+  const { acquired } = acquireSyncLock(lockRoot, 0, WRITE_GATE_LOCK_NAME);
+  if (!acquired) {
+    logWarning("intercept", "write-gate: proceeding without cross-process lock (held by live peer)", { lockRoot });
+    return fn();
+  }
+  try {
+    interleaveHookForTest?.(lockRoot);
+    return fn();
+  } finally {
+    releaseSyncLock(lockRoot, WRITE_GATE_LOCK_NAME);
+  }
+}
+
 /**
  * Read-modify-write primitive for gate mutations. Reconciles the disk
  * snapshot into memory (union merge), applies the mutation on top, then
- * persists. The whole sequence is synchronous, so the reconcile read
- * doubles as the pre-persist merge of concurrent writes — there is no
- * version field; the read-merge-write is simply unconditional.
+ * persists — all under the cross-process lock (withWriteGateLock). The whole
+ * sequence is synchronous, so the reconcile read doubles as the pre-persist
+ * merge of concurrent writes; there is no version field.
  *
  * The mutate callback sees the already-reconciled state, so policy checks
  * (e.g. host setPending's verified-on-disk-wins guard) can live inside it
@@ -385,21 +437,23 @@ function mutateWriteGateState(
   opts?: { writer?: WriteGateWriter; reconcile?: boolean },
 ): boolean {
   const state = getWriteGateState(basePath);
-  if (shouldPersistWriteGateSnapshot() && (opts?.reconcile ?? true)) {
-    const disk = readDiskSnapshot(basePath);
-    if (disk) {
-      mergeSnapshotIntoState(state, disk);
-    } else {
-      // Missing OR unparseable on disk: treat as a full reset. Keeping
-      // stale in-memory state across a corrupt snapshot would persist it
-      // back on this very mutation and defeat the documented
-      // "delete the file to clear the HARD BLOCK gate" escape hatch.
-      replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+  return withWriteGateLock(basePath, () => {
+    if (shouldPersistWriteGateSnapshot() && (opts?.reconcile ?? true)) {
+      const disk = readDiskSnapshot(basePath);
+      if (disk) {
+        mergeSnapshotIntoState(state, disk);
+      } else {
+        // Missing OR unparseable on disk: treat as a full reset. Keeping
+        // stale in-memory state across a corrupt snapshot would persist it
+        // back on this very mutation and defeat the documented
+        // "delete the file to clear the HARD BLOCK gate" escape hatch.
+        replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+      }
     }
-  }
-  if (mutate(state) === false) return false;
-  persistWriteGateSnapshot(basePath, opts?.writer ?? defaultWriteGateWriter());
-  return true;
+    if (mutate(state) === false) return false;
+    persistWriteGateSnapshot(basePath, opts?.writer ?? defaultWriteGateWriter());
+    return true;
+  });
 }
 
 export function isDepthVerified(basePath: string = process.cwd()): boolean {
@@ -643,13 +697,15 @@ export const childWriteGateAdapter: WriteGateStateAdapter = {
 
 function childMutate(basePath: string, mutate: (state: InMemoryWriteGateState) => void): void {
   const state = getWriteGateState(basePath);
-  if (shouldPersistWriteGateSnapshot()) {
-    // Always-fresh: disk is the only truth for the child; discard any
-    // cross-turn in-memory residue before mutating.
-    replaceStateFromSnapshot(state, readDiskSnapshot(basePath) ?? EMPTY_SNAPSHOT);
-  }
-  mutate(state);
-  persistWriteGateSnapshot(basePath, "child");
+  withWriteGateLock(basePath, () => {
+    if (shouldPersistWriteGateSnapshot()) {
+      // Always-fresh: disk is the only truth for the child; discard any
+      // cross-turn in-memory residue before mutating.
+      replaceStateFromSnapshot(state, readDiskSnapshot(basePath) ?? EMPTY_SNAPSHOT);
+    }
+    mutate(state);
+    persistWriteGateSnapshot(basePath, "child");
+  });
 }
 
 /**

package/src/resources/extensions/gsd/command-feedback.ts

@@ -96,22 +96,29 @@ export function notifyDiscussNeedsInteractiveMenu(
   });
 }
 
-/** Hub picker for /gsd queue (reorder vs add) is unavailable. */
+/**
+ * Hub picker for /gsd queue (reorder vs add) is unavailable.
+ *
+ * Unlike the other picker-guidance notices, /gsd queue does NOT dead-end here:
+ * the caller falls through to the add-work flow, which runs headlessly. So this
+ * notice must avoid the "did not start:" picker-failure phrasing — the headless
+ * host classifies that as a blocked dead-end (see stop-notice.ts / #1294) and
+ * would exit 10 before the add-work run starts.
+ */
 export function notifyQueueHubNeedsInteractiveMenu(
   ctx: ExtensionCommandContext,
   reason: string,
 ): void {
-  notifyPickerCommandNeedsInteractiveMenu(ctx, {
-    command: "/gsd queue",
-    reason,
-    alternatives: [
-      "Add-work flow can run headless — continuing with queue discussion.",
-    ],
-    hints: [
-      "/gsd queue — run from the GSD TUI to reorder pending milestones",
-      "/gsd status — see milestone order and phase",
-    ],
-  });
+  ctx.ui.notify(
+    [
+      `/gsd queue reorder menu needs an interactive session (${reason}).`,
+      "Continuing headless with the add-work flow.",
+      "",
+      "  • /gsd queue — run from the GSD TUI to reorder pending milestones",
+      "  • /gsd status — see milestone order and phase",
+    ].join("\n"),
+    "warning",
+  );
 }
 
 /** /gsd, /gsd new-milestone, /gsd new-project wizard menus. */

package/src/resources/extensions/gsd/compat/compat-marker.ts

@@ -7,7 +7,7 @@
 
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, isAbsolute, normalize } from "node:path";
 
 /** Current marker schema version. Bump on breaking format changes + migrate. */
 export const COMPAT_MARKER_SCHEMA = 2;
@@ -34,8 +34,10 @@ export interface PlanningMarker {
 
 /**
  * Per-file projection entry. `sha` is a normalized-content SHA-256; `entities`
- * is the list of DB entity ids (milestone/slice/task) that the file projects,
- * so repair can scope re-import rather than re-importing the whole tree.
+ * is the list of DB entity ids (milestone/slice/task) that the file projects.
+ * External-edit repair derives milestone ids from this list so markdown status
+ * authority is limited to the drifted projection's milestone scope while the
+ * importer still walks the whole tree.
  */
 export interface ProjectionEntry {
   sha: string;
@@ -220,9 +222,24 @@ function isValidProjectionEntry(x: unknown): x is ProjectionEntry {
   return true;
 }
 
+/**
+ * Projection-map keys are repo-relative paths under .gsd/ or .planning/.
+ * The marker is repo-controlled content, so a key must never escape its
+ * root: reject absolute paths, drive letters, backslashes, and any
+ * normalized form that starts with "..". Mirrors the write-side guard in
+ * db-writer.ts.
+ */
+function isSafeProjectionKey(key: string): boolean {
+  if (key.length === 0 || key.includes("\\") || key.includes("\0")) return false;
+  if (isAbsolute(key) || /^[A-Za-z]:/.test(key)) return false;
+  const norm = normalize(key);
+  return norm !== ".." && !norm.startsWith("../") && !isAbsolute(norm);
+}
+
 function isValidProjectionMap(x: unknown): boolean {
   if (typeof x !== "object" || x === null) return false;
-  for (const v of Object.values(x as Record<string, unknown>)) {
+  for (const [k, v] of Object.entries(x as Record<string, unknown>)) {
+    if (!isSafeProjectionKey(k)) return false;
     if (!isValidProjectionEntry(v)) return false;
   }
   return true;

package/src/resources/extensions/gsd/db/command-queue.ts

@@ -15,6 +15,7 @@
 
 import {
   _getAdapter,
+  immediateTransaction,
   isDbAvailable,
   transaction,
 } from "../gsd-db.js";
@@ -75,7 +76,12 @@ export function claimNextCommand(workerId: string): CommandQueueRow | null {
   const now = new Date().toISOString();
   const db = _getAdapter()!;
 
-  return transaction((): CommandQueueRow | null => {
+  // BEGIN IMMEDIATE: this is a read-then-write claim. Under WAL, a deferred
+  // transaction that reads first and then upgrades to a writer can fail with
+  // SQLITE_BUSY_SNAPSHOT (not retried by busy_timeout) when two workers race;
+  // taking the write lock up front serializes claimants so the loser waits
+  // and then sees the row already claimed (changes !== 1 → null).
+  return immediateTransaction((): CommandQueueRow | null => {
     // Find the oldest unclaimed command targeted at this worker OR
     // broadcast. The partial index covers both via NULL-in-B-tree.
     const row = db.prepare(

package/src/resources/extensions/gsd/db/engine.ts

@@ -46,6 +46,7 @@ import {
   applyMigrationV27ArtifactHash,
   applyMigrationV28MemoryLastHitAt,
   applyMigrationV29RepositoryTargets,
+  applyMigrationV30ReworkBriefs,
 } from "../db-migration-steps.js";
 import {
   isMemoriesFtsAvailableSchema,
@@ -93,7 +94,7 @@ const providerLoader = createSqliteProviderLoader({
   nodeVersion: process.versions.node,
   writeStderr: (message: string) => process.stderr.write(message),
 });
-export const SCHEMA_VERSION = 29;
+export const SCHEMA_VERSION = 30;
 function initSchema(db: DbAdapter, fileBacked: boolean, dbPath: string | null): void {
   const conservativeFilePragmas = fileBacked && _isLikelyWslDrvFsPathForTest(dbPath);
   if (fileBacked) db.exec(conservativeFilePragmas ? "PRAGMA journal_mode=DELETE" : "PRAGMA journal_mode=WAL");
@@ -114,21 +115,39 @@ function initSchema(db: DbAdapter, fileBacked: boolean, dbPath: string | null):
 
     const existing = db.prepare("SELECT count(*) as cnt FROM schema_version").get();
     if (existing && (existing["cnt"] as number) === 0) {
-      createCoordinationTablesV24(db);
-      createRuntimeKvTableV25(db);
-
-      // Fresh install — all tables are created above with the full current schema,
-      // so it is safe to create all migration-specific indexes here.  For existing
-      // databases these indexes are created inside the individual migration guards
-      // in migrateSchema() after the corresponding columns have been added.
-      db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
-      db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
-      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
-      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
-      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
-      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
-
-      recordSchemaVersion(db, SCHEMA_VERSION);
+      // An empty schema_version table usually means a fresh install, but it can
+      // also be a legacy/truncated DB that already holds user data. Stamping
+      // that DB SCHEMA_VERSION without running migrations would mis-mark it as
+      // fully migrated and break at first query. Probe before stamping.
+      const hasData = ["milestones", "decisions", "memories"].some((t) => {
+        try {
+          const r = db.prepare(`SELECT count(*) as cnt FROM ${t}`).get();
+          return ((r?.["cnt"] as number) ?? 0) > 0;
+        } catch { /* table absent on a truly fresh DB — treat as no data */ return false; }
+      });
+      if (hasData) {
+        // Legacy DB with data but no version row: record the baseline so
+        // migrateSchema runs the full chain instead of stamping the current version.
+        recordSchemaVersion(db, 1);
+      } else {
+        createCoordinationTablesV24(db);
+        createRuntimeKvTableV25(db);
+
+        // Fresh install — all tables are created above with the full current schema,
+        // so it is safe to create all migration-specific indexes here.  For existing
+        // databases these indexes are created inside the individual migration guards
+        // in migrateSchema() after the corresponding columns have been added.
+        db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_rework_briefs_task ON rework_briefs(milestone_id, slice_id, task_id)");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_rework_findings_status ON rework_brief_findings(brief_id, severity, status)");
+
+        recordSchemaVersion(db, SCHEMA_VERSION);
+      }
     }
 
     db.exec("COMMIT");
@@ -183,9 +202,19 @@ function copyQualityGateRowsToRepairedTable(db: DbAdapter): void {
   `);
 }
 
+let _migrationFaultForTest = false;
+/** Test-only: force migrateSchema to throw after applying its steps but before COMMIT. */
+export function _setMigrationFaultForTest(v: boolean): void { _migrationFaultForTest = v; }
+
 function migrateSchema(db: DbAdapter, dbPath: string | null): void {
   const currentVersion = getCurrentSchemaVersion(db);
-  if (currentVersion >= SCHEMA_VERSION) return;
+  if (currentVersion > SCHEMA_VERSION) {
+    throw new Error(
+      `gsd.db schema is v${currentVersion}, newer than the v${SCHEMA_VERSION} this gsd-pi supports. ` +
+      `Update gsd-pi (npm i -g @opengsd/gsd-pi) before opening this project.`,
+    );
+  }
+  if (currentVersion === SCHEMA_VERSION) return;
 
   backupDatabaseBeforeMigration(db, dbPath, currentVersion, {
     existsSync,
@@ -351,6 +380,13 @@ function migrateSchema(db: DbAdapter, dbPath: string | null): void {
       recordSchemaVersion(db, 29);
     }
 
+    if (currentVersion < 30) {
+      applyMigrationV30ReworkBriefs(db);
+      recordSchemaVersion(db, 30);
+    }
+
+    if (_migrationFaultForTest) throw new Error("migration fault injected for test");
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");

package/src/resources/extensions/gsd/db/writers/cascades.ts

@@ -211,7 +211,11 @@ export function skipSliceCascade(milestoneId: string, sliceId: string): SkipSlic
   transaction(() => {
     const slice = getSlice(milestoneId, sliceId);
     if (!slice) { outcome = { ok: false, reason: "slice-not-found" }; return; }
-    if (slice.status === "complete" || slice.status === "done") {
+    // Reject any closed slice except "skipped" (which falls through to the
+    // wasAlreadySkipped no-op). isClosedStatus covers the "closed"/"done"
+    // aliases too — hand-picking literals here nulls a completed slice's
+    // completed_at on re-skip.
+    if (isClosedStatus(slice.status) && slice.status !== "skipped") {
       outcome = { ok: false, reason: "slice-already-complete" };
       return;
     }