forgehive 0.7.0 → 0.7.2

package/README.md

@@ -14,8 +14,8 @@
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js ≥ 18">
   <img src="https://img.shields.io/badge/typescript-5.8-blue" alt="TypeScript">
-  <img src="https://img.shields.io/badge/tests-217%20passing-success" alt="217 tests">
-  <img src="https://img.shields.io/badge/bundle-205KB-lightgrey" alt="205KB bundle">
+  <img src="https://img.shields.io/badge/tests-267%20passing-success" alt="267 tests">
+  <img src="https://img.shields.io/badge/bundle-244KB-lightgrey" alt="244KB bundle">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
 </p>
 
@@ -31,18 +31,23 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 
 - **Stack Scanner** — detects tech stack, dependencies, and project structure automatically
 - **Persistent Memory** — context and session notes survive every restart
+- **Story & Epic Tracking** — lightweight agile backlog inside `.forgehive/memory/`
+- **Velocity Tracking** — sprint velocity history, rolling average, and capacity hints
 - **Party Mode** — specialized agent sets, each agent in its own isolated git worktree
 - **MCP Wiring** — preconfigured connectors for 10 services, API keys stored securely in `~/.forgehive/`
 - **Security Suite** — SAST, secret scanner, CVE check, CISO reports (GDPR/SOC2/HIPAA)
+- **CI Integration** — CI health report and GitHub Actions template generator
+- **Codebase Map** — file/line/import table for navigation and onboarding
+- **Team Sync** — share memory across the team via a dedicated git branch
 - **AGENTS.md** — cross-tool standard (Cursor, Copilot, Gemini CLI, Codex, Windsurf)
 
 **Design principle:** writes exclusively to `.forgehive/` in the target project. No globbing outside the project root. Never overwrites files it didn't create.
 
 ---
 
-## Status: Early Alpha (v0.6)
+## Status: v0.7 — Stable
 
-This is an early release. The codebase is clean — TypeScript, 217 passing tests, single bundle — but several features have not yet been tested against a real project.
+267 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
 
 **Stable — use with confidence:**
 
@@ -56,6 +61,16 @@ This is an early release. The codebase is clean — TypeScript, 217 passing test
 | `fh security report` — compliance reports | stable |
 | `fh memory` — show, clean, export, snapshot | stable |
 | MCP credential store (`fh mcp auth`) | stable |
+| `fh ci` — CI health report + GitHub Actions template | stable |
+| `fh map` — codebase structure map | stable |
+| `fh onboard` — generates ONBOARDING.md | stable |
+| `fh changelog` — semantic changelog from git | stable |
+| `fh metrics` — developer metrics by author/type | stable |
+| `fh sync` — team memory sharing via git branch | stable |
+| `fh run` — background agent execution via `claude -p` | stable |
+| `fh story` — story card create/list/show/done | stable |
+| `fh epic` — epic create/list/show | stable |
+| `fh velocity` — show history + record sprint data | stable |
 
 **Experimental — works in tests, not yet live-validated:**
 
@@ -74,7 +89,7 @@ If you run into issues, please open an issue on GitHub. The most valuable feedba
 
 - **Node.js ≥ 18** — check with `node --version`
 - **Claude Code** installed and configured (`claude` CLI available)
-- **git** — required for Party Mode worktrees and the guardrails hook
+- **git** — required for Party Mode worktrees, `fh sync`, and the guardrails hook
 
 ---
 
@@ -94,14 +109,14 @@ This makes both `fh` and `forgehive` available globally.
 git clone https://github.com/matharnica/forgehive
 cd forgehive
 npm install
-npm run build      # compiles to dist/cli.js (~205 KB)
+npm run build      # compiles to dist/cli.js (~244 KB)
 npm link           # makes 'fh' available globally
 ```
 
 Verify the installation:
 
 ```bash
