gsd-pi 2.45.0-dev.fdcf73c → 2.46.0-dev.cc9d310

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,

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

@@ -17,12 +17,19 @@ import {
   insertSlice,
   insertTask,
   insertVerificationEvidence,
+  getMilestone,
+  getSlice,
+  getTask,
   _getAdapter,
 } from "../gsd-db.js";
 import { resolveSliceFile, resolveTasksDir, clearPathCache } from "../paths.js";
+import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanCheckboxes } from "../markdown-renderer.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 
 export interface CompleteTaskResult {
   taskId: string;
@@ -131,10 +138,43 @@ export async function handleCompleteTask(
     return { error: "milestoneId is required and must be a non-empty string" };
   }
 
-  // ── DB writes inside a transaction ──────────────────────────────────────
+  // ── Ownership check (opt-in: only enforced when claim file exists) ──────
+  const ownershipErr = checkOwnership(
+    basePath,
+    taskUnitKey(params.milestoneId, params.sliceId, params.taskId),
+    params.actorName,
+  );
+  if (ownershipErr) {
+    return { error: ownershipErr };
+  }
+
+  // ── 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 task 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 = `cannot complete task in a closed slice: ${params.sliceId} (status: ${slice.status})`;
+      return;
+    }
+
+    const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
+    if (existingTask && (existingTask.status === "complete" || existingTask.status === "done")) {
+      guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
+      return;
+    }
+
+    // All guards passed — perform writes
     insertMilestone({ id: params.milestoneId });
     insertSlice({ id: params.sliceId, milestoneId: params.milestoneId });
     insertTask({
@@ -167,6 +207,10 @@ export async function handleCompleteTask(
     }
   });
 
+  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").
@@ -236,6 +280,24 @@ export async function handleCompleteTask(
   clearPathCache();
   clearParseCache();
 
+  // ── Post-mutation hook: projections, manifest, event log ───────────────
+  try {
+    await renderAllProjections(basePath, params.milestoneId);
+    writeManifest(basePath);
+    appendEvent(basePath, {
+      cmd: "complete-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) {
+    process.stderr.write(
+      `gsd: complete-task post-mutation hook warning: ${(hookErr as Error).message}\n`,
+    );
+  }
+
   return {
     taskId: params.taskId,
     sliceId: params.sliceId,

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

@@ -1,6 +1,7 @@
 import { clearParseCache } from "../files.js";
 import {
   transaction,
+  getMilestone,
   insertMilestone,
   insertSlice,
   upsertMilestonePlanning,
@@ -9,6 +10,9 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb } from "../markdown-renderer.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 
 export interface PlanMilestoneSliceInput {
   sliceId: string;
@@ -28,6 +32,10 @@ export interface PlanMilestoneParams {
   title: string;
   status?: string;
   dependsOn?: string[];
+  /** Optional caller-provided identity for audit trail */
+  actorName?: string;
+  /** Optional caller-provided reason this action was triggered */
+  triggerReason?: string;
   vision: string;
   successCriteria: string[];
   keyRisks: Array<{ risk: string; whyItMatters: string }>;
@@ -181,6 +189,25 @@ export async function handlePlanMilestone(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
+  // ── State machine preconditions ─────────────────────────────────────────
+  const existingMilestone = getMilestone(params.milestoneId);
+  if (existingMilestone && (existingMilestone.status === "complete" || existingMilestone.status === "done")) {
+    return { error: `cannot re-plan milestone ${params.milestoneId}: it is already complete` };
+  }
+
+  // Validate depends_on: all dependencies must exist and be complete
+  if (params.dependsOn && params.dependsOn.length > 0) {
+    for (const depId of params.dependsOn) {
+      const dep = getMilestone(depId);
+      if (!dep) {
+        return { error: `depends_on references unknown milestone: ${depId}` };
+      }
+      if (dep.status !== "complete" && dep.status !== "done") {
+        return { error: `depends_on milestone ${depId} is not yet complete (status: ${dep.status})` };
+      }
+    }
+  }
+
   try {
     transaction(() => {
       insertMilestone({
@@ -242,6 +269,24 @@ export async function handlePlanMilestone(
   invalidateStateCache();
   clearParseCache();
 
+  // ── Post-mutation hook: projections, manifest, event log ───────────────
+  try {
+    await renderAllProjections(basePath, params.milestoneId);
+    writeManifest(basePath);
+    appendEvent(basePath, {
+      cmd: "plan-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: plan-milestone post-mutation hook warning: ${(hookErr as Error).message}\n`,
+    );
+  }
+
   return {
     milestoneId: params.milestoneId,
     roadmapPath,