forgehive 0.7.7 → 0.7.8

package/docs/superpowers/plans/2026-05-14-sprint-planner-v2.md

@@ -1,1058 +0,0 @@
-# Sprint Planner v2 — Story Cards, Epics, Velocity
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task.
-
-**Goal:** Extend forgehive's sprint planning with structured Story Cards (User Stories + AC), Epic hierarchy, and Velocity Tracking — all stored as Markdown files in `.forgehive/memory/`.
-
-**Architecture:** Three new modules (`src/stories.ts`, `src/epics.ts`, `src/velocity.ts`) with corresponding test files. Stories and Epics are persisted as individual Markdown files with YAML frontmatter. Velocity is a single append-only Markdown table. CLI commands: `fh story`, `fh epic`, `fh velocity`. `/fh-sprint` is enhanced to load backlog stories, assign Fibonacci points, and write velocity on completion.
-
-**Tech Stack:** TypeScript ESM, Node.js ≥ 18, `js-yaml`, `node:fs`, `node:path` — no new runtime dependencies.
-
----
-
-## File Map
-
-**New source files:**
-- `src/stories.ts` — Story Card CRUD + formatting
-- `src/epics.ts` — Epic CRUD + formatting
-- `src/velocity.ts` — Velocity tracking + rolling average
-
-**New test files:**
-- `test/stories.test.ts`
-- `test/epics.test.ts`
-- `test/velocity.test.ts`
-
-**Modified files:**
-- `src/cli.ts` — wire `fh story`, `fh epic`, `fh velocity`
-- `forgehive/commands/fh-sprint.md` — Fibonacci points + story loading + velocity recording
-
----
-
-## Task 1: Story Cards (`src/stories.ts`)
-
-**Files:**
-- Create: `src/stories.ts`
-- Create: `test/stories.test.ts`
-- Modify: `src/cli.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/stories.test.ts
-import { describe, it, beforeEach, afterEach } from "node:test";
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import {
-  createStory,
-  listStories,
-  getStory,
-  updateStoryPoints,
-  updateStoryStatus,
-  formatStoryCard,
-} from "../src/stories.ts";
-
-describe("createStory()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-stories-"));
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("creates a story file and returns the story", () => {
-    const story = createStory(tmpDir, "Als Nutzer möchte ich mich einloggen");
-    assert.ok(story.id.startsWith("US-"));
-    assert.equal(story.title, "Als Nutzer möchte ich mich einloggen");
-    assert.equal(story.status, "backlog");
-    assert.ok(fs.existsSync(path.join(tmpDir, `${story.id}.md`)));
-  });
-
-  it("auto-increments story IDs", () => {
-    const s1 = createStory(tmpDir, "Story one");
-    const s2 = createStory(tmpDir, "Story two");
-    assert.notEqual(s1.id, s2.id);
-  });
-
-  it("assigns epicId when provided", () => {
-    const story = createStory(tmpDir, "Story with epic", "EPC-1");
-    assert.equal(story.epicId, "EPC-1");
-  });
-});
-
-describe("listStories()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-stories-"));
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("returns all stories from directory", () => {
-    createStory(tmpDir, "Story A");
-    createStory(tmpDir, "Story B");
-    const stories = listStories(tmpDir);
-    assert.equal(stories.length, 2);
-  });
-
-  it("returns empty array when directory is empty", () => {
-    const stories = listStories(tmpDir);
-    assert.equal(stories.length, 0);
-  });
-});
-
-describe("updateStoryPoints()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-stories-"));
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("updates points and persists", () => {
-    const story = createStory(tmpDir, "Pointable story");
-    updateStoryPoints(tmpDir, story.id, 5);
-    const loaded = getStory(tmpDir, story.id);
-    assert.equal(loaded?.points, 5);
-  });
-});
-
-describe("formatStoryCard()", () => {
-  it("produces markdown with story ID and title", () => {
-    const story = {
-      id: "US-1",
-      title: "Login feature",
-      asA: "Nutzer",
-      iWant: "mich einloggen",
-      soThat: "ich mein Konto sehen kann",
-      acceptanceCriteria: ["Login-Formular ist sichtbar", "Falsche Credentials zeigen Fehler"],
-      points: 3,
-      epicId: null,
-      status: "backlog" as const,
-    };
-    const md = formatStoryCard(story);
-    assert.ok(md.includes("US-1"));
-    assert.ok(md.includes("Login feature"));
-    assert.ok(md.includes("3"));
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-cd /home/stefan/projekte/forgehive
-node --import tsx/esm --test test/stories.test.ts
-```
-Expected: FAIL — `Cannot find module '../src/stories.ts'`
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/stories.ts
-import fs from "node:fs";
-import path from "node:path";
-import yaml from "js-yaml";
-
-export interface Story {
-  id: string;
-  title: string;
-  asA: string;
-  iWant: string;
-  soThat: string;
-  acceptanceCriteria: string[];
-  points: number | null;
-  epicId: string | null;
-  status: "backlog" | "in-sprint" | "done";
-}
-
-function nextStoryId(storiesDir: string): string {
-  if (!fs.existsSync(storiesDir)) return "US-1";
-  const existing = fs.readdirSync(storiesDir)
-    .filter((f) => f.match(/^US-\d+\.md$/))
-    .map((f) => parseInt(f.replace("US-", "").replace(".md", ""), 10))
-    .filter((n) => !isNaN(n));
-  const max = existing.length > 0 ? Math.max(...existing) : 0;
-  return `US-${max + 1}`;
-}
-
-function storyToMarkdown(story: Story): string {
-  const frontmatter = yaml.dump({
-    id: story.id,
-    title: story.title,
-    asA: story.asA,
-    iWant: story.iWant,
-    soThat: story.soThat,
-    points: story.points,
-    epicId: story.epicId,
-    status: story.status,
-  });
-  const acLines = story.acceptanceCriteria.map((c) => `- [ ] ${c}`).join("\n");
-  return `---\n${frontmatter}---\n\n# ${story.id}: ${story.title}\n\n## User Story\n\nAls **${story.asA}** möchte ich **${story.iWant}**, damit **${story.soThat}**.\n\n## Acceptance Criteria\n\n${acLines || "- [ ] (noch nicht definiert)"}\n`;
-}
-
-function parseStoryFile(filePath: string): Story | null {
-  try {
-    const content = fs.readFileSync(filePath, "utf8");
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match) return null;
-    const data = yaml.load(match[1]) as any;
-    return {
-      id: data.id ?? "",
-      title: data.title ?? "",
-      asA: data.asA ?? "",
-      iWant: data.iWant ?? "",
-      soThat: data.soThat ?? "",
-      acceptanceCriteria: data.acceptanceCriteria ?? [],
-      points: data.points ?? null,
-      epicId: data.epicId ?? null,
-      status: data.status ?? "backlog",
-    };
-  } catch {
-    return null;
-  }
-}
-
-export function createStory(
-  storiesDir: string,
-  title: string,
-  epicId?: string
-): Story {
-  fs.mkdirSync(storiesDir, { recursive: true });
-  const id = nextStoryId(storiesDir);
-  const story: Story = {
-    id,
-    title,
-    asA: "",
-    iWant: title,
-    soThat: "",
-    acceptanceCriteria: [],
-    points: null,
-    epicId: epicId ?? null,
-    status: "backlog",
-  };
-  fs.writeFileSync(path.join(storiesDir, `${id}.md`), storyToMarkdown(story), "utf8");
-  return story;
-}
-
-export function listStories(storiesDir: string): Story[] {
-  if (!fs.existsSync(storiesDir)) return [];
-  return fs.readdirSync(storiesDir)
-    .filter((f) => f.match(/^US-\d+\.md$/))
-    .map((f) => parseStoryFile(path.join(storiesDir, f)))
-    .filter((s): s is Story => s !== null)
-    .sort((a, b) => {
-      const na = parseInt(a.id.replace("US-", ""), 10);
-      const nb = parseInt(b.id.replace("US-", ""), 10);
-      return na - nb;
-    });
-}
-
-export function getStory(storiesDir: string, id: string): Story | null {
-  const filePath = path.join(storiesDir, `${id}.md`);
-  if (!fs.existsSync(filePath)) return null;
-  return parseStoryFile(filePath);
-}
-
-export function updateStoryPoints(storiesDir: string, id: string, points: number): void {
-  const story = getStory(storiesDir, id);
-  if (!story) throw new Error(`Story ${id} nicht gefunden`);
-  story.points = points;
-  fs.writeFileSync(path.join(storiesDir, `${id}.md`), storyToMarkdown(story), "utf8");
-}
-
-export function updateStoryStatus(
-  storiesDir: string,
-  id: string,
-  status: Story["status"]
-): void {
-  const story = getStory(storiesDir, id);
-  if (!story) throw new Error(`Story ${id} nicht gefunden`);
-  story.status = status;
-  fs.writeFileSync(path.join(storiesDir, `${id}.md`), storyToMarkdown(story), "utf8");
-}
-
-export function formatStoryCard(story: Story): string {
-  const points = story.points !== null ? ` · ${story.points} Punkte` : "";
-  const epic = story.epicId ? ` · ${story.epicId}` : "";
-  const lines: string[] = [];
-  lines.push(`## ${story.id}: ${story.title}${points}${epic}`);
-  lines.push(`**Status:** ${story.status}`);
-  if (story.asA || story.iWant)
-    lines.push(`**Story:** Als ${story.asA || "Nutzer"} möchte ich ${story.iWant}${story.soThat ? `, damit ${story.soThat}` : ""}.`);
-  if (story.acceptanceCriteria.length > 0) {
-    lines.push("**Acceptance Criteria:**");
-    for (const ac of story.acceptanceCriteria) lines.push(`- ${ac}`);
-  }
-  return lines.join("\n");
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/stories.test.ts
-```
-Expected: 8 passing
-
-- [ ] **Step 5: Wire `fh story` in cli.ts**
-
-Add import:
-```typescript
-import { createStory, listStories, getStory, updateStoryPoints, updateStoryStatus, formatStoryCard } from "./stories.ts";
-```
-
-Add handler (use `const storiesDir = path.join(forgehiveDir, "memory", "stories");`):
-```typescript
-} else if (command === "story") {
-  const storiesDir = path.join(forgehiveDir, "memory", "stories");
-  if (subcommand === "create") {
-    const title = rest.filter((r) => !r.startsWith("--")).join(" ");
-    const epicArg = rest.includes("--epic") ? rest[rest.indexOf("--epic") + 1] : undefined;
-    const pointsArg = rest.includes("--points") ? parseInt(rest[rest.indexOf("--points") + 1], 10) : undefined;
-    if (!title) { console.error("Usage: fh story create <titel> [--epic EPC-N] [--points N]"); process.exit(1); }
-    const story = createStory(storiesDir, title, epicArg);
-    if (pointsArg) updateStoryPoints(storiesDir, story.id, pointsArg);
-    console.log(`✔ ${story.id} erstellt: ${path.join(storiesDir, story.id + ".md")}`);
-    console.log(`  Bearbeite die Datei um Acceptance Criteria hinzuzufügen.`);
-  } else if (subcommand === "list") {
-    const epicFilter = rest.includes("--epic") ? rest[rest.indexOf("--epic") + 1] : null;
-    let stories = listStories(storiesDir);
-    if (epicFilter) stories = stories.filter((s) => s.epicId === epicFilter);
-    if (stories.length === 0) { console.log("Keine Stories gefunden."); }
-    else {
-      for (const s of stories) {
-        const pts = s.points !== null ? ` [${s.points}pt]` : " [?pt]";
-        const epic = s.epicId ? ` (${s.epicId})` : "";
-        console.log(`  ${s.id}${pts}${epic} — ${s.title} [${s.status}]`);
-      }
-    }
-  } else if (subcommand === "done") {
-    const id = rest[0];
-    const pointsArg = rest.includes("--points") ? parseInt(rest[rest.indexOf("--points") + 1], 10) : undefined;
-    if (!id) { console.error("Usage: fh story done <US-N> [--points N]"); process.exit(1); }
-    if (pointsArg) updateStoryPoints(storiesDir, id, pointsArg);
-    updateStoryStatus(storiesDir, id, "done");
-    console.log(`✔ ${id} als done markiert`);
-  } else if (subcommand === "show") {
-    const id = rest[0];
-    if (!id) { console.error("Usage: fh story show <US-N>"); process.exit(1); }
-    const story = getStory(storiesDir, id);
-    if (!story) { console.error(`Story ${id} nicht gefunden`); process.exit(1); }
-    console.log(formatStoryCard(story));
-  } else {
-    console.error("Verfügbar: fh story create | list | show | done");
-  }
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/stories.ts test/stories.test.ts src/cli.ts
-git commit -m "feat: add fh story command with Story Card management"
-```
-
----
-
-## Task 2: Epic Hierarchy (`src/epics.ts`)
-
-**Files:**
-- Create: `src/epics.ts`
-- Create: `test/epics.test.ts`
-- Modify: `src/cli.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/epics.test.ts
-import { describe, it, beforeEach, afterEach } from "node:test";
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import { createEpic, listEpics, getEpic, addStoryToEpic, formatEpicCard } from "../src/epics.ts";
-
-describe("createEpic()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-epics-"));
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("creates an epic file and returns the epic", () => {
-    const epic = createEpic(tmpDir, "User Authentication");
-    assert.ok(epic.id.startsWith("EPC-"));
-    assert.equal(epic.title, "User Authentication");
-    assert.equal(epic.status, "active");
-    assert.ok(fs.existsSync(path.join(tmpDir, `${epic.id}.md`)));
-  });
-
-  it("auto-increments epic IDs", () => {
-    const e1 = createEpic(tmpDir, "Epic One");
-    const e2 = createEpic(tmpDir, "Epic Two");
-    assert.notEqual(e1.id, e2.id);
-  });
-
-  it("stores goal when provided", () => {
-    const epic = createEpic(tmpDir, "Auth", "Nutzer können sich sicher einloggen");
-    assert.equal(epic.goal, "Nutzer können sich sicher einloggen");
-  });
-});
-
-describe("addStoryToEpic()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-epics-"));
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("adds story ID to epic and persists", () => {
-    const epic = createEpic(tmpDir, "Epic with stories");
-    addStoryToEpic(tmpDir, epic.id, "US-1");
-    addStoryToEpic(tmpDir, epic.id, "US-2");
-    const loaded = getEpic(tmpDir, epic.id);
-    assert.ok(loaded?.stories.includes("US-1"));
-    assert.ok(loaded?.stories.includes("US-2"));
-  });
-});
-
-describe("listEpics()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-epics-"));
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("returns all epics from directory", () => {
-    createEpic(tmpDir, "Epic A");
-    createEpic(tmpDir, "Epic B");
-    assert.equal(listEpics(tmpDir).length, 2);
-  });
-});
-
-describe("formatEpicCard()", () => {
-  it("produces markdown with epic ID and title", () => {
-    const epic = { id: "EPC-1", title: "Auth", goal: "Sicher einloggen", stories: ["US-1", "US-2"], status: "active" as const };
-    const md = formatEpicCard(epic);
-    assert.ok(md.includes("EPC-1"));
-    assert.ok(md.includes("Auth"));
-    assert.ok(md.includes("US-1"));
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/epics.test.ts
-```
-Expected: FAIL
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/epics.ts
-import fs from "node:fs";
-import path from "node:path";
-import yaml from "js-yaml";
-
-export interface Epic {
-  id: string;
-  title: string;
-  goal: string;
-  stories: string[];
-  status: "active" | "done";
-}
-
-function nextEpicId(epicsDir: string): string {
-  if (!fs.existsSync(epicsDir)) return "EPC-1";
-  const existing = fs.readdirSync(epicsDir)
-    .filter((f) => f.match(/^EPC-\d+\.md$/))
-    .map((f) => parseInt(f.replace("EPC-", "").replace(".md", ""), 10))
-    .filter((n) => !isNaN(n));
-  const max = existing.length > 0 ? Math.max(...existing) : 0;
-  return `EPC-${max + 1}`;
-}
-
-function epicToMarkdown(epic: Epic): string {
-  const frontmatter = yaml.dump({
-    id: epic.id,
-    title: epic.title,
-    goal: epic.goal,
-    stories: epic.stories,
-    status: epic.status,
-  });
-  const storyLines = epic.stories.map((s) => `- ${s}`).join("\n");
-  return `---\n${frontmatter}---\n\n# ${epic.id}: ${epic.title}\n\n**Ziel:** ${epic.goal || "(noch nicht definiert)"}\n\n## Stories\n\n${storyLines || "(noch keine Stories)"}\n`;
-}
-
-function parseEpicFile(filePath: string): Epic | null {
-  try {
-    const content = fs.readFileSync(filePath, "utf8");
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match) return null;
-    const data = yaml.load(match[1]) as any;
-    return {
-      id: data.id ?? "",
-      title: data.title ?? "",
-      goal: data.goal ?? "",
-      stories: data.stories ?? [],
-      status: data.status ?? "active",
-    };
-  } catch {
-    return null;
-  }
-}
-
-export function createEpic(epicsDir: string, title: string, goal?: string): Epic {
-  fs.mkdirSync(epicsDir, { recursive: true });
-  const id = nextEpicId(epicsDir);
-  const epic: Epic = {
-    id,
-    title,
-    goal: goal ?? "",
-    stories: [],
-    status: "active",
-  };
-  fs.writeFileSync(path.join(epicsDir, `${id}.md`), epicToMarkdown(epic), "utf8");
-  return epic;
-}
-
-export function listEpics(epicsDir: string): Epic[] {
-  if (!fs.existsSync(epicsDir)) return [];
-  return fs.readdirSync(epicsDir)
-    .filter((f) => f.match(/^EPC-\d+\.md$/))
-    .map((f) => parseEpicFile(path.join(epicsDir, f)))
-    .filter((e): e is Epic => e !== null)
-    .sort((a, b) => {
-      const na = parseInt(a.id.replace("EPC-", ""), 10);
-      const nb = parseInt(b.id.replace("EPC-", ""), 10);
-      return na - nb;
-    });
-}
-
-export function getEpic(epicsDir: string, id: string): Epic | null {
-  const filePath = path.join(epicsDir, `${id}.md`);
-  if (!fs.existsSync(filePath)) return null;
-  return parseEpicFile(filePath);
-}
-
-export function addStoryToEpic(epicsDir: string, epicId: string, storyId: string): void {
-  const epic = getEpic(epicsDir, epicId);
-  if (!epic) throw new Error(`Epic ${epicId} nicht gefunden`);
-  if (!epic.stories.includes(storyId)) {
-    epic.stories.push(storyId);
-    fs.writeFileSync(path.join(epicsDir, `${epicId}.md`), epicToMarkdown(epic), "utf8");
-  }
-}
-
-export function formatEpicCard(epic: Epic, stories?: { id: string; title: string; points: number | null; status: string }[]): string {
-  const lines: string[] = [];
-  lines.push(`## ${epic.id}: ${epic.title} [${epic.status}]`);
-  if (epic.goal) lines.push(`**Ziel:** ${epic.goal}`);
-  lines.push(`**Stories:** ${epic.stories.length}`);
-  if (stories && stories.length > 0) {
-    const total = stories.reduce((sum, s) => sum + (s.points ?? 0), 0);
-    lines.push(`**Punkte:** ${total}`);
-    lines.push("");
-    for (const s of stories) {
-      const pts = s.points !== null ? ` [${s.points}pt]` : " [?pt]";
-      lines.push(`  - ${s.id}${pts} — ${s.title} [${s.status}]`);
-    }
-  } else if (epic.stories.length > 0) {
-    for (const id of epic.stories) lines.push(`  - ${id}`);
-  }
-  return lines.join("\n");
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/epics.test.ts
-```
-Expected: 7 passing
-
-- [ ] **Step 5: Wire `fh epic` in cli.ts**
-
-Add import:
-```typescript
-import { createEpic, listEpics, getEpic, addStoryToEpic, formatEpicCard } from "./epics.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "epic") {
-  const epicsDir = path.join(forgehiveDir, "memory", "epics");
-  const storiesDir = path.join(forgehiveDir, "memory", "stories");
-  if (subcommand === "create") {
-    const title = rest.filter((r) => !r.startsWith("--")).join(" ");
-    const goalArg = rest.includes("--goal") ? rest[rest.indexOf("--goal") + 1] : undefined;
-    if (!title) { console.error("Usage: fh epic create <titel> [--goal <ziel>]"); process.exit(1); }
-    const epic = createEpic(epicsDir, title, goalArg);
-    console.log(`✔ ${epic.id} erstellt: ${path.join(epicsDir, epic.id + ".md")}`);
-  } else if (subcommand === "list") {
-    const epics = listEpics(epicsDir);
-    if (epics.length === 0) { console.log("Keine Epics gefunden."); }
-    else {
-      for (const e of epics)
-        console.log(`  ${e.id} — ${e.title} [${e.status}] (${e.stories.length} Stories)`);
-    }
-  } else if (subcommand === "show") {
-    const id = rest[0];
-    if (!id) { console.error("Usage: fh epic show <EPC-N>"); process.exit(1); }
-    const epic = getEpic(epicsDir, id);
-    if (!epic) { console.error(`Epic ${id} nicht gefunden`); process.exit(1); }
-    const stories = listStories(storiesDir).filter((s) => s.epicId === id);
-    console.log(formatEpicCard(epic, stories));
-  } else {
-    console.error("Verfügbar: fh epic create | list | show");
-  }
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/epics.ts test/epics.test.ts src/cli.ts
-git commit -m "feat: add fh epic command with Epic hierarchy management"
-```
-
----
-
-## Task 3: Velocity Tracking (`src/velocity.ts`)
-
-**Files:**
-- Create: `src/velocity.ts`
-- Create: `test/velocity.test.ts`
-- Modify: `src/cli.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/velocity.test.ts
-import { describe, it, beforeEach, afterEach } from "node:test";
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import {
-  recordVelocity,
-  getVelocityHistory,
-  getRollingAverage,
-  formatVelocityReport,
-} from "../src/velocity.ts";
-
-describe("recordVelocity()", () => {
-  let tmpDir: string;
-  let velocityFile: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-velocity-"));
-    velocityFile = path.join(tmpDir, "velocity.md");
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("creates velocity file on first record", () => {
-    recordVelocity(velocityFile, 1, 13, 10);
-    assert.ok(fs.existsSync(velocityFile));
-  });
-
-  it("appends subsequent records", () => {
-    recordVelocity(velocityFile, 1, 13, 10);
-    recordVelocity(velocityFile, 2, 15, 13);
-    const history = getVelocityHistory(velocityFile);
-    assert.equal(history.length, 2);
-  });
-});
-
-describe("getVelocityHistory()", () => {
-  let tmpDir: string;
-  let velocityFile: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-velocity-"));
-    velocityFile = path.join(tmpDir, "velocity.md");
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("returns empty array when file does not exist", () => {
-    const history = getVelocityHistory(velocityFile);
-    assert.equal(history.length, 0);
-  });
-
-  it("returns correct committed and delivered values", () => {
-    recordVelocity(velocityFile, 1, 13, 10);
-    const history = getVelocityHistory(velocityFile);
-    assert.equal(history[0].committed, 13);
-    assert.equal(history[0].delivered, 10);
-    assert.equal(history[0].sprint, 1);
-  });
-});
-
-describe("getRollingAverage()", () => {
-  it("returns average of last N sprints", () => {
-    const history = [
-      { sprint: 1, date: "2026-01-01", committed: 10, delivered: 8 },
-      { sprint: 2, date: "2026-01-15", committed: 12, delivered: 10 },
-      { sprint: 3, date: "2026-02-01", committed: 14, delivered: 12 },
-    ];
-    const avg = getRollingAverage(history, 2);
-    assert.equal(avg, 11); // (10 + 12) / 2
-  });
-
-  it("returns 0 for empty history", () => {
-    assert.equal(getRollingAverage([]), 0);
-  });
-});
-
-describe("formatVelocityReport()", () => {
-  it("produces markdown with sprint table", () => {
-    const history = [
-      { sprint: 1, date: "2026-01-01", committed: 10, delivered: 8 },
-    ];
-    const md = formatVelocityReport(history);
-    assert.ok(md.includes("Sprint 1"));
-    assert.ok(md.includes("10"));
-    assert.ok(md.includes("8"));
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/velocity.test.ts
-```
-Expected: FAIL
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/velocity.ts
-import fs from "node:fs";
-import path from "node:path";
-
-export interface SprintVelocity {
-  sprint: number;
-  date: string;
-  committed: number;
-  delivered: number;
-}
-
-const HEADER = "# Sprint Velocity\n\n| Sprint | Datum | Committed | Delivered | Rate |\n|---|---|---|---|---|\n";
-
-export function recordVelocity(
-  velocityFile: string,
-  sprint: number,
-  committed: number,
-  delivered: number
-): void {
-  const date = new Date().toISOString().slice(0, 10);
-  const rate = committed > 0 ? Math.round((delivered / committed) * 100) : 0;
-  const row = `| Sprint ${sprint} | ${date} | ${committed} | ${delivered} | ${rate}% |\n`;
-
-  if (!fs.existsSync(velocityFile)) {
-    fs.mkdirSync(path.dirname(velocityFile), { recursive: true });
-    fs.writeFileSync(velocityFile, HEADER + row, "utf8");
-  } else {
-    fs.appendFileSync(velocityFile, row, "utf8");
-  }
-}
-
-export function getVelocityHistory(velocityFile: string): SprintVelocity[] {
-  if (!fs.existsSync(velocityFile)) return [];
-  const content = fs.readFileSync(velocityFile, "utf8");
-  const rows = content
-    .split("\n")
-    .filter((l) => l.startsWith("| Sprint "));
-
-  return rows.map((row) => {
-    const cells = row.split("|").map((c) => c.trim()).filter(Boolean);
-    const sprintMatch = cells[0]?.match(/Sprint (\d+)/);
-    return {
-      sprint: sprintMatch ? parseInt(sprintMatch[1], 10) : 0,
-      date: cells[1] ?? "",
-      committed: parseInt(cells[2] ?? "0", 10),
-      delivered: parseInt(cells[3] ?? "0", 10),
-    };
-  }).filter((r) => r.sprint > 0);
-}
-
-export function getRollingAverage(history: SprintVelocity[], window = 3): number {
-  if (history.length === 0) return 0;
-  const recent = history.slice(-window);
-  const sum = recent.reduce((acc, s) => acc + s.delivered, 0);
-  return Math.round(sum / recent.length);
-}
-
-export function formatVelocityReport(history: SprintVelocity[]): string {
-  if (history.length === 0) return "Noch keine Velocity-Daten vorhanden.\n\nStarte mit: `fh velocity record <sprint> --committed N --delivered N`";
-
-  const avg3 = getRollingAverage(history, 3);
-  const lines: string[] = [];
-  lines.push("# Sprint Velocity");
-  lines.push("");
-  lines.push(`**Rolling Average (letzte 3 Sprints):** ${avg3} Punkte`);
-  lines.push("");
-  lines.push("| Sprint | Datum | Committed | Delivered | Rate |");
-  lines.push("|---|---|---|---|---|");
-  for (const s of history) {
-    const rate = s.committed > 0 ? Math.round((s.delivered / s.committed) * 100) : 0;
-    lines.push(`| Sprint ${s.sprint} | ${s.date} | ${s.committed} | ${s.delivered} | ${rate}% |`);
-  }
-  lines.push("");
-  lines.push(`**Empfehlung für nächsten Sprint:** ~${avg3} Punkte einplanen`);
-  return lines.join("\n");
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/velocity.test.ts
-```
-Expected: 8 passing
-
-- [ ] **Step 5: Wire `fh velocity` in cli.ts**
-
-Add import:
-```typescript
-import { recordVelocity, getVelocityHistory, getRollingAverage, formatVelocityReport } from "./velocity.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "velocity") {
-  const velocityFile = path.join(forgehiveDir, "memory", "velocity.md");
-  if (subcommand === "record") {
-    const sprintNum = parseInt(rest[0] ?? "0", 10);
-    const committed = rest.includes("--committed") ? parseInt(rest[rest.indexOf("--committed") + 1], 10) : NaN;
-    const delivered = rest.includes("--delivered") ? parseInt(rest[rest.indexOf("--delivered") + 1], 10) : NaN;
-    if (!sprintNum || isNaN(committed) || isNaN(delivered)) {
-      console.error("Usage: fh velocity record <sprint-num> --committed N --delivered N");
-      process.exit(1);
-    }
-    recordVelocity(velocityFile, sprintNum, committed, delivered);
-    const avg = getRollingAverage(getVelocityHistory(velocityFile));
-    console.log(`✔ Sprint ${sprintNum} gespeichert. Rolling Average: ${avg} Punkte`);
-  } else {
-    const history = getVelocityHistory(velocityFile);
-    console.log(formatVelocityReport(history));
-  }
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/velocity.ts test/velocity.test.ts src/cli.ts
-git commit -m "feat: add fh velocity command for sprint velocity tracking"
-```
-
----
-
-## Task 4: Enhance `/fh-sprint` + version bump
-
-**Files:**
-- Modify: `forgehive/commands/fh-sprint.md`
-- Modify: `src/cli.ts` (version → 0.7.1)
-- Modify: `package.json` (version → 0.7.1)
-
-- [ ] **Step 1: Replace fh-sprint.md with enhanced version**
-
-Overwrite `forgehive/commands/fh-sprint.md` entirely with:
-
-```markdown
-You are running a Sprint Planning session using the ForgeHive workflow.
-
-## Sprint Planning Protocol
-
-### Step 1: Load context
-
-1. Read `.forgehive/capabilities.yaml` — understand the tech stack and constraints
-2. Read `.forgehive/memory/MEMORY.md` and all linked memory files — load project context
-3. Check if `.forgehive/memory/sprint.md` exists — if so, show the last sprint summary first
-4. Check if `.forgehive/memory/velocity.md` exists — if so, show rolling average as capacity hint
-5. Run `fh scan --check` to verify the codebase snapshot is current
-
-### Step 2: Collect backlog items
-
-Ask the user: **"Welche Items kommen in den Sprint? Liste sie auf — oder soll ich Backlog-Stories laden?"**
-
-**If stories exist** in `.forgehive/memory/stories/` with status `backlog`:
-Run `fh story list` to show available stories. Ask: **"Welche dieser Stories kommen in den Sprint?"**
-
-**If Linear MCP is available** (check if `.mcp.json` contains `linear`):
-Use the Linear MCP tool to fetch open issues:
-```
-mcp__linear__list_issues({ state: "backlog", limit: 30 })
-```
-Show the fetched issues and ask: **"Welche davon kommen in den Sprint?"**
-
-**If GitHub MCP is available** (check if `.mcp.json` contains `github`):
-```bash
-gh issue list --state open --label "sprint-candidate" --limit 20
-```
-
-**If no stories/MCP:**
-Accept free-text input — one item per line.
-
-### Step 3: Clarify and refine
-
-For each item, ask one clarifying question if needed:
-- Is this a feature, bug fix, or chore?
-- Is there a hard dependency on another item?
-- Any known technical risks?
-
-Do NOT ask more than one question per item. If the item is clear, skip this step.
-
-### Step 4: Estimate with Fibonacci Points
-
-Estimate each item using Fibonacci story points:
-
-| Points | Meaning | Typical scope |
-|---|---|---|
-| 1 | Trivial | Config change, copy fix, 1-line fix |
-| 2 | Small | Simple isolated change |
-| 3 | Medium-small | Small feature, isolated fix |
-| 5 | Medium | Feature with tests, moderate complexity |
-| 8 | Large | Complex feature, multiple files |
-| 13 | Extra-large | Should be broken down |
-
-**T-Shirt aliases:** XS=1, S=2, M=5, L=8, XL=13
-
-Flag any 13-point items: **"Dieses Item ist zu groß für einen Sprint — soll ich es aufteilen?"**
-
-If items were loaded from `.forgehive/memory/stories/`, update their points:
-```bash
-fh story <US-N> --points <N>
-```
-
-### Step 5: Prioritize
-
-Sort items into three buckets:
-
-**Must (Sprint-Ziel)** — delivers the sprint goal, blocks other work, or is overdue  
-**Should (Best Effort)** — important but not blocking  
-**Could (Nice to Have)** — do if capacity allows  
-
-Suggest a sprint goal in one sentence based on the Must items.
-
-### Step 6: Check capacity
-
-Show velocity hint if available:
-```bash
-fh velocity show
-```
-
-Ask: **"Wie viele Punkte habt ihr im Sprint?"**
-
-Default: rolling average from velocity history, or 20 points for a 2-week sprint with one developer.
-
-Calculate if Must + Should items fit. If they don't, move the lowest-priority Should items to Could.
-
-Show a capacity summary:
-```
-Sprint-Kapazität: 20 Punkte
-Must:   [sum] Punkte
-Should: [sum] Punkte  
-Could:  [sum] Punkte
-─────────────────────
-Geplant: [must+should] / 20 Punkte
-```
-
-### Step 7: Output the sprint plan
-
-Write the sprint plan to `.forgehive/memory/sprint.md` in this format:
-
-```markdown
-# Sprint [N] — [Datum]
-
-**Ziel:** [one sentence sprint goal]
-
-**Kapazität:** [X] Punkte
-
-## Must
-- [ ] [ID] [Item] ([points]pt) — [one-line description]
-
-## Should  
-- [ ] [ID] [Item] ([points]pt) — [one-line description]
-
-## Could
-- [ ] [ID] [Item] ([points]pt) — [one-line description]
-
-## Offen / Blocked
-- [any blocked items with reason]
-
----
-*Erstellt mit fh sprint — [timestamp]*
-```
-
-Confirm with the user: **"Sprint Plan gespeichert. Soll ich für jedes Must-Item direkt einen Branch anlegen?"**
-
-If yes: create branches following `feat/<slug>`, `fix/<slug>`, `chore/<slug>`.
-
-### Step 8: Update project memory
-
-Append the sprint goal to `.forgehive/memory/project.md` under a `## Aktueller Sprint` section.
-
-### Step 9: Record velocity (at sprint end)
-
-When the user runs `/fh-sprint` and mentions "Sprint ist fertig" or "Sprint abgeschlossen":
-
-1. Ask: **"Wie viele Punkte habt ihr tatsächlich geliefert?"**
-2. Read the committed points from `sprint.md`
-3. Record velocity:
-```bash
-fh velocity record <N> --committed <committed> --delivered <delivered>
-```
-4. Show updated velocity report:
-```bash
-fh velocity show
-```
-```
-
-- [ ] **Step 2: Bump version to 0.7.1**
-
-In `src/cli.ts`, change `console.log("0.7.0")` to `console.log("0.7.1")`.
-In `package.json`, change `"version": "0.7.0"` to `"version": "0.7.1"`.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add forgehive/commands/fh-sprint.md src/cli.ts package.json
-git commit -m "feat: enhance /fh-sprint with story points, velocity, epic-aware backlog"
-```
-
----
-
-## Task 5: Full test run, build, publish 0.7.1
-
-- [ ] **Step 1: Run all tests**
-
-```bash
-npm test
-```
-Expected: all passing (target: ~270+ tests)
-
-- [ ] **Step 2: Typecheck**
-
-```bash
-npm run typecheck
-```
-
-- [ ] **Step 3: Build**
-
-```bash
-npm run build
-head -1 dist/cli.js   # must be #!/usr/bin/env node
-```
-
-- [ ] **Step 4: Publish**
-
-```bash
-npm publish
-```
-
-- [ ] **Step 5: Update memory**
-
-Update `/home/stefan/.claude/projects/-home-stefan-projekte-framework-os/memory/project.md`:
-- Version: v0.7.1
-- New: Story Cards, Epic hierarchy, Velocity tracking
-- Updated: /fh-sprint with Fibonacci points + velocity integration
-```