-fh --version       # should print 0.6.0
+fh --version       # should print 0.7.1
 fh --help          # lists all available commands
 ```
 
@@ -264,6 +279,91 @@ Shows `permissions.yaml` — the file access control list for each agent. Each a
 
 ---
 
+### CI
+
+```bash
+fh ci                          # run CI health report (text output)
+fh ci --format json            # output report as JSON
+fh ci --format markdown        # output report as Markdown
+fh ci --fail-on critical       # exit 1 only on CRITICAL findings
+fh ci --fail-on high           # exit 1 on HIGH or CRITICAL
+fh ci --fail-on any            # exit 1 on any finding
+fh ci --init                   # generate a GitHub Actions workflow template
+```
+
+`fh ci` aggregates security scan, dependency audit, and test results into a single CI health report. Use `--init` to scaffold a `.github/workflows/forgehive.yml` file that runs the full check on every pull request. The `--fail-on` flag controls which severity level causes a non-zero exit code, giving you fine-grained control over what blocks a merge.
+
+---
+
+### Codebase Map
+
+```bash
+fh map
+```
+
+Prints a structured table of your codebase: file paths, line counts, and import relationships. Useful for onboarding a new engineer (or a new Claude session) to an unfamiliar codebase. Output goes to stdout; pipe it to a file if you want to save it.
+
+---
+
+### Onboarding
+
+```bash
+fh onboard                     # generate ONBOARDING.md (stdout)
+fh onboard --output ./ONBOARDING.md   # write to file
+```
+
+Generates a human-readable `ONBOARDING.md` from three sources: the detected stack in `capabilities.yaml`, the persistent memory in `.forgehive/memory/`, and the recent git log. The result is a self-contained document a new team member can read to understand the project architecture, conventions, and current state.
+
+---
+
+### Changelog
+
+```bash
+fh changelog                        # full changelog from all commits
+fh changelog --since v0.6.0         # changes since a specific tag
+fh changelog --output CHANGELOG.md  # write to file
+```
+
+Parses conventional commits (`feat:`, `fix:`, `chore:`, `docs:`, etc.) and groups them into a semantic changelog. Breaking changes are surfaced separately. Requires conventional commit messages — standard for projects that use `fh git-conventions`.
+
+---
+
+### Developer Metrics
+
+```bash
+fh metrics                          # all-time developer metrics
+fh metrics --since 2025-01-01       # metrics since a date
+```
+
+Shows commit activity broken down by author and commit type (feat, fix, chore, docs, test, refactor). Also shows rolling statistics: commit frequency, most active contributors, and type distribution. Useful for retrospectives and identifying contribution patterns.
+
+---
+
+### Team Memory Sync
+
+```bash
+fh sync push                                           # push memory to default remote/branch
+fh sync push --remote origin --branch forgehive-memory  # push to a specific remote branch
+fh sync pull                                           # pull memory from remote
+fh sync pull --remote origin --branch forgehive-memory  # pull from specific branch
+```
+
+`fh sync` shares `.forgehive/memory/` across the team by pushing to (or pulling from) a dedicated git branch. This is an alternative to committing the memory directory into the main branch. On `pull`, existing local files are not overwritten — only new files are added, the same idempotent behavior as `fh memory snapshot import`.
+
+---
+
+### Background Agent Execution
+
+```bash
+fh run <issue-url>                         # run agent on a GitHub/Linear issue URL
+fh run <issue-url> --agent kai             # use a specific agent
+fh run <issue-url> --label ready-for-ai   # filter by label
+```
+
+`fh run` launches a background agent via `claude -p`, passes the issue content as context, and returns immediately. The agent reads the issue, applies forgehive context from `.forgehive/`, and works on the task in the background. Useful for automating repetitive issues or running agents overnight. Agent output is streamed to stdout and also written to `.forgehive/runs/`.
+
+---
+
 ### Memory
 
 Memory files live in `.forgehive/memory/` and are read by Claude at session start via the CLAUDE.md block.
@@ -297,6 +397,55 @@ Memory files live in `.forgehive/memory/` and are read by Claude at session star
 
 ---
 
+### Story Cards
+
+Story cards are lightweight user stories stored in `.forgehive/memory/stories/`. They integrate with `/fh-sprint` for velocity-based sprint planning.
+
+```bash
+fh story create "As a user I want to log in"            # create a story (auto-numbered US-N)
+fh story create "As a user I want to log in" --epic EPC-1 --points 3   # with epic + points
+fh story list                                            # list all backlog stories
+fh story list --epic EPC-1                              # filter by epic
+fh story show US-1                                       # show full story card with acceptance criteria
+fh story done US-1                                       # mark story as done
+fh story done US-1 --points 5                           # mark done and record actual points
+```
+
+Each story card is a Markdown file at `.forgehive/memory/stories/US-N.md`. The card includes a title, acceptance criteria placeholder, story points, epic link, and status (`backlog` | `done`). When you run `/fh-sprint` in a Claude Code session, Claude reads the backlog and uses velocity data to suggest a realistic sprint scope.
+
+---
+
+### Epics
+
+Epics group related stories and are stored in `.forgehive/memory/epics/`.
+
+```bash
+fh epic create "User Authentication"                              # create an epic (auto-numbered EPC-N)
+fh epic create "User Authentication" --goal "Users can log in securely"  # with a goal statement
+fh epic list                                                       # list all epics
+fh epic show EPC-1                                                 # show epic with linked stories and point total
+```
+
+Each epic card is a Markdown file at `.forgehive/memory/epics/EPC-N.md`. `fh epic show` aggregates all stories linked to the epic and displays their status and point totals.
+
+---
+
+### Velocity
+
+```bash
+fh velocity show                                              # velocity history + rolling average + recommendation
+fh velocity record sprint-3 --committed 21 --delivered 18    # record sprint data
+```
+
+`fh velocity show` reads the velocity history from `.forgehive/memory/velocity.md` and prints:
+- A table of past sprints (committed vs. delivered points)
+- A rolling average (last 3 sprints)
+- A capacity recommendation for the next sprint
+
+`fh velocity record` appends a new entry to the velocity history. The `/fh-sprint` slash command reads this data automatically and uses it to calibrate the sprint scope it suggests.
+
+---
+
 ### Party Mode
 
 Party Mode runs specialized agent sets in parallel, each in an isolated git worktree.
@@ -320,7 +469,7 @@ fh party cleanup            # remove finished worktrees
 | `security` | Vera + Sam | `/security-party` |
 | `full` | All 8 agents | `/full-party` |
 
-**Model mapping** — assign specific Claude models per agent:
+**Multi-model routing** — `defaults.yaml` supports a `models:` key per agent set. Override via CLI:
 
 ```bash
 fh party --model-map "viktor:claude-opus-4-7,kai:claude-sonnet-4-6,sam:claude-haiku-4-5"
@@ -417,33 +566,57 @@ Clones the repo with `--depth=1`, copies all `.md` files from the `skills/expert
 
 ---
 
+### Slash Commands
+
+The following slash commands are available inside Claude Code sessions:
+
+| Command | Description |
+|---|---|
+| `/fh-sprint` | Sprint planning — reads backlog, velocity, and capacity; suggests scope using Fibonacci points (1/2/3/5/8/13); records velocity at end of sprint |
+| `/fh-deploy` | Pre-deploy checklist — security scan, dependency audit, test run, final confirmation |
+| `/fh-test-this` | Generate tests for the current file or selection — uses `testing-strategies` skill |
+| `/fh-docs` | Generate documentation for the current file or module |
+| `/party` | Start the `build` party (Viktor + Kai + Sam) |
+| `/design-party` | Start the `design` party (Suki + Viktor) |
+| `/review-party` | Start the `review` party (Kai + Sam + Eli) |
+| `/security-party` | Start the `security` party (Vera + Sam) |
+| `/full-party` | Start all 8 agents |
+
+**`/fh-sprint` in detail:** Reads `.forgehive/memory/stories/` for backlog items, `.forgehive/memory/velocity.md` for historical capacity, and `.forgehive/memory/epics/` for epic context. Suggests a sprint scope as a list of story cards with Fibonacci point estimates. When you close the sprint, it prompts you to record delivered points so velocity history stays up to date. If Linear or GitHub MCP servers are connected, it can pull issues directly from those services.
+
+---
+
 ## What `fh init` Creates
 
 ```
 my-project/
   .forgehive/
-    capabilities.yaml          ← detected stack (status: draft → confirmed)
-    scan-result.yaml           ← raw scanner output
-    .scan-hash                 ← checksum for fh scan --check
+    capabilities.yaml          <- detected stack (status: draft -> confirmed)
+    scan-result.yaml           <- raw scanner output
+    .scan-hash                 <- checksum for fh scan --check
     harness/
