agile-context-engineering 0.3.0 → 0.5.1

package/shared/lib/ace-story.js

@@ -0,0 +1,400 @@
+/**
+ * ACE Story — Story metadata extraction, path computation, and state management.
+ *
+ * Extracted from ace-tools.js monolith. Contains: story param classification,
+ * markdown section extraction, metadata/requirements parsing, wiki reference parsing,
+ * path computation, and story state updates across story/feature/backlog files.
+ *
+ * Usage: const { classifyStoryParam, extractStoryMetadata, updateState } = require('./ace-story');
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  safeReadFile, generateSlug, parseKeyValueArgs, output, error,
+} = require('./ace-core');
+
+// ─── Story Param Classification ──────────────────────────────────────────────
+
+/**
+ * Classify a story parameter as file path, GitHub URL, or issue number.
+ * Returns { type, filePath?, repo?, issueNumber?, reason? }
+ */
+function classifyStoryParam(param) {
+  if (!param) return { type: null, reason: 'No story parameter provided' };
+  const trimmed = param.trim();
+  if (/^https?:\/\/github\.com\//.test(trimmed)) {
+    const match = trimmed.match(/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)/);
+    if (match) return { type: 'github-url', repo: match[1], issueNumber: parseInt(match[2]) };
+    return { type: 'invalid', reason: 'Unrecognized GitHub URL format. Expected: https://github.com/owner/repo/issues/123' };
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return { type: 'issue-number', issueNumber: parseInt(trimmed) };
+  }
+  return { type: 'file', filePath: trimmed };
+}
+
+// ─── Markdown Parsing ────────────────────────────────────────────────────────
+
+/**
+ * Extract a markdown section between a heading and the next heading of equal or higher level.
+ * Returns the section content (without the heading itself), or null if not found.
+ */
+function extractMarkdownSection(content, sectionName, headingLevel) {
+  const prefix = '#'.repeat(headingLevel);
+  const escapedName = sectionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const headingPattern = new RegExp(`^${prefix}\\s+${escapedName}\\s*$`, 'm');
+  const headingMatch = headingPattern.exec(content);
+  if (!headingMatch) return null;
+
+  const startIdx = headingMatch.index + headingMatch[0].length;
+  const rest = content.substring(startIdx);
+
+  const nextHeadingPattern = new RegExp(`^#{1,${headingLevel}}\\s`, 'm');
+  const nextMatch = nextHeadingPattern.exec(rest);
+
+  const sectionContent = nextMatch ? rest.substring(0, nextMatch.index) : rest;
+  return sectionContent.trim() || null;
+}
+
+// ─── Story Metadata ──────────────────────────────────────────────────────────
+
+/**
+ * Parse the story markdown header to extract metadata and parent context.
+ *
+ * Expected format:
+ *   # S3: Display OAuth Provider Buttons
+ *   **Feature**: F3 OAuth2 Login Flow | **Epic**: #45 User Authentication
+ *   **Status**: Refined | **Size**: 3 | **Sprint**: Sprint 2 | **Link**: [#95](url)
+ */
+function extractStoryMetadata(content) {
+  const result = {
+    id: null, title: null, status: null, size: null, sprint: null, link: null,
+    feature: { id: null, title: null },
+    epic: { id: null, title: null },
+  };
+  if (!content) return result;
+
+  // Header: # ID: Title
+  const headerMatch = content.match(/^#\s+([^:\n]+?):\s+(.+)$/m);
+  if (headerMatch) {
+    result.id = headerMatch[1].trim();
+    result.title = headerMatch[2].trim();
+  }
+
+  // Feature/Epic line
+  const featureEpicMatch = content.match(/\*\*Feature\*\*:\s*(.+?)\s*\|\s*\*\*Epic\*\*:\s*(.+)$/m);
+  if (featureEpicMatch) {
+    const featureStr = featureEpicMatch[1].trim();
+    const epicStr = featureEpicMatch[2].trim();
+    const featureParts = featureStr.match(/^(\S+)\s+(.+)$/);
+    if (featureParts) {
+      result.feature.id = featureParts[1];
+      result.feature.title = featureParts[2];
+    } else {
+      result.feature.title = featureStr;
+    }
+    const epicParts = epicStr.match(/^(\S+)\s+(.+)$/);
+    if (epicParts) {
+      result.epic.id = epicParts[1];
+      result.epic.title = epicParts[2];
+    } else {
+      result.epic.title = epicStr;
+    }
+  }
+
+  const statusMatch = content.match(/\*\*Status\*\*:\s*([^|*]+)/);
+  if (statusMatch) result.status = statusMatch[1].trim();
+
+  const sizeMatch = content.match(/\*\*Size\*\*:\s*([^|*]+)/);
+  if (sizeMatch) result.size = sizeMatch[1].trim();
+
+  const sprintMatch = content.match(/\*\*Sprint\*\*:\s*([^|*]+)/);
+  if (sprintMatch) result.sprint = sprintMatch[1].trim();
+
+  const linkMatch = content.match(/\*\*Link\*\*:\s*([^|*\n]+)/);
+  if (linkMatch) result.link = linkMatch[1].trim();
+
+  return result;
+}
+
+/**
+ * Extract GitHub issue number from a Link field value.
+ * Handles formats: "[#187](url)", "#187", "187"
+ */
+function extractIssueNumber(linkStr) {
+  if (!linkStr) return null;
+  const match = linkStr.match(/#(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Extract GitHub issue number from a file's **Link** header field.
+ */
+function extractIssueNumberFromFile(cwd, filePath) {
+  if (!filePath) return null;
+  const resolved = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const content = safeReadFile(resolved);
+  if (!content) return null;
+  const linkMatch = content.match(/\*\*Link\*\*:\s*([^|*\n]+)/);
+  if (!linkMatch) return null;
+  return extractIssueNumber(linkMatch[1].trim());
+}
+
+// ─── Story Requirements ──────────────────────────────────────────────────────
+
+/**
+ * Extract story requirements: user story statement, description, and AC scenario count.
+ */
+function extractStoryRequirements(content) {
+  const result = { user_story: null, description: null, acceptance_criteria_count: 0 };
+  if (!content) return result;
+
+  const userStorySection = extractMarkdownSection(content, 'User Story', 2);
+  if (userStorySection) {
+    result.user_story = userStorySection.replace(/^>\s?/gm, '').trim();
+  }
+
+  const descSection = extractMarkdownSection(content, 'Description', 2);
+  if (descSection) {
+    result.description = descSection.trim();
+  }
+
+  const scenarioMatches = content.match(/^###\s+Scenario:/gm);
+  result.acceptance_criteria_count = scenarioMatches ? scenarioMatches.length : 0;
+
+  return result;
+}
+
+/**
+ * Parse the "## Relevant Wiki" section to extract structured wiki file references.
+ */
+function extractWikiReferences(content) {
+  const result = { system_wide: [], subsystem_docs: [], total_count: 0 };
+  if (!content) return result;
+
+  const wikiSection = extractMarkdownSection(content, 'Relevant Wiki', 2);
+  if (!wikiSection) return result;
+
+  const linePattern = /^-\s+`([^`]+)`\s*[—–-]\s*(.+)$/gm;
+  let match;
+  while ((match = linePattern.exec(wikiSection)) !== null) {
+    const filePath = match[1].trim();
+    const reason = match[2].trim();
+
+    if (filePath.includes('/system-wide/')) {
+      result.system_wide.push(filePath);
+    } else {
+      let category = 'other';
+      if (filePath.includes('/systems/')) category = 'systems';
+      else if (filePath.includes('/patterns/')) category = 'patterns';
+      else if (filePath.includes('/cross-cutting/')) category = 'cross-cutting';
+      else if (filePath.includes('/guides/')) category = 'guides';
+      else if (filePath.includes('/decisions/')) category = 'decisions';
+      else if (filePath.includes('/architecture')) category = 'architecture';
+
+      result.subsystem_docs.push({ path: filePath, category, reason });
+    }
+  }
+
+  result.total_count = result.system_wide.length + result.subsystem_docs.length;
+  return result;
+}
+
+// ─── Path Computation ────────────────────────────────────────────────────────
+
+/**
+ * Compute all story-related paths and slugs from parent context.
+ */
+function computeStoryPaths(epicId, epicTitle, featureId, featureTitle, storyId, storyTitle) {
+  const epicSlug = generateSlug(`${epicId}-${epicTitle}`) || 'unknown-epic';
+  const featureSlug = generateSlug(`${featureId}-${featureTitle}`) || 'unknown-feature';
+  const storySlug = generateSlug(`${storyId}-${storyTitle}`) || 'unknown-story';
+
+  const storyDir = `.ace/artifacts/product/${epicSlug}/${featureSlug}/${storySlug}`;
+  const featureDir = `.ace/artifacts/product/${epicSlug}/${featureSlug}`;
+
+  return {
+    epic_slug: epicSlug,
+    feature_slug: featureSlug,
+    story_slug: storySlug,
+    story_dir: storyDir,
+    story_file: `${storyDir}/${storySlug}.md`,
+    external_analysis_file: `${storyDir}/external-analysis.md`,
+    integration_analysis_file: `${storyDir}/integration-analysis.md`,
+    feature_dir: featureDir,
+    feature_file: `${featureDir}/${featureSlug}.md`,
+  };
+}
+
+// ─── Story State Management ──────────────────────────────────────────────────
+
+/**
+ * Update story status across story file, feature file, and product backlog.
+ * Handles: story header update, feature index table update, backlog table update,
+ * and auto-promotes feature to Done when all stories are Done.
+ *
+ * Called via: node script.js update-state story=<path> status=<Refined|InProgress|Done|DevReady>
+ */
+function updateState(cwd, raw, extraArgs) {
+  const params = parseKeyValueArgs(extraArgs);
+  const storyParam = params.story;
+  const newStatus = params.status;
+
+  if (!storyParam) {
+    error('update-state requires: story=<path>');
+  }
+  if (!newStatus || !['Done', 'DevReady', 'Refined', 'InProgress', 'In Progress'].includes(newStatus)) {
+    error('update-state requires: status=Done|DevReady|Refined|InProgress');
+  }
+
+  const displayStatus = newStatus === 'InProgress' ? 'In Progress' : newStatus;
+
+  const result = {
+    story_updated: false,
+    feature_updated: false,
+    backlog_updated: false,
+    feature_status_changed: false,
+    new_status: displayStatus,
+    errors: [],
+  };
+
+  // Resolve story file path
+  const classified = classifyStoryParam(storyParam);
+  if (classified.type !== 'file' || !classified.filePath) {
+    result.errors.push('update-state currently only supports file paths');
+    output(result, raw);
+    return;
+  }
+
+  const storyFilePath = path.isAbsolute(classified.filePath)
+    ? classified.filePath
+    : path.join(cwd, classified.filePath);
+
+  // 1. Update story file header
+  const storyContent = safeReadFile(storyFilePath);
+  if (!storyContent) {
+    result.errors.push(`Could not read story file: ${classified.filePath}`);
+    output(result, raw);
+    return;
+  }
+
+  const updatedStory = storyContent.replace(
+    /(\*\*Status\*\*:\s*)([^|*\n]+)/,
+    `$1${displayStatus}`
+  );
+  if (updatedStory !== storyContent) {
+    try {
+      fs.writeFileSync(storyFilePath, updatedStory, 'utf-8');
+      result.story_updated = true;
+    } catch (e) {
+      result.errors.push(`Failed to write story file: ${e.message}`);
+    }
+  }
+
+  const metadata = extractStoryMetadata(storyContent);
+  const storyId = metadata.id;
+
+  // 2. Update feature file story index
+  const storyDir = path.dirname(storyFilePath);
+  const featureDir = path.dirname(storyDir);
+  const featureSlug = path.basename(featureDir);
+  const featureFilePath = path.join(featureDir, `${featureSlug}.md`);
+
+  const featureContent = safeReadFile(featureFilePath);
+  if (featureContent && storyId) {
+    const storyIdEscaped = storyId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const tableRowPattern = new RegExp(
+      `(\\|\\s*${storyIdEscaped}\\s*\\|[^|]*\\|[^|]*\\|\\s*)([^|]*)(\\s*\\|)`,
+      'm'
+    );
+    const updatedFeature = featureContent.replace(tableRowPattern, `$1${displayStatus}$3`);
+
+    if (updatedFeature !== featureContent) {
+      try {
+        fs.writeFileSync(featureFilePath, updatedFeature, 'utf-8');
+        result.feature_updated = true;
+      } catch (e) {
+        result.errors.push(`Failed to write feature file: ${e.message}`);
+      }
+    }
+
+    // Check if all stories in the feature are Done
+    if (displayStatus === 'Done') {
+      const updatedFeatureContent = safeReadFile(featureFilePath) || updatedFeature;
+      const statusPattern = /\|\s*(?:S\d+|#\d+)\s*\|[^|]*\|[^|]*\|\s*([^|]*)\s*\|/gm;
+      let allDone = true;
+      let match;
+      let storyCount = 0;
+      while ((match = statusPattern.exec(updatedFeatureContent)) !== null) {
+        storyCount++;
+        const status = match[1].trim();
+        if (status !== 'Done') {
+          allDone = false;
+        }
+      }
+
+      if (allDone && storyCount > 0) {
+        const featureWithDoneStatus = updatedFeatureContent.replace(
+          /(\*\*Status\*\*:\s*)([^|*\n]+)/,
+          '$1Done'
+        );
+        if (featureWithDoneStatus !== updatedFeatureContent) {
+          try {
+            fs.writeFileSync(featureFilePath, featureWithDoneStatus, 'utf-8');
+            result.feature_status_changed = true;
+          } catch (e) {
+            result.errors.push(`Failed to update feature status: ${e.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  // 3. Update product backlog
+  const backlogPath = path.join(cwd, '.ace', 'artifacts', 'product', 'product-backlog.md');
+  const backlogContent = safeReadFile(backlogPath);
+  if (backlogContent && storyId) {
+    let updatedBacklog = backlogContent;
+
+    const storyIdEscaped = storyId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const backlogStoryPattern = new RegExp(
+      `(\\|\\s*${storyIdEscaped}\\s*\\|[^|]*\\|[^|]*\\|\\s*)([^|]*)(\\s*\\|)`,
+      'm'
+    );
+    updatedBacklog = updatedBacklog.replace(backlogStoryPattern, `$1${displayStatus}$3`);
+
+    if (result.feature_status_changed && metadata.feature.id) {
+      const featureIdEscaped = metadata.feature.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const backlogFeaturePattern = new RegExp(
+        `(\\|\\s*${featureIdEscaped}\\s*\\|[^|]*\\|[^|]*\\|\\s*)([^|]*)(\\s*\\|)`,
+        'm'
+      );
+      updatedBacklog = updatedBacklog.replace(backlogFeaturePattern, `$1Done$3`);
+    }
+
+    if (updatedBacklog !== backlogContent) {
+      try {
+        fs.writeFileSync(backlogPath, updatedBacklog, 'utf-8');
+        result.backlog_updated = true;
+      } catch (e) {
+        result.errors.push(`Failed to write product backlog: ${e.message}`);
+      }
+    }
+  }
+
+  if (result.errors.length === 0) delete result.errors;
+  output(result, raw);
+}
+
+module.exports = {
+  classifyStoryParam,
+  extractMarkdownSection,
+  extractStoryMetadata,
+  extractIssueNumber,
+  extractIssueNumberFromFile,
+  extractStoryRequirements,
+  extractWikiReferences,
+  computeStoryPaths,
+  updateState,
+};

package/shared/lib/ace-story.test.js

@@ -0,0 +1,250 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+
+const {
+  classifyStoryParam, extractMarkdownSection, extractStoryMetadata,
+  extractIssueNumber, extractStoryRequirements, extractWikiReferences,
+  computeStoryPaths,
+} = require('./ace-story');
+
+const SAMPLE_STORY = `# S3: Display OAuth Provider Buttons
+
+**Feature**: F3 OAuth2 Login Flow | **Epic**: #45 User Authentication
+**Status**: Refined | **Size**: 3 | **Sprint**: Sprint 2 | **Link**: [#95](https://github.com/owner/repo/issues/95)
+
+## User Story
+
+> As a returning customer,
+> I want to click a Google or GitHub login button,
+> so that I can authenticate without remembering a site-specific password.
+
+## Description
+
+This story adds OAuth provider buttons to the login page. It builds on the
+auth service foundation (S1) and enables the token exchange flow (S4).
+
+## Acceptance Criteria
+
+### Scenario: Successful Google login
+
+**Given** the user is on the login page and has a valid Google account
+**When** they click the "Sign in with Google" button and complete Google's OAuth flow
+**Then** they are redirected to the dashboard and see their Google profile name
+
+### Scenario: Provider unavailable
+
+**Given** the user is on the login page and the Google OAuth service is unreachable
+**When** they click the "Sign in with Google" button
+**Then** they see an error message "Login service temporarily unavailable. Please try again."
+
+### Scenario: GitHub login button displayed
+
+**Given** the user navigates to the login page
+**When** the page loads
+**Then** they see a "Sign in with GitHub" button alongside the Google button
+
+## Out of Scope
+
+- Token refresh logic (handled by S4)
+- Account linking (future feature)
+
+## Definition of Done
+
+- [ ] All acceptance criteria scenarios pass
+- [ ] Code reviewed and approved
+
+## Relevant Wiki
+
+### System-Wide
+
+- \`.docs/wiki/system-wide/system-structure.md\` — Mandatory system-wide context
+- \`.docs/wiki/system-wide/coding-standards.md\` — Mandatory system-wide context
+
+### Systems
+- \`.docs/wiki/subsystems/auth/systems/oauth-provider.md\` — Implements the provider abstraction
+
+### Patterns
+- \`.docs/wiki/subsystems/auth/patterns/strategy-pattern.md\` — Each OAuth provider is a strategy
+`;
+
+// ─── classifyStoryParam ──────────────────────────────────────────────────────
+
+describe('classifyStoryParam', () => {
+  it('classifies file path', () => {
+    const result = classifyStoryParam('.ace/artifacts/product/e1/f1/s1/s1.md');
+    assert.strictEqual(result.type, 'file');
+    assert.ok(result.filePath.includes('s1.md'));
+  });
+
+  it('classifies GitHub URL', () => {
+    const result = classifyStoryParam('https://github.com/owner/repo/issues/123');
+    assert.strictEqual(result.type, 'github-url');
+    assert.strictEqual(result.repo, 'owner/repo');
+    assert.strictEqual(result.issueNumber, 123);
+  });
+
+  it('classifies issue number', () => {
+    const result = classifyStoryParam('42');
+    assert.strictEqual(result.type, 'issue-number');
+    assert.strictEqual(result.issueNumber, 42);
+  });
+
+  it('returns null type for empty input', () => {
+    assert.strictEqual(classifyStoryParam(null).type, null);
+    assert.strictEqual(classifyStoryParam('').type, null);
+    assert.strictEqual(classifyStoryParam(undefined).type, null);
+  });
+
+  it('returns invalid for unrecognized GitHub URL', () => {
+    const result = classifyStoryParam('https://github.com/owner/repo/pulls/5');
+    assert.strictEqual(result.type, 'invalid');
+  });
+});
+
+// ─── extractMarkdownSection ──────────────────────────────────────────────────
+
+describe('extractMarkdownSection', () => {
+  it('extracts section content', () => {
+    const result = extractMarkdownSection(SAMPLE_STORY, 'Description', 2);
+    assert.ok(result.includes('OAuth provider buttons'));
+  });
+
+  it('returns null for non-existent section', () => {
+    assert.strictEqual(extractMarkdownSection(SAMPLE_STORY, 'Nonexistent', 2), null);
+  });
+
+  it('stops at next heading of same level', () => {
+    const result = extractMarkdownSection(SAMPLE_STORY, 'Out of Scope', 2);
+    assert.ok(result.includes('Token refresh'));
+    assert.ok(!result.includes('Definition of Done'));
+  });
+});
+
+// ─── extractStoryMetadata ────────────────────────────────────────────────────
+
+describe('extractStoryMetadata', () => {
+  it('extracts full metadata from sample story', () => {
+    const meta = extractStoryMetadata(SAMPLE_STORY);
+    assert.strictEqual(meta.id, 'S3');
+    assert.strictEqual(meta.title, 'Display OAuth Provider Buttons');
+    assert.strictEqual(meta.status, 'Refined');
+    assert.strictEqual(meta.size, '3');
+    assert.strictEqual(meta.sprint, 'Sprint 2');
+    assert.strictEqual(meta.feature.id, 'F3');
+    assert.strictEqual(meta.feature.title, 'OAuth2 Login Flow');
+    assert.strictEqual(meta.epic.id, '#45');
+    assert.strictEqual(meta.epic.title, 'User Authentication');
+  });
+
+  it('returns nulls for empty content', () => {
+    const meta = extractStoryMetadata(null);
+    assert.strictEqual(meta.id, null);
+    assert.strictEqual(meta.title, null);
+    assert.strictEqual(meta.feature.id, null);
+  });
+
+  it('extracts link field', () => {
+    const meta = extractStoryMetadata(SAMPLE_STORY);
+    assert.ok(meta.link.includes('#95'));
+  });
+});
+
+// ─── extractIssueNumber ──────────────────────────────────────────────────────
+
+describe('extractIssueNumber', () => {
+  it('extracts from markdown link format', () => {
+    assert.strictEqual(extractIssueNumber('[#187](https://github.com/owner/repo/issues/187)'), 187);
+  });
+
+  it('extracts from hash format', () => {
+    assert.strictEqual(extractIssueNumber('#95'), 95);
+  });
+
+  it('returns null for null input', () => {
+    assert.strictEqual(extractIssueNumber(null), null);
+  });
+
+  it('returns null for no match', () => {
+    assert.strictEqual(extractIssueNumber('no number here'), null);
+  });
+});
+
+// ─── extractStoryRequirements ────────────────────────────────────────────────
+
+describe('extractStoryRequirements', () => {
+  it('extracts user story, description, and AC count', () => {
+    const req = extractStoryRequirements(SAMPLE_STORY);
+    assert.ok(req.user_story.includes('returning customer'));
+    assert.ok(req.description.includes('OAuth provider buttons'));
+    assert.strictEqual(req.acceptance_criteria_count, 3);
+  });
+
+  it('strips blockquote prefix from user story', () => {
+    const req = extractStoryRequirements(SAMPLE_STORY);
+    assert.ok(!req.user_story.startsWith('>'));
+  });
+
+  it('returns zeros/nulls for empty content', () => {
+    const req = extractStoryRequirements(null);
+    assert.strictEqual(req.user_story, null);
+    assert.strictEqual(req.description, null);
+    assert.strictEqual(req.acceptance_criteria_count, 0);
+  });
+});
+
+// ─── extractWikiReferences ───────────────────────────────────────────────────
+
+describe('extractWikiReferences', () => {
+  it('extracts system-wide references', () => {
+    const refs = extractWikiReferences(SAMPLE_STORY);
+    assert.strictEqual(refs.system_wide.length, 2);
+    assert.ok(refs.system_wide.includes('.docs/wiki/system-wide/system-structure.md'));
+  });
+
+  it('extracts subsystem docs with categories', () => {
+    const refs = extractWikiReferences(SAMPLE_STORY);
+    assert.strictEqual(refs.subsystem_docs.length, 2);
+
+    const oauthDoc = refs.subsystem_docs.find(d => d.path.includes('oauth-provider'));
+    assert.ok(oauthDoc);
+    assert.strictEqual(oauthDoc.category, 'systems');
+
+    const strategyDoc = refs.subsystem_docs.find(d => d.path.includes('strategy-pattern'));
+    assert.ok(strategyDoc);
+    assert.strictEqual(strategyDoc.category, 'patterns');
+  });
+
+  it('computes total count', () => {
+    const refs = extractWikiReferences(SAMPLE_STORY);
+    assert.strictEqual(refs.total_count, 4);
+  });
+
+  it('returns empty for content without wiki section', () => {
+    const refs = extractWikiReferences('# No wiki here');
+    assert.strictEqual(refs.total_count, 0);
+    assert.deepStrictEqual(refs.system_wide, []);
+  });
+});
+
+// ─── computeStoryPaths ───────────────────────────────────────────────────────
+
+describe('computeStoryPaths', () => {
+  it('generates correct slugs and paths', () => {
+    const paths = computeStoryPaths('E1', 'Platform', 'F3', 'OAuth Login', 'S1', 'Add Button');
+    assert.strictEqual(paths.epic_slug, 'e1-platform');
+    assert.strictEqual(paths.feature_slug, 'f3-oauth-login');
+    assert.strictEqual(paths.story_slug, 's1-add-button');
+    assert.strictEqual(paths.story_dir, '.ace/artifacts/product/e1-platform/f3-oauth-login/s1-add-button');
+    assert.strictEqual(paths.story_file, '.ace/artifacts/product/e1-platform/f3-oauth-login/s1-add-button/s1-add-button.md');
+    assert.ok(paths.external_analysis_file.endsWith('external-analysis.md'));
+    assert.ok(paths.integration_analysis_file.endsWith('integration-analysis.md'));
+    assert.ok(paths.feature_file.endsWith('f3-oauth-login.md'));
+  });
+
+  it('handles missing titles with fallback slugs', () => {
+    const paths = computeStoryPaths('', '', '', '', '', '');
+    assert.strictEqual(paths.epic_slug, 'unknown-epic');
+    assert.strictEqual(paths.feature_slug, 'unknown-feature');
+    assert.strictEqual(paths.story_slug, 'unknown-story');
+  });
+});