@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/scripts/sprint/check-story.sh

@@ -0,0 +1,164 @@
+#!/bin/bash
+# Check if a story or epic exists and is available for work
+# Usage: check-story.sh <id|next>
+#
+# Arguments:
+#   <story-id>  - Check specific story availability
+#   <epic-id>   - Get first available story in epic
+#   next        - Get highest-priority available story across all epics
+#
+# Returns JSON with story/epic details and availability
+
+set -euo pipefail
+
+ID="${1:-}"
+
+if [[ -z "$ID" ]]; then
+  echo '{"type": "error", "message": "No ID provided"}'
+  exit 1
+fi
+
+# PROJECT_ROOT should be set by run.sh
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+if [[ ! -f "$SPRINT_FILE" ]]; then
+  echo '{"type": "error", "message": "Sprint file not found"}'
+  exit 1
+fi
+
+# Handle "next" argument - find highest priority available story
+if [[ "$ID" == "next" ]]; then
+  # Get all available stories (backlog or ready), sort by priority, take first
+  NEXT_STORY=$(yq -o json "[.epics[].stories[] | select(.status == \"backlog\" or .status == \"ready\" or .status == null)] | sort_by(.priority) | .[0]" "$SPRINT_FILE" 2>/dev/null || echo "null")
+
+  if [[ "$NEXT_STORY" != "null" && -n "$NEXT_STORY" ]]; then
+    STORY_ID=$(echo "$NEXT_STORY" | yq -r '.id')
+    STORY_TITLE=$(echo "$NEXT_STORY" | yq -r '.title')
+    STORY_POINTS=$(echo "$NEXT_STORY" | yq -r '.points // 0')
+    STORY_PRIORITY=$(echo "$NEXT_STORY" | yq -r '.priority // "P2"')
+    STORY_WORKFLOW=$(echo "$NEXT_STORY" | yq -r '.workflow // "tdd"')
+    STORY_REPOS=$(echo "$NEXT_STORY" | yq -r '.repos // "pennyfarthing"')
+    STORY_AC=$(echo "$NEXT_STORY" | yq -o json '.acceptance_criteria // []')
+    EPIC_ID=$(yq -r ".epics[] | select(.stories[].id == \"$STORY_ID\") | .id" "$SPRINT_FILE" 2>/dev/null | head -1)
+
+    cat <<EOF
+{
+  "type": "next",
+  "story": {
+    "id": "$STORY_ID",
+    "title": "$STORY_TITLE",
+    "points": $STORY_POINTS,
+    "priority": "$STORY_PRIORITY",
+    "workflow": "$STORY_WORKFLOW",
+    "repos": "$STORY_REPOS",
+    "epic_id": "$EPIC_ID",
+    "acceptance_criteria": $STORY_AC
+  }
+}
+EOF
+  else
+    echo '{"type": "next", "story": null, "message": "No available stories in backlog"}'
+  fi
+  exit 0
+fi
+
+# Check if it's an epic
+EPIC_DATA=$(yq -o json ".epics[] | select(.id == \"$ID\")" "$SPRINT_FILE" 2>/dev/null || echo "")
+
+if [[ -n "$EPIC_DATA" && "$EPIC_DATA" != "null" ]]; then
+  # It's an epic - get first available story by priority
+  FIRST_STORY=$(yq -o json "[.epics[] | select(.id == \"$ID\") | .stories[] | select(.status == \"backlog\" or .status == \"ready\" or .status == null)] | sort_by(.priority) | .[0]" "$SPRINT_FILE" 2>/dev/null || echo "null")
+
+  EPIC_TITLE=$(echo "$EPIC_DATA" | yq -r '.title // "Unknown"')
+  STORY_COUNT=$(yq "[.epics[] | select(.id == \"$ID\") | .stories[] | select(.status == \"backlog\" or .status == \"ready\" or .status == null)] | length" "$SPRINT_FILE" 2>/dev/null || echo "0")
+
+  if [[ "$FIRST_STORY" != "null" && -n "$FIRST_STORY" ]]; then
+    STORY_ID=$(echo "$FIRST_STORY" | yq -r '.id')
+    STORY_TITLE=$(echo "$FIRST_STORY" | yq -r '.title')
+    STORY_POINTS=$(echo "$FIRST_STORY" | yq -r '.points // 0')
+    STORY_WORKFLOW=$(echo "$FIRST_STORY" | yq -r '.workflow // "tdd"')
+    STORY_REPOS=$(echo "$FIRST_STORY" | yq -r '.repos // "pennyfarthing"')
+    STORY_AC=$(echo "$FIRST_STORY" | yq -o json '.acceptance_criteria // []')
+
+    cat <<EOF
+{
+  "type": "epic",
+  "id": "$ID",
+  "title": "$EPIC_TITLE",
+  "available_stories": $STORY_COUNT,
+  "first_story": {
+    "id": "$STORY_ID",
+    "title": "$STORY_TITLE",
+    "points": $STORY_POINTS,
+    "workflow": "$STORY_WORKFLOW",
+    "repos": "$STORY_REPOS",
+    "acceptance_criteria": $STORY_AC
+  }
+}
+EOF
+  else
+    cat <<EOF
+{
+  "type": "epic",
+  "id": "$ID",
+  "title": "$EPIC_TITLE",
+  "available_stories": 0,
+  "first_story": null,
+  "message": "No available stories in this epic"
+}
+EOF
+  fi
+  exit 0
+fi
+
+# Check if it's a story
+STORY_DATA=$(yq -o json ".epics[].stories[] | select(.id == \"$ID\")" "$SPRINT_FILE" 2>/dev/null || echo "")
+
+if [[ -n "$STORY_DATA" && "$STORY_DATA" != "null" ]]; then
+  STATUS=$(echo "$STORY_DATA" | yq -r '.status // "backlog"')
+  ASSIGNED=$(echo "$STORY_DATA" | yq -r '.assigned_to // ""')
+  TITLE=$(echo "$STORY_DATA" | yq -r '.title // "Unknown"')
+  POINTS=$(echo "$STORY_DATA" | yq -r '.points // 0')
+  WORKFLOW=$(echo "$STORY_DATA" | yq -r '.workflow // "tdd"')
+  EPIC_ID=$(yq -r ".epics[] | select(.stories[].id == \"$ID\") | .id" "$SPRINT_FILE" 2>/dev/null | head -1)
+  REPOS=$(echo "$STORY_DATA" | yq -r '.repos // "pennyfarthing"')
+
+  # Story is available if status is backlog/ready and not assigned
+  if [[ ("$STATUS" == "backlog" || "$STATUS" == "ready") && -z "$ASSIGNED" ]]; then
+    AVAILABLE="true"
+  else
+    AVAILABLE="false"
+  fi
+
+  # Get acceptance criteria as JSON array
+  AC=$(echo "$STORY_DATA" | yq -o json '.acceptance_criteria // []')
+
+  cat <<EOF
+{
+  "type": "story",
+  "id": "$ID",
+  "title": "$TITLE",
+  "points": $POINTS,
+  "workflow": "$WORKFLOW",
+  "status": "$STATUS",
+  "assigned_to": "$ASSIGNED",
+  "epic_id": "$EPIC_ID",
+  "repos": "$REPOS",
+  "available": $AVAILABLE,
+  "acceptance_criteria": $AC
+}
+EOF
+  exit 0
+fi
+
+# Not found
+echo '{"type": "not_found", "id": "'"$ID"'", "message": "Story or epic not found in current sprint"}'
+exit 0

