gsd-pi 2.44.0-dev.d25d507 → 2.45.0-dev.1afbdaa

package/src/resources/extensions/gsd/tests/worktree-journal-events.test.ts

@@ -0,0 +1,220 @@
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  WorktreeResolver,
+  type WorktreeResolverDeps,
+  type NotifyCtx,
+} from "../worktree-resolver.js";
+import { AutoSession } from "../auto/session.js";
+import type { JournalEntry } from "../journal.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeSession(
+  overrides?: Partial<{ basePath: string; originalBasePath: string }>,
+): AutoSession {
+  const s = new AutoSession();
+  s.basePath = overrides?.basePath ?? "/project";
+  s.originalBasePath = overrides?.originalBasePath ?? "/project";
+  return s;
+}
+
+function makeDeps(
+  overrides?: Partial<WorktreeResolverDeps>,
+): WorktreeResolverDeps {
+  const deps: WorktreeResolverDeps = {
+    isInAutoWorktree: () => false,
+    shouldUseWorktreeIsolation: () => true,
+    getIsolationMode: () => "worktree",
+    mergeMilestoneToMain: () => ({ pushed: false, codeFilesChanged: true }),
+    syncWorktreeStateBack: () => ({ synced: [] }),
+    teardownAutoWorktree: () => {},
+    createAutoWorktree: (_basePath: string, milestoneId: string) =>
+      `/project/.gsd/worktrees/${milestoneId}`,
+    enterAutoWorktree: (_basePath: string, milestoneId: string) =>
+      `/project/.gsd/worktrees/${milestoneId}`,
+    getAutoWorktreePath: () => null,
+    autoCommitCurrentBranch: () => {},
+    getCurrentBranch: () => "main",
+    autoWorktreeBranch: (milestoneId: string) => `milestone/${milestoneId}`,
+    resolveMilestoneFile: (_basePath: string, milestoneId: string) =>
+      `/project/.gsd/milestones/${milestoneId}/${milestoneId}-ROADMAP.md`,
+    readFileSync: () => "# Roadmap\n- [x] S01: Slice one\n",
+    GitServiceImpl: class {
+      constructor() {}
+    } as unknown as WorktreeResolverDeps["GitServiceImpl"],
+    loadEffectiveGSDPreferences: () => ({ preferences: { git: {} } }),
+    invalidateAllCaches: () => {},
+    captureIntegrationBranch: () => {},
+    ...overrides,
+  };
+  return deps;
+}
+
+function makeNotifyCtx(): NotifyCtx {
+  return {
+    notify: () => {},
+  };
+}
+
+/** Read all journal entries from a temp .gsd/journal directory. */
+function readJournalEntries(basePath: string): JournalEntry[] {
+  const journalDir = join(basePath, ".gsd", "journal");
+  try {
+    const files = readdirSync(journalDir).filter(f => f.endsWith(".jsonl")).sort();
+    const entries: JournalEntry[] = [];
+    for (const file of files) {
+      const raw = readFileSync(join(journalDir, file), "utf-8");
+      for (const line of raw.split("\n")) {
+        if (!line.trim()) continue;
+        entries.push(JSON.parse(line) as JournalEntry);
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("worktree journal events", () => {
+  let tmp: string;
+  const originalCwd = process.cwd();
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "wt-journal-"));
+  });
+  afterEach(() => {
+    // Restore cwd before cleanup — on Windows, rmSync fails with EPERM
+    // if the process cwd is inside the directory being deleted.
+    try { process.chdir(originalCwd); } catch { /* best-effort */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("enterMilestone emits worktree-enter on success (new worktree)", () => {
+    const s = makeSession({ basePath: tmp, originalBasePath: tmp });
+    const deps = makeDeps({ getAutoWorktreePath: () => null });
+    const resolver = new WorktreeResolver(s, deps);
+
+    resolver.enterMilestone("M001", makeNotifyCtx());
+
+    const entries = readJournalEntries(tmp);
+    const enter = entries.find(e => e.eventType === "worktree-enter");
+    assert.ok(enter, "worktree-enter event should be emitted");
+    assert.equal(enter!.data?.milestoneId, "M001");
+    assert.equal(enter!.data?.created, true);
+    assert.ok(enter!.data?.wtPath);
+  });
+
+  test("enterMilestone emits worktree-enter with created=false for existing worktree", () => {
+    const s = makeSession({ basePath: tmp, originalBasePath: tmp });
+    const deps = makeDeps({
+      getAutoWorktreePath: () => "/project/.gsd/worktrees/M001",
+    });
+    const resolver = new WorktreeResolver(s, deps);
+
+    resolver.enterMilestone("M001", makeNotifyCtx());
+
+    const entries = readJournalEntries(tmp);
+    const enter = entries.find(e => e.eventType === "worktree-enter");
+    assert.ok(enter, "worktree-enter event should be emitted");
+    assert.equal(enter!.data?.created, false);
+  });
+
+  test("enterMilestone emits worktree-skip when isolation disabled", () => {
+    const s = makeSession({ basePath: tmp, originalBasePath: tmp });
+    const deps = makeDeps({ shouldUseWorktreeIsolation: () => false });
+    const resolver = new WorktreeResolver(s, deps);
+
+    resolver.enterMilestone("M001", makeNotifyCtx());
+
+    const entries = readJournalEntries(tmp);
+    const skip = entries.find(e => e.eventType === "worktree-skip");
+    assert.ok(skip, "worktree-skip event should be emitted");
+    assert.equal(skip!.data?.milestoneId, "M001");
+    assert.equal(skip!.data?.reason, "isolation-disabled");
+  });
+
+  test("enterMilestone emits worktree-create-failed on error", () => {
+    const s = makeSession({ basePath: tmp, originalBasePath: tmp });
+    const deps = makeDeps({
+      getAutoWorktreePath: () => null,
+      createAutoWorktree: () => { throw new Error("disk full"); },
+    });
+    const resolver = new WorktreeResolver(s, deps);
+
+    resolver.enterMilestone("M001", makeNotifyCtx());
+
+    const entries = readJournalEntries(tmp);
+    const failed = entries.find(e => e.eventType === "worktree-create-failed");
+    assert.ok(failed, "worktree-create-failed event should be emitted");
+    assert.equal(failed!.data?.milestoneId, "M001");
+    assert.equal(failed!.data?.error, "disk full");
+    assert.equal(failed!.data?.fallback, "project-root");
+  });
+
+  test("mergeAndExit emits worktree-merge-start", () => {
+    const s = makeSession({
+      basePath: join(tmp, "worktree"),
+      originalBasePath: tmp,
+    });
+    const deps = makeDeps({
+      isInAutoWorktree: () => true,
+      getIsolationMode: () => "worktree",
+    });
+    const resolver = new WorktreeResolver(s, deps);
+
+    resolver.mergeAndExit("M001", makeNotifyCtx());
+
+    const entries = readJournalEntries(tmp);
+    const start = entries.find(e => e.eventType === "worktree-merge-start");
+    assert.ok(start, "worktree-merge-start event should be emitted");
+    assert.equal(start!.data?.milestoneId, "M001");
+    assert.equal(start!.data?.mode, "worktree");
+  });
+
+  test("mergeAndExit emits worktree-merge-failed on error", () => {
+    const s = makeSession({
+      basePath: join(tmp, "worktree"),
+      originalBasePath: tmp,
+    });
+    const deps = makeDeps({
+      isInAutoWorktree: () => true,
+      getIsolationMode: () => "worktree",
+      mergeMilestoneToMain: () => { throw new Error("conflict in main"); },
+    });
+    const resolver = new WorktreeResolver(s, deps);
+
+    resolver.mergeAndExit("M001", makeNotifyCtx());
+
+    const entries = readJournalEntries(tmp);
+    const failed = entries.find(e => e.eventType === "worktree-merge-failed");
+    assert.ok(failed, "worktree-merge-failed event should be emitted");
+    assert.equal(failed!.data?.milestoneId, "M001");
+    assert.equal(failed!.data?.error, "conflict in main");
+  });
+
+  test("journal entries have valid flowId, seq, and ts fields", () => {
+    const s = makeSession({ basePath: tmp, originalBasePath: tmp });
+    const deps = makeDeps({ shouldUseWorktreeIsolation: () => false });
+    const resolver = new WorktreeResolver(s, deps);
+
+    resolver.enterMilestone("M001", makeNotifyCtx());
+
+    const entries = readJournalEntries(tmp);
+    assert.ok(entries.length > 0, "at least one entry should exist");
+    const entry = entries[0];
+    assert.ok(entry.flowId, "flowId should be set");
+    assert.ok(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(entry.flowId),
+      "flowId should be a valid UUID",
+    );
+    assert.equal(entry.seq, 0);
+    assert.ok(entry.ts, "ts should be set");
+    assert.ok(!isNaN(Date.parse(entry.ts)), "ts should be a valid ISO date");
+  });
+});

package/src/resources/extensions/gsd/tests/worktree-submodule-safety.test.ts

@@ -0,0 +1,65 @@
+/**
+ * worktree-submodule-safety.test.ts — #2337
+ *
+ * Worktree teardown (removeWorktree) uses --force which destroys
+ * uncommitted changes in submodule directories. This test verifies
+ * that the removal logic detects submodules and preserves their state.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertTrue, report } = createTestContext();
+
+const srcPath = join(import.meta.dirname, "..", "worktree-manager.ts");
+const src = readFileSync(srcPath, "utf-8");
+
+console.log("\n=== #2337: Worktree teardown preserves submodule state ===");
+
+// ── Test 1: removeWorktree function exists ──────────────────────────────
+
+const removeWorktreeIdx = src.indexOf("export function removeWorktree");
+assertTrue(removeWorktreeIdx > 0, "worktree-manager.ts exports removeWorktree");
+
+const fnBody = src.slice(removeWorktreeIdx, removeWorktreeIdx + 3000);
+
+// ── Test 2: The function checks for submodules before force removal ─────
+
+const checksSubmodules =
+  fnBody.includes("submodule") ||
+  fnBody.includes(".gitmodules");
+
+assertTrue(
+  checksSubmodules,
+  "removeWorktree checks for submodules before force removal (#2337)",
+);
+
+// ── Test 3: Submodule changes are stashed or warned about ───────────────
+
+const preservesSubmoduleState =
+  fnBody.includes("stash") ||
+  fnBody.includes("uncommitted") ||
+  fnBody.includes("dirty") ||
+  fnBody.includes("submodule") && (fnBody.includes("warn") || fnBody.includes("preserv"));
+
+assertTrue(
+  preservesSubmoduleState,
+  "removeWorktree preserves or warns about submodule uncommitted changes (#2337)",
+);
+
+// ── Test 4: Force removal is skipped when submodules have changes ───────
+
+// The key fix: when submodules have dirty state, we should NOT use force
+// removal. Instead, use non-force first and fall back to force only after
+// submodule state is preserved.
+const hasConditionalForce =
+  fnBody.includes("submodule") &&
+  (fnBody.includes("force") || fnBody.includes("--force"));
+
+assertTrue(
+  hasConditionalForce,
+  "removeWorktree has conditional force logic around submodules (#2337)",
+);
+
+report();

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

@@ -0,0 +1,76 @@
+// GSD Extension — write-intercept unit tests
+// Tests isBlockedStateFile() and BLOCKED_WRITE_ERROR constant.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isBlockedStateFile, BLOCKED_WRITE_ERROR } from '../write-intercept.ts';
+
+// ─── isBlockedStateFile: blocked paths ───────────────────────────────────
+
+test('write-intercept: blocks unix .gsd/STATE.md path', () => {
+  assert.strictEqual(isBlockedStateFile('/project/.gsd/STATE.md'), true);
+});
+
+test('write-intercept: blocks relative path with dir prefix before .gsd/STATE.md', () => {
+  assert.strictEqual(isBlockedStateFile('project/.gsd/STATE.md'), true);
+});
+
+test('write-intercept: blocks bare relative .gsd/STATE.md (no leading separator)', () => {
+  // (^|[/\\]) matches paths that start with .gsd/ — covers the case where write
+  // tools receive a bare relative path before the file exists (realpathSync fails).
+  assert.strictEqual(isBlockedStateFile('.gsd/STATE.md'), true);
+});
+
+test('write-intercept: blocks nested project .gsd/STATE.md path', () => {
+  assert.strictEqual(isBlockedStateFile('/Users/dev/my-project/.gsd/STATE.md'), true);
+});
+
+test('write-intercept: blocks .gsd/projects/<name>/STATE.md (symlinked projects path)', () => {
+  assert.strictEqual(isBlockedStateFile('/home/user/.gsd/projects/my-project/STATE.md'), true);
+});
+
+// ─── isBlockedStateFile: allowed paths ───────────────────────────────────
+
+test('write-intercept: allows .gsd/ROADMAP.md', () => {
+  assert.strictEqual(isBlockedStateFile('/project/.gsd/ROADMAP.md'), false);
+});
+
+test('write-intercept: allows .gsd/PLAN.md', () => {
+  assert.strictEqual(isBlockedStateFile('/project/.gsd/PLAN.md'), false);
+});
+
+test('write-intercept: allows .gsd/REQUIREMENTS.md', () => {
+  assert.strictEqual(isBlockedStateFile('/project/.gsd/REQUIREMENTS.md'), false);
+});
+
+test('write-intercept: allows .gsd/SUMMARY.md', () => {
+  assert.strictEqual(isBlockedStateFile('/project/.gsd/SUMMARY.md'), false);
+});
+
+test('write-intercept: allows .gsd/PROJECT.md', () => {
+  assert.strictEqual(isBlockedStateFile('/project/.gsd/PROJECT.md'), false);
+});
+
+test('write-intercept: allows regular source files', () => {
+  assert.strictEqual(isBlockedStateFile('/project/src/index.ts'), false);
+});
+
+test('write-intercept: allows slice plan files', () => {
+  assert.strictEqual(isBlockedStateFile('/project/.gsd/milestones/M001/slices/S01/S01-PLAN.md'), false);
+});
+
+test('write-intercept: does not block files named STATE.md outside .gsd/', () => {
+  assert.strictEqual(isBlockedStateFile('/project/docs/STATE.md'), false);
+});
+
+// ─── BLOCKED_WRITE_ERROR: content ────────────────────────────────────────
+
+test('write-intercept: BLOCKED_WRITE_ERROR is a non-empty string', () => {
+  assert.strictEqual(typeof BLOCKED_WRITE_ERROR, 'string');
+  assert.ok(BLOCKED_WRITE_ERROR.length > 0);
+});
+
+test('write-intercept: BLOCKED_WRITE_ERROR mentions engine tool calls', () => {
+  assert.ok(BLOCKED_WRITE_ERROR.includes('gsd_complete_task'), 'should mention gsd_complete_task');
+  assert.ok(BLOCKED_WRITE_ERROR.includes('engine tool calls'), 'should mention engine tool calls');
+});

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

@@ -11,12 +11,17 @@ import { mkdirSync } from "node:fs";
 
 import {
   transaction,
+  getMilestone,
   getMilestoneSlices,
+  getSliceTasks,
   _getAdapter,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 
 export interface CompleteMilestoneParams {
   milestoneId: string;
@@ -31,6 +36,11 @@ export interface CompleteMilestoneParams {
   lessonsLearned: string[];
   followUps: string;
   deviations: string;
+  verificationPassed: boolean;
+  /** Optional caller-provided identity for audit trail */
+  actorName?: string;
+  /** Optional caller-provided reason this action was triggered */
+  triggerReason?: string;
 }
 
 export interface CompleteMilestoneResult {
@@ -108,22 +118,53 @@ export async function handleCompleteMilestone(
     return { error: "title is required and must be a non-empty string" };
   }
 
-  // ── Verify all slices are complete ───────────────────────────────────────
-  const slices = getMilestoneSlices(params.milestoneId);
-  if (slices.length === 0) {
-    return { error: `no slices found for milestone ${params.milestoneId}` };
+  // ── Verify that verification passed ─────────────────────────────────────
+  if (params.verificationPassed !== true) {
+    return { error: "verification did not pass — milestone completion blocked. verificationPassed must be explicitly set to true after all verification steps succeed" };
   }
 
-  const incompleteSlices = slices.filter(s => s.status !== "complete" && s.status !== "done");
-  if (incompleteSlices.length > 0) {
-    const incompleteIds = incompleteSlices.map(s => `${s.id} (status: ${s.status})`).join(", ");
-    return { error: `incomplete slices: ${incompleteIds}` };
-  }
-
-  // ── DB writes inside a transaction ──────────────────────────────────────
+  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   const completedAt = new Date().toISOString();
+  let guardError: string | null = null;
 
   transaction(() => {
+    // State machine preconditions (inside txn for atomicity)
+    const milestone = getMilestone(params.milestoneId);
+    if (!milestone) {
+      guardError = `milestone not found: ${params.milestoneId}`;
+      return;
+    }
+    if (milestone.status === "complete" || milestone.status === "done") {
+      guardError = `milestone ${params.milestoneId} is already complete`;
+      return;
+    }
+
+    // Verify all slices are complete
+    const slices = getMilestoneSlices(params.milestoneId);
+    if (slices.length === 0) {
+      guardError = `no slices found for milestone ${params.milestoneId}`;
+      return;
+    }
+
+    const incompleteSlices = slices.filter(s => s.status !== "complete" && s.status !== "done");
+    if (incompleteSlices.length > 0) {
+      const incompleteIds = incompleteSlices.map(s => `${s.id} (status: ${s.status})`).join(", ");
+      guardError = `incomplete slices: ${incompleteIds}`;
+      return;
+    }
+
+    // Deep check: verify all tasks in all slices are complete
+    for (const slice of slices) {
+      const tasks = getSliceTasks(params.milestoneId, slice.id);
+      const incompleteTasks = tasks.filter(t => t.status !== "complete" && t.status !== "done");
+      if (incompleteTasks.length > 0) {
+        const ids = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
+        guardError = `slice ${slice.id} has incomplete tasks: ${ids}`;
+        return;
+      }
+    }
+
+    // All guards passed — perform write
     const adapter = _getAdapter()!;
     adapter.prepare(
       `UPDATE milestones SET status = 'complete', completed_at = :completed_at WHERE id = :mid`,
@@ -133,6 +174,10 @@ export async function handleCompleteMilestone(
     });
   });
 
+  if (guardError) {
+    return { error: guardError };
+  }
+
   // ── Filesystem operations (outside transaction) ─────────────────────────
   const summaryMd = renderMilestoneSummaryMarkdown(params);
 
@@ -169,6 +214,24 @@ export async function handleCompleteMilestone(
   clearPathCache();
   clearParseCache();
 
+  // ── Post-mutation hook: projections, manifest, event log ───────────────
+  try {
+    await renderAllProjections(basePath, params.milestoneId);
+    writeManifest(basePath);
+    appendEvent(basePath, {
+      cmd: "complete-milestone",
+      params: { milestoneId: params.milestoneId },
+      ts: new Date().toISOString(),
+      actor: "agent",
+      actor_name: params.actorName,
+      trigger_reason: params.triggerReason,
+    });
+  } catch (hookErr) {
+    process.stderr.write(
+      `gsd: complete-milestone post-mutation hook warning: ${(hookErr as Error).message}\n`,
+    );
+  }
+
   return {
     milestoneId: params.milestoneId,
     summaryPath,

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

@@ -15,14 +15,20 @@ import {
   transaction,
   insertMilestone,
   insertSlice,
+  getSlice,
   getSliceTasks,
+  getMilestone,
   updateSliceStatus,
   _getAdapter,
 } from "../gsd-db.js";
 import { resolveSliceFile, resolveSlicePath, clearPathCache } from "../paths.js";
+import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapCheckboxes } from "../markdown-renderer.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 
 export interface CompleteSliceResult {
   sliceId: string;
@@ -200,27 +206,60 @@ export async function handleCompleteSlice(
     return { error: "milestoneId is required and must be a non-empty string" };
   }
 
-  // ── Verify all tasks are complete ───────────────────────────────────────
-  const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-  if (tasks.length === 0) {
-    return { error: `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}` };
+  // ── Ownership check (opt-in: only enforced when claim file exists) ──────
+  const ownershipErr = checkOwnership(
+    basePath,
+    sliceUnitKey(params.milestoneId, params.sliceId),
+    params.actorName,
+  );
+  if (ownershipErr) {
+    return { error: ownershipErr };
   }
 
-  const incompleteTasks = tasks.filter(t => t.status !== "complete");
-  if (incompleteTasks.length > 0) {
-    const incompleteIds = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
-    return { error: `incomplete tasks: ${incompleteIds}` };
-  }
-
-  // ── DB writes inside a transaction ──────────────────────────────────────
+  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   const completedAt = new Date().toISOString();
+  let guardError: string | null = null;
 
   transaction(() => {
+    // State machine preconditions (inside txn for atomicity).
+    // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
+    // Only block if they exist and are closed.
+    const milestone = getMilestone(params.milestoneId);
+    if (milestone && (milestone.status === "complete" || milestone.status === "done")) {
+      guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
+      return;
+    }
+
+    const slice = getSlice(params.milestoneId, params.sliceId);
+    if (slice && (slice.status === "complete" || slice.status === "done")) {
+      guardError = `slice ${params.sliceId} is already complete — use gsd_slice_reopen first if you need to redo it`;
+      return;
+    }
+
+    // Verify all tasks are complete
+    const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+    if (tasks.length === 0) {
+      guardError = `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}`;
+      return;
+    }
+
+    const incompleteTasks = tasks.filter(t => t.status !== "complete" && t.status !== "done");
+    if (incompleteTasks.length > 0) {
+      const incompleteIds = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
+      guardError = `incomplete tasks: ${incompleteIds}`;
+      return;
+    }
+
+    // All guards passed — perform writes
     insertMilestone({ id: params.milestoneId });
     insertSlice({ id: params.sliceId, milestoneId: params.milestoneId });
     updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
   });
 
+  if (guardError) {
+    return { error: guardError };
+  }
+
   // ── Filesystem operations (outside transaction) ─────────────────────────
   // If disk render fails, roll back the DB status so deriveState() and
   // verifyExpectedArtifact() stay consistent (both say "not done").
@@ -291,6 +330,24 @@ export async function handleCompleteSlice(
   clearPathCache();
   clearParseCache();
 
+  // ── Post-mutation hook: projections, manifest, event log ───────────────
+  try {
+    await renderAllProjections(basePath, params.milestoneId);
+    writeManifest(basePath);
+    appendEvent(basePath, {
+      cmd: "complete-slice",
+      params: { milestoneId: params.milestoneId, sliceId: params.sliceId },
+      ts: new Date().toISOString(),
+      actor: "agent",
+      actor_name: params.actorName,
+      trigger_reason: params.triggerReason,
+    });
+  } catch (hookErr) {
+    process.stderr.write(
+      `gsd: complete-slice post-mutation hook warning: ${(hookErr as Error).message}\n`,
+    );
+  }
+
   return {
     sliceId: params.sliceId,
     milestoneId: params.milestoneId,