hungry-ghost-hive 0.43.2 → 0.45.0

package/src/utils/auto-merge.test.ts

@@ -21,6 +21,11 @@ vi.mock('./paths.js', () => ({
   getHivePaths: vi.fn(() => ({ hiveDir: '/mock/hive' })),
 }));
 
+vi.mock('../connectors/project-management/operations.js', () => ({
+  postLifecycleComment: vi.fn().mockResolvedValue(undefined),
+  syncStatusForStory: vi.fn(),
+}));
+
 import { loadConfig } from '../config/loader.js';
 import { autoMergeApprovedPRs } from './auto-merge.js';
 
@@ -266,6 +271,82 @@ describe('auto-merge functionality', () => {
       expect(mockLoadConfig).toHaveBeenCalledWith('/mock/hive');
     });
 
+    it('should keep PR as queued when auto-merge is pending (PR still open after gh pr merge --auto)', async () => {
+      const pr = createPullRequest(db, {
+        storyId,
+        teamId,
+        branchName: 'feature/auto-merge-pending',
+        githubPrNumber: 456,
+      });
+      updatePullRequest(db, pr.id, { status: 'approved' });
+
+      mockLoadConfig.mockReturnValue({
+        integrations: {
+          autonomy: { level: 'full' },
+          source_control: { provider: 'github' },
+          project_management: { provider: 'none' },
+        },
+      } as any);
+
+      // Mock execSync: first call returns OPEN+MERGEABLE, merge command succeeds,
+      // second call (post-merge check) returns OPEN (auto-merge pending)
+      const mockExecSync = vi.fn();
+      mockExecSync
+        .mockReturnValueOnce(
+          JSON.stringify({ state: 'OPEN', mergeable: 'MERGEABLE', mergeStateStatus: 'CLEAN' })
+        )
+        .mockReturnValueOnce(undefined) // gh pr merge --auto
+        .mockReturnValueOnce(
+          JSON.stringify({ state: 'OPEN', mergeable: 'MERGEABLE', mergeStateStatus: 'BLOCKED' })
+        );
+
+      vi.doMock('child_process', () => ({ execSync: mockExecSync }));
+
+      const dbClient = { db, save: vi.fn(), close: vi.fn(), runMigrations: vi.fn() };
+      const result = await autoMergeApprovedPRs('/mock/root', dbClient);
+
+      // Should return 0 because the PR was not actually merged yet
+      expect(result).toBe(0);
+      // PR should remain 'queued' (not rolled back to 'approved' or advanced to 'merged')
+      expect(getPullRequestById(db, pr.id)?.status).toBe('queued');
+    });
+
+    it('should reset stale branch PR to approved after updating behind branch', async () => {
+      const pr = createPullRequest(db, {
+        storyId,
+        teamId,
+        branchName: 'feature/stale-branch',
+        githubPrNumber: 789,
+      });
+      updatePullRequest(db, pr.id, { status: 'approved' });
+
+      mockLoadConfig.mockReturnValue({
+        integrations: {
+          autonomy: { level: 'full' },
+          source_control: { provider: 'github' },
+          project_management: { provider: 'none' },
+        },
+      } as any);
+
+      // Mock execSync: PR state shows BEHIND, then gh pr update-branch succeeds
+      const mockExecSync = vi.fn();
+      mockExecSync
+        .mockReturnValueOnce(
+          JSON.stringify({ state: 'OPEN', mergeable: 'MERGEABLE', mergeStateStatus: 'BEHIND' })
+        )
+        .mockReturnValueOnce(undefined); // gh pr update-branch
+
+      vi.doMock('child_process', () => ({ execSync: mockExecSync }));
+
+      const dbClient = { db, save: vi.fn(), close: vi.fn(), runMigrations: vi.fn() };
+      const result = await autoMergeApprovedPRs('/mock/root', dbClient);
+
+      // Should return 0 because no merge happened yet
+      expect(result).toBe(0);
+      // PR should be reset to 'approved' to be retried on next cycle
+      expect(getPullRequestById(db, pr.id)?.status).toBe('approved');
+    });
+
     it('should skip approved PRs marked for manual merge', async () => {
       const pr = createPullRequest(db, {
         storyId,

package/src/utils/auto-merge.ts

@@ -29,6 +29,7 @@ const PR_MERGE_TIMEOUT_MS = 60000;
 interface GitHubPRState {
   state: string;
   mergeable: string;
+  mergeStateStatus: string;
 }
 
 /**
@@ -149,6 +150,8 @@ export async function autoMergeApprovedPRs(
     claimed: ClaimedPR;
     outcome:
       | { type: 'merged' }
+      | { type: 'auto_merge_pending' }
+      | { type: 'branch_updated' }
       | { type: 'already_closed'; prState: GitHubPRState }
       | { type: 'conflicts' }
       | { type: 'unknown_state' }
@@ -163,10 +166,9 @@ export async function autoMergeApprovedPRs(
     try {
       // Check PR state
       let prState: GitHubPRState;
-      let mergeableStatus: boolean;
       try {
         const prViewOutput = execSync(
-          `gh pr view ${pr.github_pr_number} --json state,mergeable${repoFlag}`,
+          `gh pr view ${pr.github_pr_number} --json state,mergeable,mergeStateStatus${repoFlag}`,
           {
             stdio: 'pipe',
             cwd: repoCwd,
@@ -175,7 +177,6 @@ export async function autoMergeApprovedPRs(
           }
         );
         prState = JSON.parse(prViewOutput);
-        mergeableStatus = prState.mergeable === 'MERGEABLE';
       } catch {
         results.push({ claimed, outcome: { type: 'unknown_state' } });
         continue;
@@ -186,7 +187,22 @@ export async function autoMergeApprovedPRs(
         continue;
       }
 
-      if (!mergeableStatus) {
+      // Update stale branches that are behind the base branch
+      if (prState.mergeStateStatus === 'BEHIND') {
+        try {
+          execSync(`gh pr update-branch ${pr.github_pr_number}${repoFlag}`, {
+            stdio: 'pipe',
+            cwd: repoCwd,
+            timeout: PR_MERGE_TIMEOUT_MS,
+          });
+          results.push({ claimed, outcome: { type: 'branch_updated' } });
+        } catch {
+          results.push({ claimed, outcome: { type: 'unknown_state' } });
+        }
+        continue;
+      }
+
+      if (prState.mergeable !== 'MERGEABLE') {
         results.push({ claimed, outcome: { type: 'conflicts' } });
         continue;
       }
@@ -198,7 +214,32 @@ export async function autoMergeApprovedPRs(
           cwd: repoCwd,
           timeout: PR_MERGE_TIMEOUT_MS,
         });
-        results.push({ claimed, outcome: { type: 'merged' } });
+
+        // Verify actual merge state: --auto may queue the merge rather than merge immediately
+        let postMergeState: GitHubPRState;
+        try {
+          const postMergeOutput = execSync(
+            `gh pr view ${pr.github_pr_number} --json state,mergeable,mergeStateStatus${repoFlag}`,
+            {
+              stdio: 'pipe',
+              cwd: repoCwd,
+              encoding: 'utf-8',
+              timeout: PR_STATE_CHECK_TIMEOUT_MS,
+            }
+          );
+          postMergeState = JSON.parse(postMergeOutput);
+        } catch {
+          // If we can't re-check, assume it merged (command succeeded)
+          results.push({ claimed, outcome: { type: 'merged' } });
+          continue;
+        }
+
+        if (postMergeState.state === 'MERGED') {
+          results.push({ claimed, outcome: { type: 'merged' } });
+        } else {
+          // PR is OPEN with auto-merge enabled — GitHub will merge when CI passes
+          results.push({ claimed, outcome: { type: 'auto_merge_pending' } });
+        }
       } catch (mergeErr) {
         results.push({
           claimed,
@@ -340,6 +381,38 @@ export async function autoMergeApprovedPRs(
           break;
         }
 
+        case 'auto_merge_pending': {
+          createLog(phaseDb.db, {
+            agentId: 'manager',
+            storyId: pr.story_id || undefined,
+            eventType: 'PR_MERGE_SKIPPED',
+            status: 'info',
+            message: `PR #${pr.github_pr_number} is queued for auto-merge, waiting for CI checks to complete`,
+            metadata: { pr_id: pr.id },
+          });
+          break;
+        }
+
+        case 'branch_updated': {
+          // Reset to 'approved' so the PR is retried on the next cycle once CI passes
+          await withTransaction(
+            phaseDb.db,
+            () => {
+              updatePullRequest(phaseDb.db, pr.id, { status: 'approved' });
+              createLog(phaseDb.db, {
+                agentId: 'manager',
+                storyId: pr.story_id || undefined,
+                eventType: 'PR_MERGE_SKIPPED',
+                status: 'info',
+                message: `Updated stale branch for PR #${pr.github_pr_number} (was behind base branch), will retry merge`,
+                metadata: { pr_id: pr.id },
+              });
+            },
+            () => phaseDb.save()
+          );
+          break;
+        }
+
         case 'merge_failed': {
           await withTransaction(
             phaseDb.db,

package/src/utils/instance.test.ts

@@ -0,0 +1,129 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  buildInstanceSessionName,
+  getInstanceId,
+  getInstancePrefix,
+  getManagerLockPath,
+  getManagerSessionName,
+  getTechLeadSessionName,
+} from './instance.js';
+
+describe('instance', () => {
+  let testHiveDir: string;
+
+  beforeEach(() => {
+    testHiveDir = join(tmpdir(), `hive-test-instance-${Date.now()}`);
+    mkdirSync(testHiveDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testHiveDir, { recursive: true, force: true });
+  });
+
+  describe('getInstanceId', () => {
+    it('should return null if hive directory does not exist', () => {
+      const result = getInstanceId('/nonexistent/path/.hive');
+      expect(result).toBeNull();
+    });
+
+    it('should create and persist an instance ID', () => {
+      const id = getInstanceId(testHiveDir);
+      expect(id).toBeTruthy();
+      expect(typeof id).toBe('string');
+      expect(id!.length).toBe(6);
+
+      // Should be persisted
+      const fileContent = readFileSync(join(testHiveDir, 'instance.id'), 'utf-8').trim();
+      expect(fileContent).toBe(id);
+    });
+
+    it('should return the same ID on subsequent calls', () => {
+      const id1 = getInstanceId(testHiveDir);
+      const id2 = getInstanceId(testHiveDir);
+      expect(id1).toBe(id2);
+    });
+
+    it('should read existing instance ID from file', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'testid', 'utf-8');
+      const id = getInstanceId(testHiveDir);
+      expect(id).toBe('testid');
+    });
+  });
+
+  describe('getInstancePrefix', () => {
+    it('should return hive-<instanceId> when hive dir exists', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const prefix = getInstancePrefix(testHiveDir);
+      expect(prefix).toBe('hive-abc123');
+    });
+
+    it('should fall back to hive when hive dir does not exist', () => {
+      const prefix = getInstancePrefix('/nonexistent/path/.hive');
+      expect(prefix).toBe('hive');
+    });
+  });
+
+  describe('buildInstanceSessionName', () => {
+    it('should build instance-scoped session name', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const name = buildInstanceSessionName(testHiveDir, 'senior', 'my-team');
+      expect(name).toBe('hive-abc123-senior-my-team');
+    });
+
+    it('should include index when > 1', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const name = buildInstanceSessionName(testHiveDir, 'senior', 'my-team', 3);
+      expect(name).toBe('hive-abc123-senior-my-team-3');
+    });
+
+    it('should omit index when 1', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'abc123', 'utf-8');
+      const name = buildInstanceSessionName(testHiveDir, 'senior', 'my-team', 1);
+      expect(name).toBe('hive-abc123-senior-my-team');
+    });
+
+    it('should fall back to old format when no hive dir', () => {
+      const name = buildInstanceSessionName('/nonexistent', 'senior', 'my-team');
+      expect(name).toBe('hive-senior-my-team');
+    });
+  });
+
+  describe('getTechLeadSessionName', () => {
+    it('should return instance-scoped tech lead session name', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'xyz789', 'utf-8');
+      const name = getTechLeadSessionName(testHiveDir);
+      expect(name).toBe('hive-xyz789-tech-lead');
+    });
+
+    it('should fall back to hive-tech-lead when no instance', () => {
+      const name = getTechLeadSessionName('/nonexistent');
+      expect(name).toBe('hive-tech-lead');
+    });
+  });
+
+  describe('getManagerSessionName', () => {
+    it('should return instance-scoped manager session name', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'xyz789', 'utf-8');
+      const name = getManagerSessionName(testHiveDir);
+      expect(name).toBe('hive-xyz789-manager');
+    });
+  });
+
+  describe('getManagerLockPath', () => {
+    it('should return instance-scoped lock path', () => {
+      writeFileSync(join(testHiveDir, 'instance.id'), 'xyz789', 'utf-8');
+      const lockPath = getManagerLockPath(testHiveDir);
+      expect(lockPath).toBe(join(testHiveDir, 'manager-xyz789.lock'));
+    });
+
+    it('should fall back to default lock path when no instance', () => {
+      const lockPath = getManagerLockPath('/nonexistent');
+      expect(lockPath).toBe(join('/nonexistent', 'manager.lock'));
+    });
+  });
+});

package/src/utils/instance.ts

@@ -0,0 +1,95 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { nanoid } from 'nanoid';
+import { join } from 'path';
+
+const INSTANCE_ID_FILE = 'instance.id';
+
+/**
+ * Get or create the instance ID for a hive workspace.
+ * The ID is stored in .hive/instance.id.
+ * Returns null if the hive directory does not exist.
+ * Only creates the file if the .hive directory already exists
+ * (i.e., this is a real workspace, not a test environment).
+ */
+export function getInstanceId(hiveDir: string): string | null {
+  if (!existsSync(hiveDir)) {
+    return null;
+  }
+
+  const instancePath = join(hiveDir, INSTANCE_ID_FILE);
+
+  if (existsSync(instancePath)) {
+    const id = readFileSync(instancePath, 'utf-8').trim();
+    if (id) return id;
+  }
+
+  // Generate a short unique ID for this workspace instance
+  const id = nanoid(6);
+  try {
+    writeFileSync(instancePath, id, 'utf-8');
+  } catch {
+    // If write fails (e.g., read-only filesystem), use in-memory ID
+  }
+  return id;
+}
+
+/**
+ * Get the instance-scoped tmux session prefix.
+ * Falls back to 'hive' if no instance ID is available.
+ */
+export function getInstancePrefix(hiveDir: string): string {
+  const instanceId = getInstanceId(hiveDir);
+  if (instanceId) {
+    return `hive-${instanceId}`;
+  }
+  return 'hive';
+}
+
+/**
+ * Build an instance-scoped session name.
+ * Pattern: hive-<instanceId>-<agentType>[-<teamName>][-<index>]
+ * Falls back to hive-<agentType>[-<teamName>][-<index>] if no instance ID.
+ */
+export function buildInstanceSessionName(
+  hiveDir: string,
+  agentType: string,
+  teamName?: string,
+  index?: number
+): string {
+  const prefix = getInstancePrefix(hiveDir);
+  let name = `${prefix}-${agentType}`;
+  if (teamName) {
+    name += `-${teamName}`;
+  }
+  if (index !== undefined && index > 1) {
+    name += `-${index}`;
+  }
+  return name;
+}
+
+/**
+ * Build the instance-scoped tech lead session name.
+ */
+export function getTechLeadSessionName(hiveDir: string): string {
+  return buildInstanceSessionName(hiveDir, 'tech-lead');
+}
+
+/**
+ * Build the instance-scoped manager session name.
+ */
+export function getManagerSessionName(hiveDir: string): string {
+  return buildInstanceSessionName(hiveDir, 'manager');
+}
+
+/**
+ * Build the instance-scoped manager lock path.
+ */
+export function getManagerLockPath(hiveDir: string): string {
+  const instanceId = getInstanceId(hiveDir);
+  if (instanceId) {
+    return join(hiveDir, `manager-${instanceId}.lock`);
+  }
+  return join(hiveDir, 'manager.lock');
+}

package/src/utils/paths.test.ts

@@ -102,6 +102,7 @@ describe('paths utility', () => {
         agentsDir: join(rootDir, '.hive', 'agents'),
         logsDir: join(rootDir, '.hive', 'logs'),
         reposDir: join(rootDir, 'repos'),
+        storiesDir: join(rootDir, '.hive', 'stories'),
       });
     });
 
@@ -128,6 +129,7 @@ describe('paths utility', () => {
       expect(result.configPath).toContain(result.hiveDir);
       expect(result.agentsDir).toContain(result.hiveDir);
       expect(result.logsDir).toContain(result.hiveDir);
+      expect(result.storiesDir).toContain(result.hiveDir);
       expect(result.reposDir).not.toContain(result.hiveDir);
     });
 
@@ -154,6 +156,12 @@ describe('paths utility', () => {
 
       expect(result.logsDir).toContain(paths.LOGS_DIR_NAME);
     });
+
+    it('should use STORIES_DIR_NAME constant for stories directory', () => {
+      const result = paths.getHivePaths(rootDir);
+
+      expect(result.storiesDir).toBe(join(rootDir, '.hive', paths.STORIES_DIR_NAME));
+    });
   });
 
   describe('isHiveWorkspace', () => {

package/src/utils/paths.ts

@@ -7,6 +7,7 @@ export const HIVE_DIR_NAME = '.hive';
 export const REPOS_DIR_NAME = 'repos';
 export const AGENTS_DIR_NAME = 'agents';
 export const LOGS_DIR_NAME = 'logs';
+export const STORIES_DIR_NAME = 'stories';
 
 export interface HivePaths {
   root: string;
@@ -16,6 +17,7 @@ export interface HivePaths {
   agentsDir: string;
   logsDir: string;
   reposDir: string;
+  storiesDir: string;
 }
 
 export function findHiveRoot(startDir: string = process.cwd()): string | null {
@@ -43,6 +45,7 @@ export function getHivePaths(rootDir: string): HivePaths {
     agentsDir: join(hiveDir, AGENTS_DIR_NAME),
     logsDir: join(hiveDir, LOGS_DIR_NAME),
     reposDir: join(rootDir, REPOS_DIR_NAME),
+    storiesDir: join(hiveDir, STORIES_DIR_NAME),
   };
 }
 

package/src/utils/story-markdown.test.ts

@@ -0,0 +1,176 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { StoryRow } from '../db/client.js';
+import {
+  deleteStoryMarkdown,
+  generateStoryMarkdown,
+  writeStoryMarkdown,
+} from './story-markdown.js';
+
+const TEST_DIR = join('/tmp', `story-markdown-test-${Date.now()}`);
+
+function makeStory(overrides: Partial<StoryRow> = {}): StoryRow {
+  return {
+    id: 'STORY-TEST01',
+    requirement_id: null,
+    team_id: null,
+    title: 'Test Story',
+    description: 'A test story description.',
+    acceptance_criteria: null,
+    complexity_score: null,
+    story_points: null,
+    status: 'draft',
+    assigned_agent_id: null,
+    branch_name: null,
+    pr_url: null,
+    jira_issue_key: null,
+    jira_issue_id: null,
+    jira_project_key: null,
+    jira_subtask_key: null,
+    jira_subtask_id: null,
+    external_issue_key: null,
+    external_issue_id: null,
+    external_project_key: null,
+    external_subtask_key: null,
+    external_subtask_id: null,
+    external_provider: null,
+    in_sprint: 0,
+    markdown_path: null,
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+describe('generateStoryMarkdown', () => {
+  it('should generate a markdown document with title and description', () => {
+    const story = makeStory();
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('# Test Story');
+    expect(md).toContain('**Story ID:** STORY-TEST01');
+    expect(md).toContain('**Status:** draft');
+    expect(md).toContain('A test story description.');
+  });
+
+  it('should include acceptance criteria as a checklist', () => {
+    const story = makeStory({
+      acceptance_criteria: JSON.stringify(['Criterion A', 'Criterion B']),
+    });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('## Acceptance Criteria');
+    expect(md).toContain('- [ ] Criterion A');
+    expect(md).toContain('- [ ] Criterion B');
+  });
+
+  it('should include optional fields when present', () => {
+    const story = makeStory({
+      team_id: 'TEAM-1',
+      requirement_id: 'REQ-1',
+      assigned_agent_id: 'agent-123',
+      complexity_score: 5,
+      story_points: 5,
+      branch_name: 'feature/STORY-TEST01-test-story',
+      pr_url: 'https://github.com/test/repo/pull/42',
+    });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('**Team:** TEAM-1');
+    expect(md).toContain('**Requirement:** REQ-1');
+    expect(md).toContain('**Assigned Agent:** agent-123');
+    expect(md).toContain('**Complexity:** 5');
+    expect(md).toContain('**Story Points:** 5');
+    expect(md).toContain('**Branch:** feature/STORY-TEST01-test-story');
+    expect(md).toContain('**PR:** https://github.com/test/repo/pull/42');
+  });
+
+  it('should include created and updated timestamps', () => {
+    const story = makeStory();
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('*Created: 2026-01-01T00:00:00.000Z*');
+    expect(md).toContain('*Updated: 2026-01-01T00:00:00.000Z*');
+  });
+
+  it('should handle malformed acceptance_criteria gracefully', () => {
+    const story = makeStory({ acceptance_criteria: 'not-json' });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('not-json');
+  });
+});
+
+describe('writeStoryMarkdown', () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it('should write a markdown file in storiesDir', () => {
+    const story = makeStory();
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+
+    expect(existsSync(filePath)).toBe(true);
+    expect(filePath).toBe(join(TEST_DIR, 'STORY-TEST01.md'));
+  });
+
+  it('should create the directory if it does not exist', () => {
+    const nestedDir = join(TEST_DIR, 'nested', 'stories');
+    const story = makeStory();
+    writeStoryMarkdown(nestedDir, story);
+
+    expect(existsSync(nestedDir)).toBe(true);
+    expect(existsSync(join(nestedDir, 'STORY-TEST01.md'))).toBe(true);
+  });
+
+  it('should write valid markdown content', () => {
+    const story = makeStory({ description: 'My description.' });
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+    const content = readFileSync(filePath, 'utf-8');
+
+    expect(content).toContain('# Test Story');
+    expect(content).toContain('My description.');
+  });
+
+  it('should overwrite existing file on update', () => {
+    const story = makeStory({ title: 'Old Title' });
+    writeStoryMarkdown(TEST_DIR, story);
+
+    const updatedStory = makeStory({ title: 'New Title' });
+    const filePath = writeStoryMarkdown(TEST_DIR, updatedStory);
+    const content = readFileSync(filePath, 'utf-8');
+
+    expect(content).toContain('# New Title');
+    expect(content).not.toContain('# Old Title');
+  });
+});
+
+describe('deleteStoryMarkdown', () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it('should delete the markdown file', () => {
+    const story = makeStory();
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+    expect(existsSync(filePath)).toBe(true);
+
+    deleteStoryMarkdown(TEST_DIR, story.id);
+    expect(existsSync(filePath)).toBe(false);
+  });
+
+  it('should not throw if file does not exist', () => {
+    expect(() => deleteStoryMarkdown(TEST_DIR, 'STORY-NONEXISTENT')).not.toThrow();
+  });
+});