package/pennyfarthing-dist/scripts/sprint/get-epic-field.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Get a field value from an epic in sprint YAML
+# Usage: .pennyfarthing/scripts/core/run.sh sprint/get-epic-field.sh <epic-id> <field>
+#
+# Examples:
+#   .pennyfarthing/scripts/core/run.sh sprint/get-epic-field.sh epic-35 jira
+#   .pennyfarthing/scripts/core/run.sh sprint/get-epic-field.sh epic-35 title
+#   .pennyfarthing/scripts/core/run.sh sprint/get-epic-field.sh 35 jira  # Also works without 'epic-' prefix
+#
+# Common fields: jira, title, description, status
+# Returns the field value or "null" if not found
+
+set -euo pipefail
+
+EPIC_ID="${1:-}"
+FIELD="${2:-}"
+
+if [[ -z "$EPIC_ID" || -z "$FIELD" ]]; then
+  echo "Usage: get-epic-field.sh <epic-id> <field>"
+  echo ""
+  echo "Examples:"
+  echo "  get-epic-field.sh epic-35 jira     # Returns: MSSCI-11234"
+  echo "  get-epic-field.sh epic-35 title    # Returns: Epic title"
+  echo "  get-epic-field.sh 35 jira          # Also works without 'epic-' prefix"
+  echo ""
+  echo "Common fields: jira, title, description, status"
+  exit 1
+fi
+
+# Normalize epic ID - add 'epic-' prefix if not present
+if [[ ! "$EPIC_ID" =~ ^epic- ]]; then
+  EPIC_ID="epic-$EPIC_ID"
+fi
+
+# PROJECT_ROOT should be set by run.sh
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+if [[ ! -f "$SPRINT_FILE" ]]; then
+  echo "null"
+  exit 1
+fi
+
+# Extract field value using yq
+VALUE=$(yq eval ".epics[] | select(.id == \"$EPIC_ID\") | .$FIELD // \"null\"" "$SPRINT_FILE" 2>/dev/null | head -1)
+
+if [[ -z "$VALUE" ]]; then
+  echo "null"
+else
+  echo "$VALUE"
+fi