-      architecture.md          ← codebase overview for Claude
-      constraints.yaml         ← max_lines, require_tests, style rules
-      permissions.yaml         ← per-agent file access control (read/write/deny)
+      architecture.md          <- codebase overview for Claude
+      constraints.yaml         <- max_lines, require_tests, style rules
+      permissions.yaml         <- per-agent file access control (read/write/deny)
     memory/
-      MEMORY.md                ← index of all memory files
-      project.md               ← project context and open decisions
-      feedback.md              ← corrections + confirmed approaches
-      stack.md                 ← stack details the scanner can't detect
-      adrs/                    ← architecture decision records
+      MEMORY.md                <- index of all memory files
+      project.md               <- project context and open decisions
+      feedback.md              <- corrections + confirmed approaches
+      stack.md                 <- stack details the scanner can't detect
+      adrs/                    <- architecture decision records
+      stories/                 <- story cards (US-N.md)
+      epics/                   <- epic cards (EPC-N.md)
+      velocity.md              <- sprint velocity history
     skills/
-      generated/               ← AI-generated skills (fh skills regen)
-      expert/                  ← 16 preinstalled expert skills
-      workflows/               ← MCP workflow skills
-    worktrees/                 ← isolated git worktrees (fh party run)
-    audit.log                  ← JSONL audit trail (fh security commands)
-    cost-config.yaml           ← spend limits (fh cost --limit/--alert)
-  AGENTS.md                    ← cross-tool agent standard
-  CLAUDE.md                    ← forgehive block inserted, rest preserved
+      generated/               <- AI-generated skills (fh skills regen)
+      expert/                  <- 16 preinstalled expert skills
+      workflows/               <- MCP workflow skills
+    worktrees/                 <- isolated git worktrees (fh party run)
+    runs/                      <- background agent output (fh run)
+    audit.log                  <- JSONL audit trail (fh security commands)
+    cost-config.yaml           <- spend limits (fh cost --limit/--alert)
+  AGENTS.md                    <- cross-tool agent standard
+  CLAUDE.md                    <- forgehive block inserted, rest preserved
 ```
 
 ---
@@ -520,7 +693,7 @@ The hook fires on every bash command execution in Claude Code and exits 1 if a m
 cd my-project
 fh init
 fh confirm
-# Open Claude Code → Claude now has full context
+# Open Claude Code -> Claude now has full context
 ```
 
 ### After adding new dependencies
@@ -539,6 +712,49 @@ fh security deps            # check for new CVEs in dependencies
 fh security report gdpr     # update compliance report
 ```
 
+### CI integration
+
+```bash
+fh ci --init                  # scaffold .github/workflows/forgehive.yml
+fh ci --format markdown --fail-on high   # use in existing CI scripts
+```
+
+### Generating onboarding documentation
+
+```bash
+fh map                        # review codebase structure
+fh onboard --output ONBOARDING.md   # generate onboarding document
+git add ONBOARDING.md
+git commit -m "docs: add forgehive-generated onboarding"
+```
+
+### Generating a changelog
+
+```bash
+fh changelog --since v0.6.0 --output CHANGELOG.md
+```
+
+### Sprint planning
+
+```bash
+# Set up your backlog
+fh epic create "User Authentication" --goal "Users can log in securely"
+fh story create "As a user I want to log in" --epic EPC-1 --points 3
+fh story create "As a user I want to reset my password" --epic EPC-1 --points 2
+
+# Check current velocity
+fh velocity show
+
+# Open Claude Code and run:
+# /fh-sprint
+# Claude reads velocity + backlog and suggests scope
+
+# At end of sprint
+fh velocity record sprint-1 --committed 13 --delivered 11
+fh story done US-1
+fh story done US-2
+```
+
 ### Sharing context with the team
 
 ```bash
@@ -548,6 +764,11 @@ git commit -m "chore: update shared forgehive context"
 
 # On another machine:
 fh memory snapshot import ./team-context.json
+
+# Or use the sync approach (no committed file):
+fh sync push --remote origin --branch forgehive-memory
+# teammate runs:
+fh sync pull --remote origin --branch forgehive-memory
 ```
 
 ### Starting a multi-agent build session
@@ -555,8 +776,8 @@ fh memory snapshot import ./team-context.json
 ```bash
 fh party --set build
 fh party run
-# → Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
-# → Each Claude Code session opens in its own isolated worktree
+# -> Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
+# -> Each Claude Code session opens in its own isolated worktree
 
 fh party status     # check what's running
 fh party cleanup    # clean up after the session
@@ -575,6 +796,14 @@ fh mcp auth add github GITHUB_TOKEN=ghp_...
 fh mcp auth list    # verify both services are stored
 ```
 
+### Running a background agent on an issue
+
+```bash
+fh run https://github.com/my-org/my-repo/issues/42 --agent kai
+# Kai reads the issue, applies forgehive context, works in background
+# Output streamed to stdout and saved to .forgehive/runs/
+```
+
 ---
 
 ## Configuration Files
@@ -613,13 +842,13 @@ Global credential store (chmod 600). Managed exclusively via `fh mcp auth` comma
 |---|---|
 | Runtime | Node.js ≥ 18, ESM |
 | Language | TypeScript |
-| Build | esbuild → `dist/cli.js` (~205 KB, single bundle) |
+| Build | esbuild -> `dist/cli.js` (~244 KB, single bundle) |
 | Type check | `tsc --noEmit` |
-| Tests | `node:test` (native) + tsx ESM loader, 217 tests |
+| Tests | `node:test` (native) + tsx ESM loader, 267 tests |
 | Dependencies | `js-yaml` (sole runtime dependency) |
 
 ```bash
