gsd-pi 2.45.0-dev.fdcf73c → 2.46.0-dev.5c2b8ed

package/src/resources/extensions/gsd/tests/workflow-manifest.test.ts

@@ -0,0 +1,186 @@
+// GSD Extension — workflow-manifest unit tests
+// Tests writeManifest, readManifest, snapshotState, bootstrapFromManifest.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+} from '../gsd-db.ts';
+import {
+  writeManifest,
+  readManifest,
+  snapshotState,
+  bootstrapFromManifest,
+} from '../workflow-manifest.ts';
+
+function tempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-manifest-'));
+}
+
+function tempDbPath(base: string): string {
+  return path.join(base, 'test.db');
+}
+
+function cleanupDir(dirPath: string): void {
+  try { fs.rmSync(dirPath, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+// ─── readManifest: no file ────────────────────────────────────────────────
+
+test('workflow-manifest: readManifest returns null when file does not exist', () => {
+  const base = tempDir();
+  try {
+    const result = readManifest(base);
+    assert.strictEqual(result, null);
+  } finally {
+    cleanupDir(base);
+  }
+});
+
+// ─── writeManifest + readManifest round-trip ─────────────────────────────
+
+test('workflow-manifest: writeManifest creates state-manifest.json with version 1', () => {
+  const base = tempDir();
+  openDatabase(tempDbPath(base));
+  try {
+    writeManifest(base);
+    const manifestPath = path.join(base, '.gsd', 'state-manifest.json');
+    assert.ok(fs.existsSync(manifestPath), 'state-manifest.json should exist');
+    const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    assert.strictEqual(raw.version, 1);
+  } finally {
+    closeDatabase();
+    cleanupDir(base);
+  }
+});
+
+test('workflow-manifest: readManifest parses manifest written by writeManifest', () => {
+  const base = tempDir();
+  openDatabase(tempDbPath(base));
+  try {
+    writeManifest(base);
+    const manifest = readManifest(base);
+    assert.ok(manifest !== null);
+    assert.strictEqual(manifest!.version, 1);
+    assert.ok(typeof manifest!.exported_at === 'string');
+    assert.ok(Array.isArray(manifest!.milestones));
+    assert.ok(Array.isArray(manifest!.slices));
+    assert.ok(Array.isArray(manifest!.tasks));
+    assert.ok(Array.isArray(manifest!.decisions));
+    assert.ok(Array.isArray(manifest!.verification_evidence));
+  } finally {
+    closeDatabase();
+    cleanupDir(base);
+  }
+});
+
+// ─── snapshotState: captures DB rows ─────────────────────────────────────
+
+test('workflow-manifest: snapshotState includes inserted milestone', () => {
+  const base = tempDir();
+  openDatabase(tempDbPath(base));
+  try {
+    insertMilestone({ id: 'M001', title: 'Auth Milestone' });
+    const snap = snapshotState();
+    assert.strictEqual(snap.version, 1);
+    const m = snap.milestones.find((r) => r.id === 'M001');
+    assert.ok(m !== undefined, 'M001 should appear in snapshot');
+    assert.strictEqual(m!.title, 'Auth Milestone');
+  } finally {
+    closeDatabase();
+    cleanupDir(base);
+  }
+});
+
+test('workflow-manifest: snapshotState captures tasks', () => {
+  const base = tempDir();
+  openDatabase(tempDbPath(base));
+  try {
+    insertMilestone({ id: 'M001' });
+    insertSlice({ id: 'S01', milestoneId: 'M001' });
+    insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Do thing', status: 'complete' });
+    const snap = snapshotState();
+    const t = snap.tasks.find((r) => r.id === 'T01');
+    assert.ok(t !== undefined, 'T01 should appear in snapshot');
+    assert.strictEqual(t!.status, 'complete');
+  } finally {
+    closeDatabase();
+    cleanupDir(base);
+  }
+});
+
+// ─── bootstrapFromManifest ────────────────────────────────────────────────
+
+test('workflow-manifest: bootstrapFromManifest returns false when no manifest file', () => {
+  const base = tempDir();
+  openDatabase(tempDbPath(base));
+  try {
+    const result = bootstrapFromManifest(base);
+    assert.strictEqual(result, false);
+  } finally {
+    closeDatabase();
+    cleanupDir(base);
+  }
+});
+
+test('workflow-manifest: bootstrapFromManifest restores DB from manifest (round-trip)', () => {
+  const base = tempDir();
+  openDatabase(tempDbPath(base));
+  try {
+    // Insert data and write manifest
+    insertMilestone({ id: 'M001', title: 'Restored Milestone' });
+    insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Restored Slice' });
+    insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Restored Task', status: 'complete' });
+    writeManifest(base);
+    closeDatabase();
+
+    // Open a fresh DB and bootstrap from manifest
+    const newDbPath = path.join(base, 'new.db');
+    openDatabase(newDbPath);
+    const result = bootstrapFromManifest(base);
+    assert.strictEqual(result, true, 'bootstrapFromManifest should return true');
+
+    // Verify restored state
+    const snap = snapshotState();
+    const m = snap.milestones.find((r) => r.id === 'M001');
+    assert.ok(m !== undefined, 'M001 should be restored');
+    assert.strictEqual(m!.title, 'Restored Milestone');
+
+    const s = snap.slices.find((r) => r.id === 'S01');
+    assert.ok(s !== undefined, 'S01 should be restored');
+
+    const t = snap.tasks.find((r) => r.id === 'T01');
+    assert.ok(t !== undefined, 'T01 should be restored');
+    assert.strictEqual(t!.status, 'complete');
+  } finally {
+    closeDatabase();
+    cleanupDir(base);
+  }
+});
+
+// ─── readManifest: version check ─────────────────────────────────────────
+
+test('workflow-manifest: readManifest throws on unsupported version', () => {
+  const base = tempDir();
+  try {
+    fs.mkdirSync(path.join(base, '.gsd'), { recursive: true });
+    fs.writeFileSync(
+      path.join(base, '.gsd', 'state-manifest.json'),
+      JSON.stringify({ version: 99, exported_at: '', milestones: [], slices: [], tasks: [], decisions: [], verification_evidence: [] }),
+    );
+    assert.throws(
+      () => readManifest(base),
+      /Unsupported manifest version/,
+      'should throw on version mismatch',
+    );
+  } finally {
+    cleanupDir(base);
+  }
+});

package/src/resources/extensions/gsd/tests/workflow-projections.test.ts

@@ -0,0 +1,171 @@
+// GSD Extension — workflow-projections unit tests
+// Tests the pure rendering functions (no DB required).
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { renderPlanContent } from '../workflow-projections.ts';
+import type { SliceRow, TaskRow } from '../gsd-db.ts';
+
+// ─── Test fixtures ────────────────────────────────────────────────────────
+
+function makeSlice(overrides: Partial<SliceRow> = {}): SliceRow {
+  return {
+    id: 'S01',
+    milestone_id: 'M001',
+    title: 'Auth Layer',
+    status: 'active',
+    risk: 'high',
+    depends: [],
+    demo: 'Login flow works end-to-end',
+    goal: 'Implement JWT authentication',
+    full_summary_md: '',
+    full_uat_md: '',
+    success_criteria: '',
+    proof_level: '',
+    integration_closure: '',
+    observability_impact: '',
+    created_at: '2026-01-01T00:00:00Z',
+    completed_at: null,
+    sequence: 1,
+    replan_triggered_at: null,
+    ...overrides,
+  };
+}
+
+function makeTask(overrides: Partial<TaskRow> = {}): TaskRow {
+  return {
+    id: 'T01',
+    slice_id: 'S01',
+    milestone_id: 'M001',
+    title: 'Create JWT middleware',
+    status: 'pending',
+    description: 'Implement JWT validation middleware',
+    estimate: '2h',
+    files: ['src/middleware/auth.ts'],
+    verify: 'npm test src/middleware/auth.test.ts',
+    one_liner: '',
+    narrative: '',
+    verification_result: '',
+    duration: '',
+    completed_at: null,
+    blocker_discovered: false,
+    deviations: '',
+    known_issues: '',
+    key_files: [],
+    key_decisions: [],
+    full_summary_md: '',
+    full_plan_md: '',
+    inputs: [],
+    expected_output: [],
+    observability_impact: '',
+    sequence: 1,
+    ...overrides,
+  };
+}
+
+// ─── renderPlanContent: structure ────────────────────────────────────────
+
+test('workflow-projections: renderPlanContent starts with H1 containing slice id and title', () => {
+  const content = renderPlanContent(makeSlice(), []);
+  assert.ok(content.startsWith('# S01: Auth Layer'), `expected H1, got: ${content.slice(0, 60)}`);
+});
+
+test('workflow-projections: renderPlanContent includes Goal line', () => {
+  const content = renderPlanContent(makeSlice(), []);
+  assert.ok(content.includes('**Goal:** Implement JWT authentication'));
+});
+
+test('workflow-projections: renderPlanContent includes Demo line', () => {
+  const content = renderPlanContent(makeSlice(), []);
+  assert.ok(content.includes('**Demo:** After this: Login flow works end-to-end'));
+});
+
+test('workflow-projections: renderPlanContent falls back to TBD when goal and full_summary_md are empty', () => {
+  const slice = makeSlice({ goal: '', full_summary_md: '' });
+  const content = renderPlanContent(slice, []);
+  assert.ok(content.includes('**Goal:** TBD'));
+});
+
+test('workflow-projections: renderPlanContent falls back to full_summary_md when goal is empty', () => {
+  const slice = makeSlice({ goal: '', full_summary_md: 'Fallback goal text' });
+  const content = renderPlanContent(slice, []);
+  assert.ok(content.includes('**Goal:** Fallback goal text'));
+});
+
+test('workflow-projections: renderPlanContent includes ## Tasks section', () => {
+  const content = renderPlanContent(makeSlice(), []);
+  assert.ok(content.includes('## Tasks'));
+});
+
+// ─── renderPlanContent: task checkboxes ──────────────────────────────────
+
+test('workflow-projections: pending task renders with [ ] checkbox', () => {
+  const task = makeTask({ status: 'pending' });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(content.includes('- [ ] **T01:'), `expected unchecked, got: ${content}`);
+});
+
+test('workflow-projections: done task renders with [x] checkbox', () => {
+  const task = makeTask({ status: 'done' });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(content.includes('- [x] **T01:'), `expected checked, got: ${content}`);
+});
+
+test('workflow-projections: complete status renders with [x] checkbox', () => {
+  const task = makeTask({ status: 'complete' }); // 'complete' and 'done' both → checked
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(content.includes('- [x] **T01:'));
+});
+
+// ─── renderPlanContent: task sublines ────────────────────────────────────
+
+test('workflow-projections: task with estimate renders Estimate subline', () => {
+  const task = makeTask({ estimate: '2h' });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(content.includes('  - Estimate: 2h'));
+});
+
+test('workflow-projections: task with empty estimate omits Estimate subline', () => {
+  const task = makeTask({ estimate: '' });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(!content.includes('  - Estimate:'));
+});
+
+test('workflow-projections: task with files renders Files subline', () => {
+  const task = makeTask({ files: ['src/auth.ts', 'src/auth.test.ts'] });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(content.includes('  - Files: src/auth.ts, src/auth.test.ts'));
+});
+
+test('workflow-projections: task with empty files array omits Files subline', () => {
+  const task = makeTask({ files: [] });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(!content.includes('  - Files:'));
+});
+
+test('workflow-projections: task with verify renders Verify subline', () => {
+  const task = makeTask({ verify: 'npm test' });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(content.includes('  - Verify: npm test'));
+});
+
+test('workflow-projections: task with no verify omits Verify subline', () => {
+  const task = makeTask({ verify: '' });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(!content.includes('  - Verify:'));
+});
+
+test('workflow-projections: task with duration renders Duration subline', () => {
+  const task = makeTask({ duration: '45m' });
+  const content = renderPlanContent(makeSlice(), [task]);
+  assert.ok(content.includes('  - Duration: 45m'));
+});
+
+test('workflow-projections: multiple tasks rendered in order', () => {
+  const t1 = makeTask({ id: 'T01', title: 'First task', sequence: 1 });
+  const t2 = makeTask({ id: 'T02', title: 'Second task', sequence: 2 });
+  const content = renderPlanContent(makeSlice(), [t1, t2]);
+  const idxT1 = content.indexOf('**T01:');
+  const idxT2 = content.indexOf('**T02:');
+  assert.ok(idxT1 < idxT2, 'T01 should appear before T02');
+});

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;
@@ -32,6 +37,10 @@ export interface CompleteMilestoneParams {
   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 {
@@ -114,22 +123,48 @@ export async function handleCompleteMilestone(
     return { error: "verification did not pass — milestone completion blocked. verificationPassed must be explicitly set to true after all verification steps succeed" };
   }
 
-  // ── Verify all slices are complete ───────────────────────────────────────
-  const slices = getMilestoneSlices(params.milestoneId);
-  if (slices.length === 0) {
-    return { error: `no slices found for milestone ${params.milestoneId}` };
-  }
-
-  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`,
@@ -139,6 +174,10 @@ export async function handleCompleteMilestone(
     });
   });
 
+  if (guardError) {
+    return { error: guardError };
+  }
+
   // ── Filesystem operations (outside transaction) ─────────────────────────
   const summaryMd = renderMilestoneSummaryMarkdown(params);
 
@@ -175,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,