package/pennyfarthing-dist/scripts/sprint/get-story-field.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Get a field value from a story in sprint YAML
+# Usage: .pennyfarthing/scripts/core/run.sh sprint/get-story-field.sh <story-id> <field>
+#
+# Examples:
+#   .pennyfarthing/scripts/core/run.sh sprint/get-story-field.sh 35-2 workflow
+#   .pennyfarthing/scripts/core/run.sh sprint/get-story-field.sh 35-2 jira
+#   .pennyfarthing/scripts/core/run.sh sprint/get-story-field.sh 35-2 status
+#
+# Common fields: workflow, status, jira, points, title, repos, priority
+# Returns the field value or "null" if not found
+
+set -euo pipefail
+
+STORY_ID="${1:-}"
+FIELD="${2:-}"
+
+if [[ -z "$STORY_ID" || -z "$FIELD" ]]; then
+  echo "Usage: get-story-field.sh <story-id> <field>"
+  echo ""
+  echo "Examples:"
+  echo "  get-story-field.sh 35-2 workflow    # Returns: tdd"
+  echo "  get-story-field.sh 35-2 jira        # Returns: MSSCI-12345"
+  echo "  get-story-field.sh 35-2 status      # Returns: in_progress"
+  echo ""
+  echo "Common fields: workflow, status, jira, points, title, repos, priority"
+  exit 1
+fi
+
+# PROJECT_ROOT should be set by run.sh
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
+
+if [[ ! -f "$SPRINT_FILE" ]]; then
+  echo "null"
+  exit 1
+fi
+
+# Extract field value using yq
+# Handle default values for common fields
+case "$FIELD" in
+  workflow)
+    DEFAULT="tdd"
+    ;;
+  status)
+    DEFAULT="backlog"
+    ;;
+  repos)
+    DEFAULT="pennyfarthing"
+    ;;
+  *)
+    DEFAULT="null"
+    ;;
+esac
+
+VALUE=$(yq eval ".epics[].stories[] | select(.id == \"$STORY_ID\") | .$FIELD // \"$DEFAULT\"" "$SPRINT_FILE" 2>/dev/null | head -1)
+
+if [[ -z "$VALUE" ]]; then
+  echo "null"
+else
+  echo "$VALUE"
+fi