-npm run build       # esbuild → dist/cli.js
+npm run build       # esbuild -> dist/cli.js
 npm run typecheck   # tsc --noEmit
 npm test            # node --import tsx/esm --test test/*.test.ts
 ```

package/dist/cli.js

@@ -2751,8 +2751,8 @@ var init_harness = __esm({
 
 // src/cli.ts
 init_js_yaml();
-import fs27 from "node:fs";
-import path28 from "node:path";
+import fs30 from "node:fs";
+import path31 from "node:path";
 
 // src/scanner.ts
 import fs from "node:fs";
@@ -6196,26 +6196,359 @@ function runBackgroundAgent(forgehiveDir2, issueUrl, agentId) {
   };
 }
 
+// src/stories.ts
+init_js_yaml();
+import fs27 from "node:fs";
+import path28 from "node:path";
+function nextStoryId(storiesDir) {
+  if (!fs27.existsSync(storiesDir)) return "US-1";
+  const existing = fs27.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) {
+  const frontmatter = jsYaml.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 `---
+${frontmatter}---
+
+# ${story.id}: ${story.title}
+
+## User Story
+
+Als **${story.asA}** m\xF6chte ich **${story.iWant}**, damit **${story.soThat}**.
+
+## Acceptance Criteria
+
+${acLines || "- [ ] (noch nicht definiert)"}
+`;
+}
+function parseStoryFile(filePath) {
+  try {
+    const content = fs27.readFileSync(filePath, "utf8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const data = jsYaml.load(match[1]);
+    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;
+  }
+}
+function createStory(storiesDir, title, epicId) {
+  fs27.mkdirSync(storiesDir, { recursive: true });
+  const id = nextStoryId(storiesDir);
+  const story = {
+    id,
+    title,
+    asA: "",
+    iWant: title,
+    soThat: "",
+    acceptanceCriteria: [],
+    points: null,
+    epicId: epicId ?? null,
+    status: "backlog"
+  };
+  fs27.writeFileSync(path28.join(storiesDir, `${id}.md`), storyToMarkdown(story), "utf8");
+  return story;
+}
+function listStories(storiesDir) {
+  if (!fs27.existsSync(storiesDir)) return [];
+  return fs27.readdirSync(storiesDir).filter((f) => f.match(/^US-\d+\.md$/)).map((f) => parseStoryFile(path28.join(storiesDir, f))).filter((s) => s !== null).sort((a, b) => {
+    const na = parseInt(a.id.replace("US-", ""), 10);
+    const nb = parseInt(b.id.replace("US-", ""), 10);
+    return na - nb;
+  });
+}
+function getStory(storiesDir, id) {
+  const filePath = path28.join(storiesDir, `${id}.md`);
+  if (!fs27.existsSync(filePath)) return null;
+  return parseStoryFile(filePath);
+}
+function updateStoryPoints(storiesDir, id, points) {
+  const story = getStory(storiesDir, id);
+  if (!story) throw new Error(`Story ${id} nicht gefunden`);
+  story.points = points;
+  fs27.writeFileSync(path28.join(storiesDir, `${id}.md`), storyToMarkdown(story), "utf8");
+}
+function updateStoryStatus(storiesDir, id, status) {
+  const story = getStory(storiesDir, id);
+  if (!story) throw new Error(`Story ${id} nicht gefunden`);
+  story.status = status;
+  fs27.writeFileSync(path28.join(storiesDir, `${id}.md`), storyToMarkdown(story), "utf8");
+}
+function formatStoryCard(story) {
+  const points = story.points !== null ? ` \xB7 ${story.points} Punkte` : "";
+  const epic = story.epicId ? ` \xB7 ${story.epicId}` : "";
+  const lines = [];
+  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\xF6chte 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");
+}
+
+// src/epics.ts
+init_js_yaml();
+import fs28 from "node:fs";
+import path29 from "node:path";
+function nextEpicId(epicsDir) {
+  if (!fs28.existsSync(epicsDir)) return "EPC-1";
+  const existing = fs28.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) {
+  const frontmatter = jsYaml.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 `---
+${frontmatter}---
+
+# ${epic.id}: ${epic.title}
+
+**Ziel:** ${epic.goal || "(noch nicht definiert)"}
+
+## Stories
+
+${storyLines || "(noch keine Stories)"}
+`;
+}
+function parseEpicFile(filePath) {
+  try {
+    const content = fs28.readFileSync(filePath, "utf8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const data = jsYaml.load(match[1]);
+    return {
+      id: data.id ?? "",
+      title: data.title ?? "",
+      goal: data.goal ?? "",
+      stories: data.stories ?? [],
+      status: data.status ?? "active"
+    };
+  } catch {
+    return null;
+  }
+}
+function createEpic(epicsDir, title, goal) {
+  fs28.mkdirSync(epicsDir, { recursive: true });
+  const id = nextEpicId(epicsDir);
+  const epic = { id, title, goal: goal ?? "", stories: [], status: "active" };
+  fs28.writeFileSync(path29.join(epicsDir, `${id}.md`), epicToMarkdown(epic), "utf8");
+  return epic;
+}
+function listEpics(epicsDir) {
+  if (!fs28.existsSync(epicsDir)) return [];
+  return fs28.readdirSync(epicsDir).filter((f) => f.match(/^EPC-\d+\.md$/)).map((f) => parseEpicFile(path29.join(epicsDir, f))).filter((e) => e !== null).sort((a, b) => {
+    const na = parseInt(a.id.replace("EPC-", ""), 10);
+    const nb = parseInt(b.id.replace("EPC-", ""), 10);
+    return na - nb;
+  });
+}
+function getEpic(epicsDir, id) {
+  const filePath = path29.join(epicsDir, `${id}.md`);
+  if (!fs28.existsSync(filePath)) return null;
+  return parseEpicFile(filePath);
+}
+function formatEpicCard(epic, stories) {
+  const lines = [];
+  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} \u2014 ${s.title} [${s.status}]`);
+    }
+  } else if (epic.stories.length > 0) {
+    for (const id of epic.stories) lines.push(`  - ${id}`);
+  }
+  return lines.join("\n");
+}
+
+// src/velocity.ts
+import fs29 from "node:fs";
+import path30 from "node:path";
+var HEADER = "# Sprint Velocity\n\n| Sprint | Datum | Committed | Delivered | Rate |\n|---|---|---|---|---|\n";
+function recordVelocity(velocityFile, sprint, committed, delivered) {
+  const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const rate = committed > 0 ? Math.round(delivered / committed * 100) : 0;
+  const row = `| Sprint ${sprint} | ${date} | ${committed} | ${delivered} | ${rate}% |
+`;
+  if (!fs29.existsSync(velocityFile)) {
+    fs29.mkdirSync(path30.dirname(velocityFile), { recursive: true });
+    fs29.writeFileSync(velocityFile, HEADER + row, "utf8");
+  } else {
+    fs29.appendFileSync(velocityFile, row, "utf8");
+  }
+}
+function getVelocityHistory(velocityFile) {
+  if (!fs29.existsSync(velocityFile)) return [];
+  const content = fs29.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);
+}
+function getRollingAverage(history, window = 3) {
+  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);
+}
+function formatVelocityReport(history) {
+  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 = [];
+  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\xFCr n\xE4chsten Sprint:** ~${avg3} Punkte einplanen`);
+  return lines.join("\n");
+}
+
 // src/cli.ts
 var [, , command, subcommand, ...rest] = process.argv;
 var projectRoot = process.cwd();
-var forgehiveDir = path28.join(projectRoot, ".forgehive");
+var forgehiveDir = path31.join(projectRoot, ".forgehive");
 if (command === "--version" || command === "-v") {
-  console.log("0.7.0");
+  console.log("0.7.2");
+  process.exit(0);
+}
+if (command === "--help" || command === "-h" || command === "help") {
+  console.log(`
+forgehive v0.7.2 \u2014 Context-aware AI development environment
+
+USAGE
+  fh <command> [subcommand] [options]
+
+SETUP
+  fh init                          Set up forgehive in the current project
+  fh confirm                       Activate capabilities (draft \u2192 confirmed)
+  fh rollback                      Remove forgehive from the project
+  fh status                        Show current project state
+  fh scan --update                 Re-scan project after changes
+  fh scan --check                  Check if scan is still current
+
+SECURITY
+  fh security scan                 Secrets + SAST scan
+  fh security deps                 CVE check (npm audit)
+  fh security report [gdpr|soc2|hipaa]  Compliance report
+  fh security audit                Show audit trail
+  fh security permissions          Show agent file permissions
+
+CI
+  fh ci                            Run CI health report
+  fh ci --format json|markdown     Output format
+  fh ci --fail-on critical|high|any  Failure threshold
+  fh ci --init                     Generate GitHub Actions workflow
+
+CODEBASE
+  fh map                           Codebase structure map
+  fh onboard [--output path]       Generate ONBOARDING.md
+  fh changelog [--since tag]       Semantic changelog from git
+  fh metrics [--since date]        Developer productivity metrics
+
+SPRINT PLANNING
+  fh story create <title> [--epic EPC-N] [--points N]
+  fh story list [--epic EPC-N]
+  fh story show <US-N>
+  fh story sprint <US-N>           Mark story as in-sprint
+  fh story done <US-N> [--points N]
+  fh epic create <title> [--goal <text>]
+  fh epic list
+  fh epic show <EPC-N>
+  fh velocity show                 Velocity history + rolling average
+  fh velocity record <N> --committed N --delivered N
+
+TEAM
+  fh sync push|pull [--remote origin --branch forgehive-memory]
+  fh run <issue-url> [--agent name] [--label label]
+  fh memory show|clean|export|prune|snapshot
+  fh memory adr list|"<title>"
+
+AGENTS & MCP
+  fh party [--set name|run|status|cleanup]
+  fh wire <service>                Configure MCP server
+  fh mcp auth add|list|remove      Manage credentials
+  fh mcp search <query>            Search MCP registry
+  fh skills list|regen|pull <url>
+
+COST
+  fh cost [today|week|all]
+  fh cost --limit N --alert N
+
+  fh --version                     Show version
+  fh --help                        Show this help
+`);
   process.exit(0);
 }
 function loadClaudeMdBlock() {
-  const templatePath = path28.join(
-    path28.dirname(new URL(import.meta.url).pathname),
+  const templatePath = path31.join(
+    path31.dirname(new URL(import.meta.url).pathname),
     "..",
     "forgehive",
     "templates",
     "claude-md.block.md"
   );
-  if (!fs27.existsSync(templatePath)) return "## forgehive\n\nSee .forgehive/ for configuration.";
-  return fs27.readFileSync(templatePath, "utf8");
+  if (!fs30.existsSync(templatePath)) return "## forgehive\n\nSee .forgehive/ for configuration.";
+  return fs30.readFileSync(templatePath, "utf8");
 }
 if (command === "init") {
+  const forgehiveDirExists = fs30.existsSync(forgehiveDir);
+  if (forgehiveDirExists && !rest.includes("--force")) {
+    console.log(`\u26A0 .forgehive/ existiert bereits in diesem Projekt.`);
+    console.log(`  Nutze 'fh init --force' um neu zu initialisieren (\xFCberschreibt capabilities.yaml).`);
+    console.log(`  Nutze 'fh scan --update' um nur den Scan zu aktualisieren.`);
+    process.exit(0);
+  }
   console.log("\u{1F50D} Analysiere Projekt...\n");
   const scanResult = scan(projectRoot);
   const tierCount = [1, 2, 3].map((t) => scanResult.signals.filter((s) => s.tier === t).length);
@@ -6227,9 +6560,9 @@ if (command === "init") {
   const block = loadClaudeMdBlock();
   writeForgehiveDir(projectRoot, scanResult, capMap, block);
   const hash = computeHash(projectRoot);
-  fs27.writeFileSync(path28.join(forgehiveDir, ".scan-hash"), hash, "utf8");
-  const runtimeDir = path28.join(
-    path28.dirname(new URL(import.meta.url).pathname),
+  fs30.writeFileSync(path31.join(forgehiveDir, ".scan-hash"), hash, "utf8");
+  const runtimeDir = path31.join(
+    path31.dirname(new URL(import.meta.url).pathname),
     "..",
     "forgehive"
   );
@@ -6261,7 +6594,7 @@ if (command === "init") {
     process.exit(1);
   }
 } else if (command === "memory") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6270,7 +6603,7 @@ if (command === "init") {
   } else if (subcommand === "clean") {
     cleanMemory(forgehiveDir);
   } else if (subcommand === "export") {
-    const outputPath = rest[0] ?? path28.join(projectRoot, "forgehive-memory-export.md");
+    const outputPath = rest[0] ?? path31.join(projectRoot, "forgehive-memory-export.md");
     try {
       exportMemory(forgehiveDir, outputPath);
     } catch (err) {
@@ -6318,7 +6651,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
   } else if (subcommand === "snapshot") {
     const snapAction = rest[0];
     if (snapAction === "export") {
-      const outPath = rest[1] ?? path28.join(
+      const outPath = rest[1] ?? path31.join(
         projectRoot,
         `forgehive-snapshot-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}.json`
       );
@@ -6358,11 +6691,11 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     process.exit(1);
   }
 } else if (command === "scan" && subcommand === "--update") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
-  const savedHash = fs27.existsSync(path28.join(forgehiveDir, ".scan-hash")) ? fs27.readFileSync(path28.join(forgehiveDir, ".scan-hash"), "utf8").trim() : null;
+  const savedHash = fs30.existsSync(path31.join(forgehiveDir, ".scan-hash")) ? fs30.readFileSync(path31.join(forgehiveDir, ".scan-hash"), "utf8").trim() : null;
   const currentHash = computeHash(projectRoot);
   if (savedHash === currentHash) {
     console.log("\u2713 Keine \xC4nderungen erkannt \u2014 capabilities.yaml ist aktuell");
@@ -6370,7 +6703,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
   }
   console.log("\u{1F50D} \xC4nderungen erkannt \u2014 scanne erneut...\n");
   const oldDoc = jsYaml.load(
-    fs27.readFileSync(path28.join(forgehiveDir, "capabilities.yaml"), "utf8")
+    fs30.readFileSync(path31.join(forgehiveDir, "capabilities.yaml"), "utf8")
   );
   const oldMap = { confirmed: oldDoc.capabilities.confirmed ?? [], inferred: [] };
   const scanResult = scan(projectRoot);
@@ -6390,16 +6723,16 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     console.log();
     const block = loadClaudeMdBlock();
     writeForgehiveDir(projectRoot, scanResult, newMap, block);
-    fs27.writeFileSync(path28.join(forgehiveDir, ".scan-hash"), currentHash, "utf8");
+    fs30.writeFileSync(path31.join(forgehiveDir, ".scan-hash"), currentHash, "utf8");
     console.log("\u2713 scan-result.yaml und capabilities.yaml aktualisiert");
     console.log("  F\xFChre `fh confirm` aus um die \xC4nderungen zu best\xE4tigen");
   }
 } else if (command === "scan" && subcommand === "--check") {
-  if (!fs27.existsSync(path28.join(forgehiveDir, ".scan-hash"))) {
+  if (!fs30.existsSync(path31.join(forgehiveDir, ".scan-hash"))) {
     console.log("Warnung: Kein Scan-Hash gefunden. F\xFChre `fh init` aus.");
     process.exit(1);
   }
-  const saved = fs27.readFileSync(path28.join(forgehiveDir, ".scan-hash"), "utf8").trim();
+  const saved = fs30.readFileSync(path31.join(forgehiveDir, ".scan-hash"), "utf8").trim();
   const current = computeHash(projectRoot);
   if (saved !== current) {
     console.log("\u26A0 Codebase hat sich seit letztem Scan ge\xE4ndert.");
@@ -6408,7 +6741,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
   }
   console.log("\u2713 capabilities.yaml ist aktuell");
 } else if (command === "skills") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6444,7 +6777,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     process.exit(1);
   }
 } else if (command === "party") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6565,7 +6898,7 @@ Ausf\xFChren mit --remove um zu l\xF6schen: fh memory prune ${days} --remove`);
     }
   }
 } else if (command === "wire") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6604,7 +6937,7 @@ N\xE4chster Schritt: Setze die erforderlichen Umgebungsvariablen und starte Clau
   const limitIdx = allArgs.indexOf("--limit");
   const alertIdx = allArgs.indexOf("--alert");
   if (limitIdx !== -1) {
-    if (!fs27.existsSync(forgehiveDir)) {
+    if (!fs30.existsSync(forgehiveDir)) {
       console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
       process.exit(1);
     }
@@ -6630,14 +6963,14 @@ N\xE4chster Schritt: Setze die erforderlichen Umgebungsvariablen und starte Clau
     }
     const sessions = parseCostSessions(projectRoot);
     console.log(formatCostReport(sessions, range));
-    if (fs27.existsSync(forgehiveDir)) {
+    if (fs30.existsSync(forgehiveDir)) {
       const total = sessions.reduce((s, x) => s + x.estimatedCostUsd, 0);
       const status = checkSpendStatus(forgehiveDir, total);
       if (status.message) console.log("\n" + status.message);
     }
   }
 } else if (command === "watch") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6653,7 +6986,7 @@ N\xE4chster Schritt: Setze die erforderlichen Umgebungsvariablen und starte Clau
     process.exit(0);
   });
 } else if (command === "mcp") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6764,7 +7097,7 @@ Setze diese Umgebungsvariablen:`);
     process.exit(1);
   }
 } else if (command === "security") {
-  if (!fs27.existsSync(forgehiveDir)) {
+  if (!fs30.existsSync(forgehiveDir)) {
     console.error("Fehler: .forgehive/ nicht gefunden \u2014 f\xFChre zuerst `fh init` aus");
     process.exit(1);
   }
@@ -6850,8 +7183,8 @@ Setze diese Umgebungsvariablen:`);
 `);
     const report = generateSecurityReport(projectRoot, forgehiveDir, mode);
     const text = formatSecurityReport(report);
-    const reportPath = path28.join(forgehiveDir, "security-report.md");
-    fs27.writeFileSync(reportPath, text, "utf8");
+    const reportPath = path31.join(forgehiveDir, "security-report.md");
+    fs30.writeFileSync(reportPath, text, "utf8");
     console.log(text);
     console.log(`
 \u2713 Report gespeichert: ${reportPath}`);
@@ -6863,8 +7196,8 @@ Setze diese Umgebungsvariablen:`);
   } else if (subcommand === "permissions") {
     const { writePermissions: writePermissions2 } = await Promise.resolve().then(() => (init_harness(), harness_exports));
     writePermissions2(forgehiveDir);
-    const permPath = path28.join(forgehiveDir, "harness", "permissions.yaml");
-    console.log(fs27.readFileSync(permPath, "utf8"));
+    const permPath = path31.join(forgehiveDir, "harness", "permissions.yaml");
+    console.log(fs30.readFileSync(permPath, "utf8"));
   } else {
     console.error(`Unbekannter security-Subcommand: ${subcommand}`);
     console.error("Verf\xFCgbar: scan | deps | audit | report [gdpr|soc2|hipaa|none] | permissions");
@@ -6876,35 +7209,35 @@ Setze diese Umgebungsvariablen:`);
   const failOnArg = allCiArgs.includes("--fail-on") ? allCiArgs[allCiArgs.indexOf("--fail-on") + 1] : "high";
   const initFlag = allCiArgs.includes("--init");
   if (initFlag) {
-    const ghDir = path28.join(projectRoot, ".github", "workflows");
-    fs27.mkdirSync(ghDir, { recursive: true });
-    const outPath = path28.join(ghDir, "forgehive.yml");
-    fs27.writeFileSync(outPath, getGithubActionsTemplate(), "utf8");
+    const ghDir = path31.join(projectRoot, ".github", "workflows");
+    fs30.mkdirSync(ghDir, { recursive: true });
+    const outPath = path31.join(ghDir, "forgehive.yml");
+    fs30.writeFileSync(outPath, getGithubActionsTemplate(), "utf8");
     console.log(`\u2714 GitHub Actions workflow geschrieben: ${outPath}`);
   } else {
     const report = generateCiReport(projectRoot, forgehiveDir, failOnArg);
     const output = formatCiReport(report, format);
     console.log(output);
     if (format === "json") {
-      fs27.mkdirSync(forgehiveDir, { recursive: true });
-      fs27.writeFileSync(path28.join(forgehiveDir, "ci-report.json"), output, "utf8");
+      fs30.mkdirSync(forgehiveDir, { recursive: true });
+      fs30.writeFileSync(path31.join(forgehiveDir, "ci-report.json"), output, "utf8");
     }
     if (report.status === "fail") process.exit(1);
   }
 } else if (command === "map") {
   const map2 = generateMap(projectRoot);
   const md = formatMap(map2);
-  const mapPath = path28.join(forgehiveDir, "map.md");
-  fs27.mkdirSync(forgehiveDir, { recursive: true });
-  fs27.writeFileSync(mapPath, md, "utf8");
+  const mapPath = path31.join(forgehiveDir, "map.md");
+  fs30.mkdirSync(forgehiveDir, { recursive: true });
+  fs30.writeFileSync(mapPath, md, "utf8");
   console.log(md);
   console.log(`
 \u2714 Codebase-Map gespeichert: ${mapPath}`);
 } else if (command === "onboard") {
   const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
-  const outputPath = outputArg ?? path28.join(projectRoot, "ONBOARDING.md");
+  const outputPath = outputArg ?? path31.join(projectRoot, "ONBOARDING.md");
   const doc = generateOnboardingDoc(projectRoot, forgehiveDir);
-  fs27.writeFileSync(outputPath, doc, "utf8");
+  fs30.writeFileSync(outputPath, doc, "utf8");
   console.log(`\u2714 Onboarding-Dokument geschrieben: ${outputPath}`);
 } else if (command === "changelog") {
   const sinceArg = rest.includes("--since") ? rest[rest.indexOf("--since") + 1] : null;
@@ -6914,28 +7247,28 @@ Setze diese Umgebungsvariablen:`);
   const commits = parseGitLog(rawLog);
   let version = "unreleased";
   try {
-    const pkgPath = path28.join(projectRoot, "package.json");
-    if (fs27.existsSync(pkgPath)) {
-      const pkg = JSON.parse(fs27.readFileSync(pkgPath, "utf8").replace(/^\s*\/\/.*$/gm, ""));
+    const pkgPath = path31.join(projectRoot, "package.json");
+    if (fs30.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs30.readFileSync(pkgPath, "utf8").replace(/^\s*\/\/.*$/gm, ""));
       version = pkg.version ?? "unreleased";
     }
   } catch {
   }
   const md = formatChangelog(commits, version);