package/pennyfarthing-dist/scripts/sprint/import-epic-to-future.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+/**
+ * import-epic-to-future.mjs - Import epics-and-stories workflow output to future.yaml
+ *
+ * Transforms the markdown output from the epics-and-stories workflow into
+ * the YAML format used by sprint/future.yaml.
+ *
+ * Usage: node import-epic-to-future.mjs [--dry-run] <epics-md-file> [initiative-name]
+ *
+ * Example:
+ *   node import-epic-to-future.mjs docs/planning/reflector-epics-and-stories.md "Reflector Consolidation"
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// =============================================================================
+// Colors
+// =============================================================================
+
+const colors = {
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  blue: (s) => `\x1b[34m${s}\x1b[0m`,
+};
+
+const log = {
+  info: (msg) => console.log(`${colors.blue('INFO')}: ${msg}`),
+  success: (msg) => console.log(`${colors.green('SUCCESS')}: ${msg}`),
+  warn: (msg) => console.log(`${colors.yellow('WARN')}: ${msg}`),
+  error: (msg) => console.error(`${colors.red('ERROR')}: ${msg}`),
+};
+
+// =============================================================================
+// Find project root
+// =============================================================================
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== '/') {
+    if (fs.existsSync(path.join(dir, '.claude'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+// =============================================================================
+// Parse epics markdown file
+// =============================================================================
+
+function parseEpicsMarkdown(content) {
+  const result = {
+    title: '',
+    description: '',
+    totalPoints: 0,
+    epicTitle: '',
+    epicDescription: '',
+    stories: [],
+  };
+
+  const lines = content.split('\n');
+
+  // Extract title from first # heading
+  const titleMatch = content.match(/^# (.+?)( - Epic Breakdown)?$/m);
+  if (titleMatch) {
+    result.title = titleMatch[1].replace(' - Epics and Stories', '');
+  }
+
+  // Extract description from Overview section
+  const overviewMatch = content.match(/## Overview\s*\n\s*\n(.+?)(?=\n\n##|\n##)/s);
+  if (overviewMatch) {
+    result.description = overviewMatch[1].trim();
+  }
+
+  // Extract total points
+  const pointsMatch = content.match(/\*\*Points:\*\*\s*(\d+)/);
+  if (pointsMatch) {
+    result.totalPoints = parseInt(pointsMatch[1], 10);
+  } else {
+    const effortMatch = content.match(/Total Effort.*?(\d+)\s*story points/i);
+    if (effortMatch) {
+      result.totalPoints = parseInt(effortMatch[1], 10);
+    }
+  }
+
+  // Extract epic title
+  const epicTitleMatch = content.match(/^## Epic \d+:\s*(.+)$/m);
+  if (epicTitleMatch) {
+    result.epicTitle = epicTitleMatch[1];
+  }
+
+  // Extract epic description (User Outcome)
+  const userOutcomeMatch = content.match(/\*\*User Outcome:\*\*\s*(.+)/);
+  if (userOutcomeMatch) {
+    result.epicDescription = userOutcomeMatch[1];
+  }
+
+  // Parse stories
+  const storyRegex = /^### Story \d+\.(\d+):\s*(.+)$/gm;
+  const iWantRegex = /^I want \*\*(.+?)\*\*,/m;
+
+  let match;
+  let storyPositions = [];
+
+  // Find all story positions
+  while ((match = storyRegex.exec(content)) !== null) {
+    storyPositions.push({
+      num: parseInt(match[1], 10),
+      title: match[2],
+      index: match.index,
+    });
+  }
+
+  // Extract description for each story
+  for (let i = 0; i < storyPositions.length; i++) {
+    const story = storyPositions[i];
+    const startIndex = story.index;
+    const endIndex = i < storyPositions.length - 1
+      ? storyPositions[i + 1].index
+      : content.length;
+
+    const storyContent = content.slice(startIndex, endIndex);
+
+    // Extract "I want" description
+    const iWantMatch = storyContent.match(iWantRegex);
+    let description = '';
+    if (iWantMatch) {
+      description = iWantMatch[1];
+    }
+
+    result.stories.push({
+      num: story.num,
+      title: story.title,
+      description: description,
+    });
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Get next epic number from future.yaml
+// =============================================================================
+
+function getNextEpicNumber(futureYamlPath) {
+  if (!fs.existsSync(futureYamlPath)) {
+    return 60;
+  }
+
+  const content = fs.readFileSync(futureYamlPath, 'utf-8');
+
+  // Look for "Next Available Epic Number: XX"
+  const nextMatch = content.match(/Next Available Epic Number:\s*(\d+)/i);
+  if (nextMatch) {
+    return parseInt(nextMatch[1], 10);
+  }
+
+  // Fallback: find highest epic-XX number
+  const epicMatches = content.matchAll(/epic-(\d+)/g);
+  let maxNum = 59;
+  for (const m of epicMatches) {
+    const num = parseInt(m[1], 10);
+    if (num > maxNum) {
+      maxNum = num;
+    }
+  }
+
+  return maxNum + 1;
+}
+
+// =============================================================================
+// Generate YAML for initiative
+// =============================================================================
+
+function generateYaml(parsed, epicNum, initiativeName, epicsFile) {
+  const date = new Date().toISOString().split('T')[0];
+
+  // Indent helper
+  const indent = (text, spaces) => {
+    return text.split('\n').map(line => ' '.repeat(spaces) + line).join('\n');
+  };
+
+  let yaml = `
+    # ==========================================================================
+    # ${initiativeName}
+    # Imported from: ${epicsFile}
+    # Date: ${date}
+    # ==========================================================================
+    - name: "${initiativeName}"
+      description: |
+        ${parsed.description}
+      status: ready
+      blocked_by: null
+      total_points: ${parsed.totalPoints}
+      prd: docs/planning/reflector-prd.md
+      epics_doc: ${epicsFile}
+      epics:
+        - id: epic-${epicNum}
+          title: "${parsed.epicTitle || initiativeName}"
+          description: |
+            ${parsed.epicDescription || parsed.description}
+          points: ${parsed.totalPoints}
+          priority: P1
+          marker: "reflector"
+          repos: pennyfarthing
+          status: planning
+          stories:
+`;
+
+  // Add stories
+  for (const story of parsed.stories) {
+    yaml += `            - id: "${epicNum}-${story.num}"
+              title: "${story.title}"
+              description: |
+                ${story.description || story.title}
+              points: 1
+              priority: P0
+              status: planning
+              repos: pennyfarthing
+`;
+  }
+
+  return yaml;
+}
+
+// =============================================================================
+// Update future.yaml
+// =============================================================================
+
+function updateFutureYaml(futureYamlPath, newContent, nextEpicNum) {
+  let content = fs.readFileSync(futureYamlPath, 'utf-8');
+
+  // Update next epic number comment
+  content = content.replace(
+    /Next Available Epic Number:\s*\d+/i,
+    `Next Available Epic Number: ${nextEpicNum + 1}`
+  );
+
+  // Find insertion point (before SUMMARY section)
+  const summaryIndex = content.indexOf('# =============================================================================\n# SUMMARY');
+
+  if (summaryIndex === -1) {
+    // No summary section, append at end
+    content += newContent;
+  } else {
+    // Insert before summary
+    content = content.slice(0, summaryIndex) + newContent + '\n' + content.slice(summaryIndex);
+  }
+
+  // Update epic numbering comment (append new epic number to the range)
+  const epicNumMatch = content.match(/# Epic Numbering Used: ([\d\-,\s]+)\n/);
+  if (epicNumMatch) {
+    const current = epicNumMatch[1].trim();
+    if (!current.includes(nextEpicNum.toString())) {
+      // Parse the last range and extend it, or add new number
+      const lastRange = current.match(/(\d+)-(\d+)$/);
+      let newNumbering;
+      if (lastRange && parseInt(lastRange[2], 10) === nextEpicNum - 1) {
+        // Extend the range (e.g., 55-59 becomes 55-61)
+        newNumbering = current.replace(/(\d+)-(\d+)$/, `$1-${nextEpicNum}`);
+      } else {
+        // Add new number (e.g., 55-59, 61)
+        newNumbering = `${current}, ${nextEpicNum}`;
+      }
+      content = content.replace(
+        /# Epic Numbering Used: [\d\-,\s]+\n/,
+        `# Epic Numbering Used: ${newNumbering}\n`
+      );
+    }
+  }
+
+  // Update summary table
+  const summaryTableMatch = content.match(/# TOTAL\s+\|\s+(\d+)\s+\|\s+(\d+)/);
+  if (summaryTableMatch) {
+    const oldEpics = parseInt(summaryTableMatch[1], 10);
+    const oldPoints = parseInt(summaryTableMatch[2], 10);
+    // We'd need to parse the new points, but for simplicity just note it needs manual update
+  }
+
+  return content;
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+function main() {
+  const args = process.argv.slice(2);
+
+  let dryRun = false;
+  let epicsFile = '';
+  let initiativeName = '';
+
+  // Parse arguments
+  for (const arg of args) {
+    if (arg === '--dry-run') {
+      dryRun = true;
+    } else if (arg === '--help' || arg === '-h') {
+      console.log(`Usage: node import-epic-to-future.mjs [--dry-run] <epics-md-file> [initiative-name]
+
+Arguments:
+  epics-md-file    Path to the markdown file from epics-and-stories workflow
+  initiative-name  Name for the initiative (optional, extracted from file if not provided)
+
+Options:
+  --dry-run        Print YAML to stdout instead of updating future.yaml
+  --help, -h       Show this help message`);
+      process.exit(0);
+    } else if (!epicsFile) {
+      epicsFile = arg;
+    } else if (!initiativeName) {
+      initiativeName = arg;
+    }
+  }
+
+  if (!epicsFile) {
+    log.error('No epics markdown file specified');
+    console.log('Usage: node import-epic-to-future.mjs [--dry-run] <epics-md-file> [initiative-name]');
+    process.exit(1);
+  }
+
+  const projectRoot = findProjectRoot();
+  const fullEpicsPath = path.isAbsolute(epicsFile)
+    ? epicsFile
+    : path.join(projectRoot, epicsFile);
+
+  if (!fs.existsSync(fullEpicsPath)) {
+    log.error(`File not found: ${fullEpicsPath}`);
+    process.exit(1);
+  }
+
+  const futureYamlPath = path.join(projectRoot, 'sprint', 'future.yaml');
+
+  // Read and parse epics file
+  const content = fs.readFileSync(fullEpicsPath, 'utf-8');
+  const parsed = parseEpicsMarkdown(content);
+
+  // Use provided name or extract from file
+  if (!initiativeName) {
+    initiativeName = parsed.title || 'Imported Initiative';
+  }
+
+  // Get next epic number
+  const nextEpicNum = getNextEpicNumber(futureYamlPath);
+
+  log.info(`Next epic number: ${nextEpicNum}`);
+  log.info(`Initiative name: ${initiativeName}`);
+  log.info(`Total points: ${parsed.totalPoints}`);
+  log.info(`Epic title: ${parsed.epicTitle}`);
+  log.info(`Stories found: ${parsed.stories.length}`);
+
+  // Generate YAML
+  const newYaml = generateYaml(parsed, nextEpicNum, initiativeName, epicsFile);
+
+  if (dryRun) {
+    console.log(`\n${colors.yellow('=== DRY RUN: Would append to future.yaml ===')}`);
+    console.log(newYaml);
+    console.log(`${colors.yellow('=== End of YAML ===')}\n`);
+    console.log(`${colors.green('To apply, run without --dry-run')}`);
+  } else {
+    // Update future.yaml
+    const updatedContent = updateFutureYaml(futureYamlPath, newYaml, nextEpicNum);
+    fs.writeFileSync(futureYamlPath, updatedContent);
+
+    log.success(`Added epic-${nextEpicNum} to ${futureYamlPath}`);
+    log.success(`Next available epic number is now: ${nextEpicNum + 1}`);
+  }
+}
+
+main();

package/pennyfarthing-dist/scripts/sprint/import-epic-to-future.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# import-epic-to-future.sh - Thin wrapper for import-epic-to-future.mjs
+#
+# Usage: ./scripts/sprint/import-epic-to-future.sh [--dry-run] <epics-md-file> [initiative-name]
+#
+# Delegates to Node script for cleaner markdown parsing and YAML generation.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "${SCRIPT_DIR}/import-epic-to-future.mjs" "$@"