-  const outputPath = outputArg ?? path28.join(projectRoot, "CHANGELOG.md");
+  const outputPath = outputArg ?? path31.join(projectRoot, "CHANGELOG.md");
   let existing = "";
-  if (fs27.existsSync(outputPath)) existing = fs27.readFileSync(outputPath, "utf8");
-  fs27.writeFileSync(outputPath, md + "\n\n" + existing, "utf8");
+  if (fs30.existsSync(outputPath)) existing = fs30.readFileSync(outputPath, "utf8");
+  fs30.writeFileSync(outputPath, md + "\n\n" + existing, "utf8");
   console.log(`\u2714 CHANGELOG.md aktualisiert: ${outputPath}`);
   console.log(`  ${commits.length} Commits verarbeitet`);
 } else if (command === "metrics") {
   const sinceArg = rest.includes("--since") ? rest[rest.indexOf("--since") + 1] : void 0;
   const rawLog = getMetricsGitLog(projectRoot, sinceArg);
   const stats = parseCommitStats(rawLog);
-  const md = formatMetrics(stats, path28.basename(projectRoot));
-  const metricsPath = path28.join(forgehiveDir, "metrics.md");
-  fs27.mkdirSync(forgehiveDir, { recursive: true });
-  fs27.writeFileSync(metricsPath, md, "utf8");
+  const md = formatMetrics(stats, path31.basename(projectRoot));
+  const metricsPath = path31.join(forgehiveDir, "metrics.md");
+  fs30.mkdirSync(forgehiveDir, { recursive: true });
+  fs30.writeFileSync(metricsPath, md, "utf8");
   console.log(md);
   console.log(`
 \u2714 Metrics gespeichert: ${metricsPath}`);
@@ -6969,10 +7302,125 @@ Setze diese Umgebungsvariablen:`);
   const result = runBackgroundAgent(forgehiveDir, issueUrl, agentId);
   console.log(`\u2714 ${result.message}`);
   console.log(`  fh run status   \u2014 aktive Sessions anzeigen`);
+} else if (command === "story") {
+  const storiesDir = path31.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] : void 0;
+    const pointsArg = rest.includes("--points") ? parseInt(rest[rest.indexOf("--points") + 1], 10) : void 0;
+    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(`\u2714 ${story.id} erstellt: ${path31.join(storiesDir, story.id + ".md")}`);
+    console.log(`  Bearbeite die Datei um Acceptance Criteria hinzuzuf\xFCgen.`);
+  } 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} \u2014 ${s.title} [${s.status}]`);
+      }
+    }
+  } else if (subcommand === "done") {
+    const id = rest[0];
+    const pointsArg = rest.includes("--points") ? parseInt(rest[rest.indexOf("--points") + 1], 10) : void 0;
+    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(`\u2714 ${id} als done markiert`);
+  } else if (subcommand === "sprint") {
+    const id = rest[0];
+    if (!id) {
+      console.error("Usage: fh story sprint <US-N>");
+      process.exit(1);
+    }
+    updateStoryStatus(storiesDir, id, "in-sprint");
+    console.log(`\u2714 ${id} in Sprint gezogen`);
+  } 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\xFCgbar: fh story create | list | show | done");
+  }
+} else if (command === "epic") {
+  const epicsDir = path31.join(forgehiveDir, "memory", "epics");
+  const storiesDir = path31.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] : void 0;
+    if (!title) {
+      console.error("Usage: fh epic create <titel> [--goal <ziel>]");
+      process.exit(1);
+    }
+    const epic = createEpic(epicsDir, title, goalArg);
+    console.log(`\u2714 ${epic.id} erstellt: ${path31.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} \u2014 ${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\xFCgbar: fh epic create | list | show");
+  }
+} else if (command === "velocity") {
+  const velocityFile = path31.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(`\u2714 Sprint ${sprintNum} gespeichert. Rolling Average: ${avg} Punkte`);
+  } else if (!subcommand || subcommand === "show") {
+    const history = getVelocityHistory(velocityFile);
+    console.log(formatVelocityReport(history));
+  } else {
+    console.error("Verf\xFCgbar: fh velocity show | record <N> --committed N --delivered N");
+  }
 } else {
-  const cmd = [command, subcommand].filter(Boolean).join(" ") || "(kein)";
-  console.error(`Unbekannter Befehl: ${cmd}`);
-  console.error("Verf\xFCgbar: init | confirm | rollback | scan --update | scan --check | status | ci [--format json|markdown] [--fail-on critical|high|any] [--init] | map | onboard [--output path] | changelog [--since tag] | metrics [--since date] | sync [push|pull] [--remote origin --branch forgehive-memory] | run <issue-url> [--agent <name>] | cost [today|week|all] | cost --limit N --alert N | memory [show|clean|export|prune|snapshot] | memory adr [list|<titel>] | skills [list|regen|pull <url>] | party [--set <name>|run|status|cleanup] | wire <service> | mcp [auth|search|add] | security [scan|deps|report|audit|permissions]");
+  console.error("Unbekannter Befehl: " + command);
+  console.error("Verf\xFCgbar: init | confirm | rollback | scan | status | ci | map | onboard | changelog | metrics | story [create|list|show|sprint|done] | epic [create|list|show] | velocity [show|record] | sync [push|pull] | run <issue-url> | cost | memory | skills | party | wire | mcp | security");
+  console.error("Hilfe: fh --help");
   process.exit(1);
 }
 /*! Bundled license information:

package/forgehive/commands/fh-sprint.md

@@ -7,11 +7,15 @@ You are running a Sprint Planning session using the ForgeHive workflow.
 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. Run `fh scan --check` to verify the codebase snapshot is current
+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 — ein Item pro Zeile. Oder soll ich Linear/Jira laden?"**
+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:
@@ -25,7 +29,7 @@ Show the fetched issues and ask: **"Welche davon kommen in den Sprint?"**
 gh issue list --state open --label "sprint-candidate" --limit 20
 ```
 
-**If no MCP connected:**
+**If no stories/MCP:**
 Accept free-text input — one item per line.
 
 ### Step 3: Clarify and refine
@@ -37,44 +41,59 @@ For each item, ask one clarifying question if needed:
 
 Do NOT ask more than one question per item. If the item is clear, skip this step.
 
-### Step 4: Estimate effort
+### Step 4: Estimate with Fibonacci Points
 
-Estimate each item using T-shirt sizes:
+Estimate each item using Fibonacci story points:
 
-| Size | Meaning | Typical scope |
+| Points | Meaning | Typical scope |
 |---|---|---|
-| XS | < 2h | Config change, copy fix, small bug |
-| S | half day | Simple feature, isolated fix |
-| M | 1–2 days | Feature with tests, moderate complexity |
-| L | 3–5 days | Complex feature, multiple files, integration work |
-| XL | > 5 days | Should be broken down further |
+| 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 XL items: **"Dieses Item ist zu groß für einen Sprint — soll ich es aufteilen?"**
+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  
+**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
 
-Ask: **"Wie viele Entwickler-Tage habt ihr im Sprint?"** (default: 10 days for a 2-week sprint with one developer)
+Show velocity hint if available:
+```bash
+fh velocity show
+```
+
+Ask: **"Wie viele Punkte habt ihr im Sprint?"**
 
-Calculate if the Must + Should items fit. If they don't, move the lowest-priority Should items to Could.
+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: 10 Tage
-Must:   [sum] Tage
-Should: [sum] Tage  
-Could:  [sum] Tage
-─────────────────
-Geplant: [must+should] / 10 Tage
+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
@@ -86,16 +105,16 @@ Write the sprint plan to `.forgehive/memory/sprint.md` in this format:
 
 **Ziel:** [one sentence sprint goal]
 
-**Kapazität:** [X] Entwickler-Tage
+**Kapazität:** [X] Punkte
 
 ## Must
-- [ ] [Item] ([size]) — [one-line description]
+- [ ] [ID] [Item] ([points]pt) — [one-line description]
 
-## Should  
-- [ ] [Item] ([size]) — [one-line description]
+## Should
+- [ ] [ID] [Item] ([points]pt) — [one-line description]
 
 ## Could
-- [ ] [Item] ([size]) — [one-line description]
+- [ ] [ID] [Item] ([points]pt) — [one-line description]
 
 ## Offen / Blocked
 - [any blocked items with reason]
@@ -104,10 +123,25 @@ Write the sprint plan to `.forgehive/memory/sprint.md` in this format:
 *Erstellt mit fh sprint — [timestamp]*
 ```
 
-Confirm with the user: **"Sprint Plan gespeichert in `.forgehive/memory/sprint.md`. Soll ich für jedes Must-Item direkt einen Branch anlegen?"**
+Confirm with the user: **"Sprint Plan gespeichert. Soll ich für jedes Must-Item direkt einen Branch anlegen?"**
 
-If yes: create branches for each Must item following the `git-conventions` skill (`feat/<slug>`, `fix/<slug>`, `chore/<slug>`).
+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 so Claude knows the current focus in every future session.
+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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgehive",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Context-aware AI development environment — one binary, your stack.",
   "type": "module",
   "bin": {