forgehive 0.7.7 → 0.7.8

package/docs/superpowers/plans/2026-05-14-v07-nextgen.md

@@ -1,1980 +0,0 @@
-# forgehive v0.7 — NextGen Gap Closure Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Close all competitive gaps identified in the v0.7 analysis — CI/PR integration, codebase map, onboarding docs, changelog, metrics, team sync, background agents, slash commands, and multi-model routing.
-
-**Architecture:** Each new feature is a self-contained TypeScript module in `src/` with a corresponding test file in `test/`. The `src/cli.ts` file is wired to call each module. Slash commands are pure Markdown files in `forgehive/commands/`. All tests use `node:test` + `node:assert/strict` with tmpdir isolation.
-
-**Tech Stack:** TypeScript ESM, Node.js ≥ 18, `node:child_process` (spawnSync/spawn), `node:fs`, `node:path`, `node:os` — no new runtime dependencies.
-
----
-
-## File Map
-
-**New source files:**
-- `src/ci.ts` — CI report generation + GitHub Actions template
-- `src/map.ts` — codebase structure map (file tree + imports)
-- `src/onboard.ts` — onboarding document generator
-- `src/changelog.ts` — semantic changelog from git log
-- `src/metrics.ts` — developer productivity metrics from git
-- `src/sync.ts` — team context sync via git branch
-- `src/background.ts` — background agent execution via `claude -p`
-
-**New test files:**
-- `test/ci.test.ts`
-- `test/map.test.ts`
-- `test/onboard.test.ts`
-- `test/changelog.test.ts`
-- `test/metrics.test.ts`
-- `test/sync.test.ts`
-- `test/background.test.ts`
-
-**New command files (Markdown only):**
-- `forgehive/commands/fh-deploy.md`
-- `forgehive/commands/fh-test-this.md`
-- `forgehive/commands/fh-docs.md`
-
-**Modified files:**
-- `forgehive/commands/fh-sprint.md` — add MCP Linear/Jira integration
-- `forgehive/party/defaults.yaml` — add `model` field per agent set
-- `src/cli.ts` — wire all new commands + fix version string to 0.7.0
-- `package.json` — version 0.7.0
-
----
-
-## Task 1: CI Report Module (`src/ci.ts`)
-
-**Files:**
-- Create: `src/ci.ts`
-- Create: `test/ci.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/ci.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 { generateCiReport, formatCiReport, getGithubActionsTemplate } from "../src/ci.ts";
-
-describe("generateCiReport()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-ci-"));
-    fs.mkdirSync(path.join(tmpDir, ".forgehive"), { recursive: true });
-    fs.mkdirSync(path.join(tmpDir, "src"), { recursive: true });
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("returns pass status for a clean project", () => {
-    fs.writeFileSync(path.join(tmpDir, "src", "index.ts"), 'export const x = 1;\n', "utf8");
-    const report = generateCiReport(tmpDir, path.join(tmpDir, ".forgehive"));
-    assert.equal(report.status, "pass");
-    assert.equal(report.secrets.length, 0);
-    assert.equal(report.failedOn, null);
-  });
-
-  it("returns fail status when secrets found", () => {
-    fs.writeFileSync(
-      path.join(tmpDir, "src", "config.ts"),
-      'const token = "ghp_XFAKEX1234567890abcdefghijklmnopqrstu";\n',
-      "utf8"
-    );
-    const report = generateCiReport(tmpDir, path.join(tmpDir, ".forgehive"));
-    assert.equal(report.status, "fail");
-    assert.ok(report.failedOn !== null);
-  });
-
-  it("formatCiReport json produces valid JSON", () => {
-    fs.writeFileSync(path.join(tmpDir, "src", "index.ts"), "export const x = 1;\n", "utf8");
-    const report = generateCiReport(tmpDir, path.join(tmpDir, ".forgehive"));
-    const json = formatCiReport(report, "json");
-    assert.doesNotThrow(() => JSON.parse(json));
-  });
-
-  it("formatCiReport markdown includes status", () => {
-    fs.writeFileSync(path.join(tmpDir, "src", "index.ts"), "export const x = 1;\n", "utf8");
-    const report = generateCiReport(tmpDir, path.join(tmpDir, ".forgehive"));
-    const md = formatCiReport(report, "markdown");
-    assert.ok(md.includes("PASS") || md.includes("FAIL"));
-  });
-
-  it("getGithubActionsTemplate returns valid YAML string", () => {
-    const yaml = getGithubActionsTemplate();
-    assert.ok(yaml.includes("forgehive CI"));
-    assert.ok(yaml.includes("fh ci"));
-    assert.ok(yaml.includes("actions/checkout"));
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-cd /home/stefan/projekte/forgehive
-node --import tsx/esm --test test/ci.test.ts
-```
-Expected: FAIL — `Cannot find module '../src/ci.ts'`
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/ci.ts
-import fs from "node:fs";
-import path from "node:path";
-import {
-  scanSecrets,
-  scanSast,
-  scanDeps,
-  type SecretFinding,
-  type SastFinding,
-  type DepVulnerability,
-} from "./security-scan.ts";
-
-export interface CiReport {
-  timestamp: string;
-  project: string;
-  status: "pass" | "fail";
-  secrets: SecretFinding[];
-  sast: SastFinding[];
-  deps: DepVulnerability[];
-  failedOn: string | null;
-}
-
-export function generateCiReport(
-  projectRoot: string,
-  forgehiveDir: string,
-  failOn: "critical" | "high" | "any" = "high"
-): CiReport {
-  const secrets = scanSecrets(projectRoot);
-  const sast = scanSast(projectRoot);
-  const deps = scanDeps(projectRoot);
-
-  let failedOn: string | null = null;
-
-  if (secrets.length > 0) {
-    failedOn = "secrets";
-  } else if (
-    failOn === "critical" &&
-    (sast.some((f) => f.severity === "CRITICAL") ||
-      deps.some((d) => d.severity === "critical"))
-  ) {
-    failedOn = "critical-severity";
-  } else if (
-    failOn === "high" &&
-    (sast.some((f) => f.severity === "CRITICAL" || f.severity === "HIGH") ||
-      deps.some((d) => d.severity === "critical" || d.severity === "high"))
-  ) {
-    failedOn = "high-severity";
-  } else if (failOn === "any" && (sast.length > 0 || deps.length > 0)) {
-    failedOn = "findings";
-  }
-
-  return {
-    timestamp: new Date().toISOString(),
-    project: path.basename(projectRoot),
-    status: failedOn ? "fail" : "pass",
-    secrets,
-    sast,
-    deps,
-    failedOn,
-  };
-}
-
-export function formatCiReport(
-  report: CiReport,
-  format: "json" | "markdown" = "markdown"
-): string {
-  if (format === "json") return JSON.stringify(report, null, 2);
-
-  const lines: string[] = [];
-  lines.push("# forgehive CI Report");
-  lines.push(`**Project:** ${report.project}`);
-  lines.push(
-    `**Status:** ${report.status === "pass" ? "✅ PASS" : "❌ FAIL"}`
-  );
-  lines.push(`**Time:** ${report.timestamp}`);
-  lines.push("");
-
-  if (report.secrets.length > 0) {
-    lines.push("## Secrets Found");
-    for (const s of report.secrets)
-      lines.push(
-        `- **${s.patternName}** in \`${s.file}:${s.line}\` — \`${s.match}\``
-      );
-    lines.push("");
-  }
-
-  if (report.sast.length > 0) {
-    lines.push("## SAST Findings");
-    for (const f of report.sast)
-      lines.push(
-        `- **${f.severity}** \`${f.ruleId}\` in \`${f.file}:${f.line}\` — ${f.snippet.slice(0, 80)}`
-      );
-    lines.push("");
-  }
-
-  if (report.deps.length > 0) {
-    lines.push("## Dependency Vulnerabilities");
-    for (const d of report.deps)
-      lines.push(
-        `- **${d.severity}** ${d.name}@${d.version} — ${d.advisory}`
-      );
-    lines.push("");
-  }
-
-  if (report.status === "pass") lines.push("✅ All checks passed.");
-
-  return lines.join("\n");
-}
-
-export function getGithubActionsTemplate(): string {
-  return `name: forgehive CI
-
-on:
-  pull_request:
-    branches: [main, master]
-  push:
-    branches: [main, master]
-
-jobs:
-  security:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - run: npm install -g forgehive
-      - run: fh ci --format json --fail-on high
-      - name: Upload CI report
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: forgehive-ci-report
-          path: .forgehive/ci-report.json
-`;
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/ci.test.ts
-```
-Expected: 5 passing
-
-- [ ] **Step 5: Wire `fh ci` into cli.ts**
-
-Add import at top of `src/cli.ts`:
-```typescript
-import { generateCiReport, formatCiReport, getGithubActionsTemplate } from "./ci.ts";
-```
-
-Add command handler before the `} else {` catch-all block:
-
-```typescript
-} else if (command === "ci") {
-  const format = rest.includes("--format") ? rest[rest.indexOf("--format") + 1] as "json" | "markdown" : "markdown";
-  const failOnArg = rest.includes("--fail-on") ? rest[rest.indexOf("--fail-on") + 1] as "critical" | "high" | "any" : "high";
-  const initFlag = rest.includes("--init");
-
-  if (initFlag) {
-    const ghDir = path.join(projectRoot, ".github", "workflows");
-    fs.mkdirSync(ghDir, { recursive: true });
-    const outPath = path.join(ghDir, "forgehive.yml");
-    fs.writeFileSync(outPath, getGithubActionsTemplate(), "utf8");
-    console.log(`✔ GitHub Actions workflow geschrieben: ${outPath}`);
-  } else {
-    const report = generateCiReport(projectRoot, forgehiveDir, failOnArg);
-    const output = formatCiReport(report, format);
-    console.log(output);
-    if (format === "json") {
-      fs.mkdirSync(forgehiveDir, { recursive: true });
-      fs.writeFileSync(path.join(forgehiveDir, "ci-report.json"), output, "utf8");
-    }
-    if (report.status === "fail") process.exit(1);
-  }
-```
-
-Also update the help text at the end of cli.ts to add `ci [--format json|markdown] [--fail-on critical|high|any] [--init]`.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/ci.ts test/ci.test.ts src/cli.ts
-git commit -m "feat: add fh ci command with GitHub Actions template"
-```
-
----
-
-## Task 2: Codebase Map (`src/map.ts`)
-
-**Files:**
-- Create: `src/map.ts`
-- Create: `test/map.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/map.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 { generateMap, formatMap } from "../src/map.ts";
-
-describe("generateMap()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-map-"));
-    fs.mkdirSync(path.join(tmpDir, "src"), { recursive: true });
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("returns file list for a project with source files", () => {
-    fs.writeFileSync(path.join(tmpDir, "src", "a.ts"), 'import { b } from "./b.ts";\n', "utf8");
-    fs.writeFileSync(path.join(tmpDir, "src", "b.ts"), "export const b = 1;\n", "utf8");
-    const map = generateMap(tmpDir);
-    assert.ok(map.files.length >= 2);
-    assert.ok(map.files.some((f) => f.path.includes("a.ts")));
-  });
-
-  it("detects imports between files", () => {
-    fs.writeFileSync(path.join(tmpDir, "src", "a.ts"), 'import { b } from "./b.ts";\n', "utf8");
-    fs.writeFileSync(path.join(tmpDir, "src", "b.ts"), "export const b = 1;\n", "utf8");
-    const map = generateMap(tmpDir);
-    const aFile = map.files.find((f) => f.path.includes("a.ts"));
-    assert.ok(aFile?.imports.some((i) => i.includes("b.ts")));
-  });
-
-  it("formatMap produces markdown with file tree", () => {
-    fs.writeFileSync(path.join(tmpDir, "src", "index.ts"), "export const x = 1;\n", "utf8");
-    const map = generateMap(tmpDir);
-    const md = formatMap(map);
-    assert.ok(md.includes("## Files"));
-    assert.ok(md.includes("index.ts"));
-  });
-
-  it("counts lines per file", () => {
-    fs.writeFileSync(path.join(tmpDir, "src", "big.ts"), "const a = 1;\nconst b = 2;\nconst c = 3;\n", "utf8");
-    const map = generateMap(tmpDir);
-    const bigFile = map.files.find((f) => f.path.includes("big.ts"));
-    assert.equal(bigFile?.lines, 3);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/map.test.ts
-```
-Expected: FAIL — `Cannot find module '../src/map.ts'`
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/map.ts
-import fs from "node:fs";
-import path from "node:path";
-
-export interface MapFile {
-  path: string;
-  relativePath: string;
-  lines: number;
-  imports: string[];
-}
-
-export interface CodeMap {
-  projectRoot: string;
-  generatedAt: string;
-  files: MapFile[];
-  totalFiles: number;
-  totalLines: number;
-}
-
-const MAP_EXTS = [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"];
-const IGNORE_DIRS = ["node_modules", ".git", "dist", ".forgehive", "coverage", ".next", "build"];
-const IMPORT_PATTERNS = [
-  /^import\s+.*?from\s+['"]([^'"]+)['"]/gm,
-  /^import\s+['"]([^'"]+)['"]/gm,
-  /require\s*\(\s*['"]([^'"]+)['"]\s*\)/gm,
-];
-
-function extractImports(content: string): string[] {
-  const imports: string[] = [];
-  for (const pattern of IMPORT_PATTERNS) {
-    pattern.lastIndex = 0;
-    let m: RegExpExecArray | null;
-    while ((m = pattern.exec(content)) !== null) {
-      if (m[1].startsWith(".")) imports.push(m[1]);
-    }
-  }
-  return [...new Set(imports)];
-}
-
-function walkFiles(dir: string): string[] {
-  const results: string[] = [];
-  function walk(current: string) {
-    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-      if (IGNORE_DIRS.includes(entry.name)) continue;
-      const full = path.join(current, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (entry.isFile() && MAP_EXTS.includes(path.extname(entry.name)))
-        results.push(full);
-    }
-  }
-  walk(dir);
-  return results;
-}
-
-export function generateMap(projectRoot: string): CodeMap {
-  const filePaths = walkFiles(projectRoot);
-  const files: MapFile[] = filePaths.map((filePath) => {
-    let content = "";
-    try { content = fs.readFileSync(filePath, "utf8"); } catch { /* skip */ }
-    const lines = content.split("\n").length;
-    const imports = extractImports(content);
-    return {
-      path: filePath,
-      relativePath: path.relative(projectRoot, filePath),
-      lines,
-      imports,
-    };
-  });
-
-  files.sort((a, b) => b.lines - a.lines);
-
-  return {
-    projectRoot,
-    generatedAt: new Date().toISOString(),
-    files,
-    totalFiles: files.length,
-    totalLines: files.reduce((sum, f) => sum + f.lines, 0),
-  };
-}
-
-export function formatMap(map: CodeMap): string {
-  const lines: string[] = [];
-  lines.push("# Codebase Map");
-  lines.push(`Generated: ${map.generatedAt}`);
-  lines.push(`Total: ${map.totalFiles} files, ${map.totalLines} lines`);
-  lines.push("");
-  lines.push("## Files");
-  lines.push("");
-  lines.push("| File | Lines | Imports |");
-  lines.push("|---|---|---|");
-  for (const f of map.files) {
-    const imps = f.imports.length > 0 ? f.imports.slice(0, 3).join(", ") : "—";
-    lines.push(`| \`${f.relativePath}\` | ${f.lines} | ${imps} |`);
-  }
-  lines.push("");
-  lines.push("## Most Imported");
-  lines.push("");
-  const importCounts: Record<string, number> = {};
-  for (const f of map.files) {
-    for (const imp of f.imports) {
-      importCounts[imp] = (importCounts[imp] || 0) + 1;
-    }
-  }
-  const sorted = Object.entries(importCounts).sort((a, b) => b[1] - a[1]).slice(0, 10);
-  if (sorted.length > 0) {
-    for (const [imp, count] of sorted)
-      lines.push(`- \`${imp}\` — imported ${count}×`);
-  } else {
-    lines.push("No internal imports detected.");
-  }
-  return lines.join("\n");
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/map.test.ts
-```
-Expected: 4 passing
-
-- [ ] **Step 5: Wire `fh map` in cli.ts**
-
-Add import:
-```typescript
-import { generateMap, formatMap } from "./map.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "map") {
-  const map = generateMap(projectRoot);
-  const md = formatMap(map);
-  const mapPath = path.join(forgehiveDir, "map.md");
-  fs.mkdirSync(forgehiveDir, { recursive: true });
-  fs.writeFileSync(mapPath, md, "utf8");
-  console.log(md);
-  console.log(`\n✔ Codebase-Map gespeichert: ${mapPath}`);
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/map.ts test/map.test.ts src/cli.ts
-git commit -m "feat: add fh map command for codebase structure visualization"
-```
-
----
-
-## Task 3: Onboarding Document (`src/onboard.ts`)
-
-**Files:**
-- Create: `src/onboard.ts`
-- Create: `test/onboard.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/onboard.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 { generateOnboardingDoc } from "../src/onboard.ts";
-
-describe("generateOnboardingDoc()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-onboard-"));
-    fs.mkdirSync(path.join(tmpDir, ".forgehive", "memory"), { recursive: true });
-    fs.mkdirSync(path.join(tmpDir, ".forgehive", "harness"), { recursive: true });
-    fs.writeFileSync(
-      path.join(tmpDir, ".forgehive", "capabilities.yaml"),
-      "status: confirmed\nlanguage: typescript\nframework: node\n",
-      "utf8"
-    );
-    fs.writeFileSync(
-      path.join(tmpDir, ".forgehive", "memory", "project.md"),
-      "# Projektkontext\n\nDies ist ein Test-Projekt.\n",
-      "utf8"
-    );
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("generates a markdown document", () => {
-    const doc = generateOnboardingDoc(tmpDir, path.join(tmpDir, ".forgehive"));
-    assert.ok(typeof doc === "string");
-    assert.ok(doc.length > 0);
-    assert.ok(doc.includes("#"));
-  });
-
-  it("includes project name", () => {
-    const doc = generateOnboardingDoc(tmpDir, path.join(tmpDir, ".forgehive"));
-    assert.ok(doc.includes(path.basename(tmpDir)));
-  });
-
-  it("includes stack info from capabilities.yaml", () => {
-    const doc = generateOnboardingDoc(tmpDir, path.join(tmpDir, ".forgehive"));
-    assert.ok(doc.includes("typescript") || doc.includes("TypeScript"));
-  });
-
-  it("includes memory content", () => {
-    const doc = generateOnboardingDoc(tmpDir, path.join(tmpDir, ".forgehive"));
-    assert.ok(doc.includes("Test-Projekt"));
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/onboard.test.ts
-```
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/onboard.ts
-import fs from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import yaml from "js-yaml";
-
-function getRecentCommits(projectRoot: string, n = 20): string[] {
-  const result = spawnSync("git", ["log", `--oneline`, `-${n}`], {
-    cwd: projectRoot,
-    encoding: "utf8",
-  });
-  if (result.status !== 0) return [];
-  return result.stdout.trim().split("\n").filter(Boolean);
-}
-
-function readCapabilities(forgehiveDir: string): Record<string, unknown> {
-  const capPath = path.join(forgehiveDir, "capabilities.yaml");
-  if (!fs.existsSync(capPath)) return {};
-  try {
-    return (yaml.load(fs.readFileSync(capPath, "utf8")) as Record<string, unknown>) ?? {};
-  } catch {
-    return {};
-  }
-}
-
-function readMemoryFiles(forgehiveDir: string): Record<string, string> {
-  const memDir = path.join(forgehiveDir, "memory");
-  if (!fs.existsSync(memDir)) return {};
-  const result: Record<string, string> = {};
-  for (const f of fs.readdirSync(memDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md")) {
-    result[f] = fs.readFileSync(path.join(memDir, f), "utf8");
-  }
-  return result;
-}
-
-function listAdrs(forgehiveDir: string): string[] {
-  const adrsDir = path.join(forgehiveDir, "memory", "adrs");
-  if (!fs.existsSync(adrsDir)) return [];
-  return fs.readdirSync(adrsDir).filter((f) => f.endsWith(".md"));
-}
-
-export function generateOnboardingDoc(
-  projectRoot: string,
-  forgehiveDir: string
-): string {
-  const projectName = path.basename(projectRoot);
-  const caps = readCapabilities(forgehiveDir);
-  const memFiles = readMemoryFiles(forgehiveDir);
-  const commits = getRecentCommits(projectRoot);
-  const adrs = listAdrs(forgehiveDir);
-
-  const lines: string[] = [];
-
-  lines.push(`# Onboarding: ${projectName}`);
-  lines.push("");
-  lines.push(`> Generated by forgehive on ${new Date().toISOString().slice(0, 10)}`);
-  lines.push("");
-
-  lines.push("## Tech Stack");
-  lines.push("");
-  if (caps.language) lines.push(`- **Language:** ${caps.language}`);
-  if (caps.framework) lines.push(`- **Framework:** ${caps.framework}`);
-  if (caps.packageManager) lines.push(`- **Package Manager:** ${caps.packageManager}`);
-  if (caps.testFramework) lines.push(`- **Tests:** ${caps.testFramework}`);
-  if ((caps as any).entryPoints) {
-    const eps = (caps as any).entryPoints;
-    if (Array.isArray(eps) && eps.length > 0)
-      lines.push(`- **Entry Points:** ${eps.join(", ")}`);
-  }
-  lines.push("");
-
-  lines.push("## Getting Started");
-  lines.push("");
-  lines.push("```bash");
-  lines.push("# Clone the repo");
-  lines.push(`git clone <repo-url>`);
-  lines.push(`cd ${projectName}`);
-  lines.push("");
-
-  const pm = (caps.packageManager as string) || "npm";
-  lines.push(`# Install dependencies`);
-  lines.push(pm === "yarn" ? "yarn" : pm === "pnpm" ? "pnpm install" : "npm install");
-  lines.push("```");
-  lines.push("");
-
-  if (memFiles["project.md"]) {
-    lines.push("## Project Context");
-    lines.push("");
-    const projectContent = memFiles["project.md"]
-      .replace(/^---[\s\S]*?---\n/m, "")
-      .trim();
-    lines.push(projectContent);
-    lines.push("");
-  }
-
-  if (memFiles["stack.md"]) {
-    lines.push("## Stack Notes");
-    lines.push("");
-    const stackContent = memFiles["stack.md"]
-      .replace(/^---[\s\S]*?---\n/m, "")
-      .trim();
-    lines.push(stackContent);
-    lines.push("");
-  }
-
-  if (adrs.length > 0) {
-    lines.push("## Architecture Decisions");
-    lines.push("");
-    for (const adr of adrs) lines.push(`- ${adr.replace(".md", "")}`);
-    lines.push("");
-    lines.push(`See \`.forgehive/memory/adrs/\` for full decision records.`);
-    lines.push("");
-  }
-
-  if (commits.length > 0) {
-    lines.push("## Recent Activity");
-    lines.push("");
-    for (const c of commits.slice(0, 10)) lines.push(`- ${c}`);
-    lines.push("");
-  }
-
-  lines.push("## forgehive");
-  lines.push("");
-  lines.push("This project uses [forgehive](https://www.npmjs.com/package/forgehive) for AI-assisted development.");
-  lines.push("");
-  lines.push("```bash");
-  lines.push("npm install -g forgehive");
-  lines.push("fh status   # check project health");
-  lines.push("```");
-
-  return lines.join("\n");
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/onboard.test.ts
-```
-Expected: 4 passing
-
-- [ ] **Step 5: Wire `fh onboard` in cli.ts**
-
-Add import:
-```typescript
-import { generateOnboardingDoc } from "./onboard.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "onboard") {
-  const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
-  const outputPath = outputArg ?? path.join(projectRoot, "ONBOARDING.md");
-  const doc = generateOnboardingDoc(projectRoot, forgehiveDir);
-  fs.writeFileSync(outputPath, doc, "utf8");
-  console.log(`✔ Onboarding-Dokument geschrieben: ${outputPath}`);
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/onboard.ts test/onboard.test.ts src/cli.ts
-git commit -m "feat: add fh onboard command for new team member documentation"
-```
-
----
-
-## Task 4: Semantic Changelog (`src/changelog.ts`)
-
-**Files:**
-- Create: `src/changelog.ts`
-- Create: `test/changelog.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/changelog.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 { parseGitLog, groupByType, formatChangelog } from "../src/changelog.ts";
-
-describe("parseGitLog()", () => {
-  it("parses conventional commit messages", () => {
-    const rawLog = [
-      "abc1234 feat: add login page",
-      "def5678 fix: correct button color",
-      "ghi9012 chore: update dependencies",
-    ].join("\n");
-    const commits = parseGitLog(rawLog);
-    assert.equal(commits.length, 3);
-    assert.equal(commits[0].type, "feat");
-    assert.equal(commits[0].message, "add login page");
-    assert.equal(commits[0].hash, "abc1234");
-  });
-
-  it("handles non-conventional commits as 'other'", () => {
-    const rawLog = "abc1234 Updated something random";
-    const commits = parseGitLog(rawLog);
-    assert.equal(commits[0].type, "other");
-    assert.equal(commits[0].message, "Updated something random");
-  });
-});
-
-describe("groupByType()", () => {
-  it("groups commits by type", () => {
-    const commits = [
-      { hash: "a", type: "feat", message: "feature one", scope: null },
-      { hash: "b", type: "feat", message: "feature two", scope: null },
-      { hash: "c", type: "fix", message: "bug fix", scope: null },
-    ];
-    const groups = groupByType(commits);
-    assert.equal(groups["feat"].length, 2);
-    assert.equal(groups["fix"].length, 1);
-  });
-});
-
-describe("formatChangelog()", () => {
-  it("produces markdown with version header", () => {
-    const commits = [
-      { hash: "a", type: "feat", message: "new feature", scope: null },
-    ];
-    const md = formatChangelog(commits, "1.0.0");
-    assert.ok(md.includes("1.0.0"));
-    assert.ok(md.includes("Added") || md.includes("feat"));
-    assert.ok(md.includes("new feature"));
-  });
-
-  it("returns empty message when no commits", () => {
-    const md = formatChangelog([], "1.0.0");
-    assert.ok(md.includes("1.0.0"));
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/changelog.test.ts
-```
-Expected: FAIL
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/changelog.ts
-import { spawnSync } from "node:child_process";
-
-export interface Commit {
-  hash: string;
-  type: string;
-  scope: string | null;
-  message: string;
-}
-
-const TYPE_LABELS: Record<string, string> = {
-  feat: "Added",
-  fix: "Fixed",
-  perf: "Improved",
-  refactor: "Changed",
-  chore: "Maintenance",
-  docs: "Documentation",
-  test: "Tests",
-  ci: "CI",
-  other: "Other",
-};
-
-export function parseGitLog(rawLog: string): Commit[] {
-  return rawLog
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => {
-      const spaceIdx = line.indexOf(" ");
-      const hash = line.slice(0, spaceIdx);
-      const rest = line.slice(spaceIdx + 1);
-      const conventionalMatch = rest.match(/^(\w+)(?:\(([^)]+)\))?\s*:\s*(.+)$/);
-      if (conventionalMatch) {
-        return {
-          hash,
-          type: conventionalMatch[1],
-          scope: conventionalMatch[2] ?? null,
-          message: conventionalMatch[3],
-        };
-      }
-      return { hash, type: "other", scope: null, message: rest };
-    });
-}
-
-export function groupByType(commits: Commit[]): Record<string, Commit[]> {
-  const groups: Record<string, Commit[]> = {};
-  for (const commit of commits) {
-    if (!groups[commit.type]) groups[commit.type] = [];
-    groups[commit.type].push(commit);
-  }
-  return groups;
-}
-
-export function formatChangelog(commits: Commit[], version: string): string {
-  const date = new Date().toISOString().slice(0, 10);
-  const lines: string[] = [];
-  lines.push(`## [${version}] — ${date}`);
-  lines.push("");
-
-  if (commits.length === 0) {
-    lines.push("No changes.");
-    return lines.join("\n");
-  }
-
-  const groups = groupByType(commits);
-  const typeOrder = ["feat", "fix", "perf", "refactor", "docs", "chore", "test", "ci", "other"];
-
-  for (const type of typeOrder) {
-    if (!groups[type] || groups[type].length === 0) continue;
-    const label = TYPE_LABELS[type] ?? type;
-    lines.push(`### ${label}`);
-    lines.push("");
-    for (const c of groups[type]) {
-      const scope = c.scope ? `**${c.scope}:** ` : "";
-      lines.push(`- ${scope}${c.message} (\`${c.hash}\`)`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-export function getGitLogSince(projectRoot: string, since?: string): string {
-  const args = ["log", "--oneline", "--no-merges"];
-  if (since) args.push(`${since}..HEAD`);
-  const result = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
-  if (result.status !== 0) return "";
-  return result.stdout.trim();
-}
-
-export function getLatestTag(projectRoot: string): string | null {
-  const result = spawnSync("git", ["describe", "--tags", "--abbrev=0"], {
-    cwd: projectRoot,
-    encoding: "utf8",
-  });
-  if (result.status !== 0) return null;
-  return result.stdout.trim() || null;
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/changelog.test.ts
-```
-Expected: 5 passing
-
-- [ ] **Step 5: Wire `fh changelog` in cli.ts**
-
-Add import:
-```typescript
-import { parseGitLog, formatChangelog, getGitLogSince, getLatestTag } from "./changelog.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "changelog") {
-  const sinceArg = rest.includes("--since") ? rest[rest.indexOf("--since") + 1] : null;
-  const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
-  const since = sinceArg ?? getLatestTag(projectRoot) ?? undefined;
-  const rawLog = getGitLogSince(projectRoot, since);
-  const commits = parseGitLog(rawLog);
-  const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, "package.json"), "utf8").replace(/^\s*\/\/.*$/gm, ""));
-  const version = pkg.version ?? "unreleased";
-  const md = formatChangelog(commits, version);
-  const outputPath = outputArg ?? path.join(projectRoot, "CHANGELOG.md");
-  let existing = "";
-  if (fs.existsSync(outputPath)) existing = fs.readFileSync(outputPath, "utf8");
-  fs.writeFileSync(outputPath, md + "\n\n" + existing, "utf8");
-  console.log(`✔ CHANGELOG.md aktualisiert: ${outputPath}`);
-  console.log(`  ${commits.length} Commits verarbeitet`);
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/changelog.ts test/changelog.test.ts src/cli.ts
-git commit -m "feat: add fh changelog command for semantic changelog generation"
-```
-
----
-
-## Task 5: Developer Metrics (`src/metrics.ts`)
-
-**Files:**
-- Create: `src/metrics.ts`
-- Create: `test/metrics.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/metrics.test.ts
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { parseCommitStats, formatMetrics } from "../src/metrics.ts";
-
-describe("parseCommitStats()", () => {
-  it("counts commits by author", () => {
-    const rawLog = [
-      "2026-05-14 Alice feat: feature one",
-      "2026-05-13 Bob fix: bug fix",
-      "2026-05-12 Alice chore: cleanup",
-    ].join("\n");
-    const stats = parseCommitStats(rawLog);
-    assert.equal(stats.totalCommits, 3);
-    assert.equal(stats.byAuthor["Alice"], 2);
-    assert.equal(stats.byAuthor["Bob"], 1);
-  });
-
-  it("counts by commit type", () => {
-    const rawLog = [
-      "2026-05-14 Alice feat: one",
-      "2026-05-13 Alice feat: two",
-      "2026-05-12 Alice fix: three",
-    ].join("\n");
-    const stats = parseCommitStats(rawLog);
-    assert.equal(stats.byType["feat"], 2);
-    assert.equal(stats.byType["fix"], 1);
-  });
-
-  it("returns zeros for empty log", () => {
-    const stats = parseCommitStats("");
-    assert.equal(stats.totalCommits, 0);
-  });
-});
-
-describe("formatMetrics()", () => {
-  it("produces markdown report", () => {
-    const stats = {
-      totalCommits: 10,
-      byAuthor: { Alice: 7, Bob: 3 },
-      byType: { feat: 4, fix: 3, chore: 3 },
-      dateRange: { from: "2026-05-01", to: "2026-05-14" },
-    };
-    const md = formatMetrics(stats, "my-project");
-    assert.ok(md.includes("my-project"));
-    assert.ok(md.includes("10"));
-    assert.ok(md.includes("Alice"));
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/metrics.test.ts
-```
-Expected: FAIL
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/metrics.ts
-import { spawnSync } from "node:child_process";
-
-export interface CommitStats {
-  totalCommits: number;
-  byAuthor: Record<string, number>;
-  byType: Record<string, number>;
-  dateRange: { from: string; to: string };
-}
-
-export function parseCommitStats(rawLog: string): CommitStats {
-  const lines = rawLog.split("\n").map((l) => l.trim()).filter(Boolean);
-  const byAuthor: Record<string, number> = {};
-  const byType: Record<string, number> = {};
-  const dates: string[] = [];
-
-  for (const line of lines) {
-    const parts = line.split(" ");
-    if (parts.length < 3) continue;
-    const date = parts[0];
-    const author = parts[1];
-    const message = parts.slice(2).join(" ");
-
-    dates.push(date);
-    byAuthor[author] = (byAuthor[author] || 0) + 1;
-
-    const typeMatch = message.match(/^(\w+)(?:\([^)]+\))?:/);
-    const type = typeMatch ? typeMatch[1] : "other";
-    byType[type] = (byType[type] || 0) + 1;
-  }
-
-  const sortedDates = dates.sort();
-  return {
-    totalCommits: lines.length,
-    byAuthor,
-    byType,
-    dateRange: {
-      from: sortedDates[0] ?? "",
-      to: sortedDates[sortedDates.length - 1] ?? "",
-    },
-  };
-}
-
-export function formatMetrics(stats: CommitStats, projectName: string): string {
-  const lines: string[] = [];
-  lines.push(`# Developer Metrics: ${projectName}`);
-  lines.push(`Generated: ${new Date().toISOString().slice(0, 10)}`);
-  lines.push("");
-  lines.push(`**Total commits:** ${stats.totalCommits}`);
-  if (stats.dateRange.from)
-    lines.push(`**Date range:** ${stats.dateRange.from} → ${stats.dateRange.to}`);
-  lines.push("");
-
-  if (Object.keys(stats.byAuthor).length > 0) {
-    lines.push("## Commits by Author");
-    lines.push("");
-    for (const [author, count] of Object.entries(stats.byAuthor).sort((a, b) => b[1] - a[1]))
-      lines.push(`- **${author}:** ${count}`);
-    lines.push("");
-  }
-
-  if (Object.keys(stats.byType).length > 0) {
-    lines.push("## Commits by Type");
-    lines.push("");
-    for (const [type, count] of Object.entries(stats.byType).sort((a, b) => b[1] - a[1]))
-      lines.push(`- **${type}:** ${count}`);
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-export function getMetricsGitLog(projectRoot: string, since?: string): string {
-  const args = ["log", "--no-merges", "--format=%as %an %s"];
-  if (since) args.push(`--since=${since}`);
-  const result = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
-  if (result.status !== 0) return "";
-  return result.stdout.trim();
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/metrics.test.ts
-```
-Expected: 4 passing
-
-- [ ] **Step 5: Wire `fh metrics` in cli.ts**
-
-Add import:
-```typescript
-import { parseCommitStats, formatMetrics, getMetricsGitLog } from "./metrics.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "metrics") {
-  const sinceArg = rest.includes("--since") ? rest[rest.indexOf("--since") + 1] : undefined;
-  const rawLog = getMetricsGitLog(projectRoot, sinceArg);
-  const stats = parseCommitStats(rawLog);
-  const projectName = require("path").basename(projectRoot);
-  const md = formatMetrics(stats, path.basename(projectRoot));
-  const metricsPath = path.join(forgehiveDir, "metrics.md");
-  fs.mkdirSync(forgehiveDir, { recursive: true });
-  fs.writeFileSync(metricsPath, md, "utf8");
-  console.log(md);
-  console.log(`\n✔ Metrics gespeichert: ${metricsPath}`);
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/metrics.ts test/metrics.test.ts src/cli.ts
-git commit -m "feat: add fh metrics command for developer productivity metrics"
-```
-
----
-
-## Task 6: Team Sync (`src/sync.ts`)
-
-**Files:**
-- Create: `src/sync.ts`
-- Create: `test/sync.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/sync.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 { spawnSync } from "node:child_process";
-import { getSyncStatus } from "../src/sync.ts";
-
-describe("getSyncStatus()", () => {
-  let tmpDir: string;
-  beforeEach(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "fh-sync-"));
-    fs.mkdirSync(path.join(tmpDir, ".forgehive", "memory"), { recursive: true });
-    fs.writeFileSync(
-      path.join(tmpDir, ".forgehive", "memory", "project.md"),
-      "# Project\n\nTest content.\n",
-      "utf8"
-    );
-    spawnSync("git", ["init"], { cwd: tmpDir });
-    spawnSync("git", ["config", "user.email", "test@test.com"], { cwd: tmpDir });
-    spawnSync("git", ["config", "user.name", "Test"], { cwd: tmpDir });
-  });
-  afterEach(() => fs.rmSync(tmpDir, { recursive: true, force: true }));
-
-  it("returns memory file count", () => {
-    const status = getSyncStatus(path.join(tmpDir, ".forgehive"));
-    assert.equal(status.files, 1);
-  });
-
-  it("returns false for hasRemote when no remote configured", () => {
-    const status = getSyncStatus(path.join(tmpDir, ".forgehive"));
-    assert.equal(status.hasRemote, false);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/sync.test.ts
-```
-Expected: FAIL
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/sync.ts
-import fs from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-export interface SyncStatus {
-  files: number;
-  hasRemote: boolean;
-  remote: string | null;
-  branch: string | null;
-}
-
-export function getSyncStatus(forgehiveDir: string): SyncStatus {
-  const memDir = path.join(forgehiveDir, "memory");
-  const files = fs.existsSync(memDir)
-    ? fs.readdirSync(memDir).filter((f) => f.endsWith(".md")).length
-    : 0;
-
-  const projectRoot = path.dirname(forgehiveDir);
-  const configResult = spawnSync(
-    "git",
-    ["config", "--get", "forgehive.sync-remote"],
-    { cwd: projectRoot, encoding: "utf8" }
-  );
-  const remote = configResult.status === 0 ? configResult.stdout.trim() : null;
-  const branchResult = spawnSync(
-    "git",
-    ["config", "--get", "forgehive.sync-branch"],
-    { cwd: projectRoot, encoding: "utf8" }
-  );
-  const branch = branchResult.status === 0 ? branchResult.stdout.trim() : null;
-
-  return { files, hasRemote: remote !== null, remote, branch };
-}
-
-export interface SyncPushResult {
-  success: boolean;
-  message: string;
-  filesCommitted: number;
-}
-
-export function pushSync(
-  forgehiveDir: string,
-  remote = "origin",
-  branch = "forgehive-memory"
-): SyncPushResult {
-  const projectRoot = path.dirname(forgehiveDir);
-  const memDir = path.join(forgehiveDir, "memory");
-
-  if (!fs.existsSync(memDir)) {
-    return { success: false, message: "Kein Memory-Verzeichnis gefunden.", filesCommitted: 0 };
-  }
-
-  const files = fs.readdirSync(memDir).filter((f) => f.endsWith(".md"));
-  if (files.length === 0) {
-    return { success: false, message: "Keine Memory-Dateien gefunden.", filesCommitted: 0 };
-  }
-
-  // Stage memory files
-  const addResult = spawnSync(
-    "git",
-    ["add", path.join(".forgehive", "memory")],
-    { cwd: projectRoot, encoding: "utf8" }
-  );
-  if (addResult.status !== 0) {
-    return { success: false, message: `git add failed: ${addResult.stderr}`, filesCommitted: 0 };
-  }
-
-  const commitResult = spawnSync(
-    "git",
-    ["commit", "-m", `chore: sync forgehive memory [${new Date().toISOString()}]`],
-    { cwd: projectRoot, encoding: "utf8" }
-  );
-  // Exit 1 with "nothing to commit" is OK
-  const commitOk =
-    commitResult.status === 0 ||
-    (commitResult.stdout + commitResult.stderr).includes("nothing to commit");
-
-  if (!commitOk) {
-    return { success: false, message: `git commit failed: ${commitResult.stderr}`, filesCommitted: 0 };
-  }
-
-  const pushResult = spawnSync(
-    "git",
-    ["push", remote, `HEAD:${branch}`],
-    { cwd: projectRoot, encoding: "utf8" }
-  );
-  if (pushResult.status !== 0) {
-    return { success: false, message: `git push failed: ${pushResult.stderr}`, filesCommitted: 0 };
-  }
-
-  // Save config for future syncs
-  spawnSync("git", ["config", "forgehive.sync-remote", remote], { cwd: projectRoot });
-  spawnSync("git", ["config", "forgehive.sync-branch", branch], { cwd: projectRoot });
-
-  return { success: true, message: `Memory gepusht nach ${remote}/${branch}`, filesCommitted: files.length };
-}
-
-export interface SyncPullResult {
-  success: boolean;
-  message: string;
-  filesImported: string[];
-}
-
-export function pullSync(
-  forgehiveDir: string,
-  remote = "origin",
-  branch = "forgehive-memory"
-): SyncPullResult {
-  const projectRoot = path.dirname(forgehiveDir);
-  const memDir = path.join(forgehiveDir, "memory");
-  fs.mkdirSync(memDir, { recursive: true });
-
-  const fetchResult = spawnSync(
-    "git",
-    ["fetch", remote, branch],
-    { cwd: projectRoot, encoding: "utf8" }
-  );
-  if (fetchResult.status !== 0) {
-    return { success: false, message: `git fetch failed: ${fetchResult.stderr}`, filesImported: [] };
-  }
-
-  // Get list of memory files from remote branch
-  const listResult = spawnSync(
-    "git",
-    ["ls-tree", "--name-only", `${remote}/${branch}`, ".forgehive/memory/"],
-    { cwd: projectRoot, encoding: "utf8" }
-  );
-  if (listResult.status !== 0) {
-    return { success: false, message: "Remote branch hat keine Memory-Dateien.", filesImported: [] };
-  }
-
-  const remoteFiles = listResult.stdout.trim().split("\n").filter(Boolean);
-  const imported: string[] = [];
-
-  for (const remotePath of remoteFiles) {
-    const filename = path.basename(remotePath);
-    const localPath = path.join(memDir, filename);
-    if (!fs.existsSync(localPath)) {
-      const contentResult = spawnSync(
-        "git",
-        ["show", `${remote}/${branch}:${remotePath}`],
-        { cwd: projectRoot, encoding: "utf8" }
-      );
-      if (contentResult.status === 0) {
-        fs.writeFileSync(localPath, contentResult.stdout, "utf8");
-        imported.push(filename);
-      }
-    }
-  }
-
-  return {
-    success: true,
-    message: imported.length > 0
-      ? `${imported.length} neue Dateien importiert.`
-      : "Keine neuen Dateien (bereits aktuell).",
-    filesImported: imported,
-  };
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/sync.test.ts
-```
-Expected: 2 passing
-
-- [ ] **Step 5: Wire `fh sync` in cli.ts**
-
-Add import:
-```typescript
-import { pushSync, pullSync, getSyncStatus } from "./sync.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "sync") {
-  const remoteArg = rest.includes("--remote") ? rest[rest.indexOf("--remote") + 1] : "origin";
-  const branchArg = rest.includes("--branch") ? rest[rest.indexOf("--branch") + 1] : "forgehive-memory";
-
-  if (subcommand === "push") {
-    const result = pushSync(forgehiveDir, remoteArg, branchArg);
-    console.log(result.success ? `✔ ${result.message}` : `✗ ${result.message}`);
-    if (!result.success) process.exit(1);
-  } else if (subcommand === "pull") {
-    const result = pullSync(forgehiveDir, remoteArg, branchArg);
-    console.log(result.success ? `✔ ${result.message}` : `✗ ${result.message}`);
-    if (result.filesImported.length > 0)
-      console.log("  Importiert:", result.filesImported.join(", "));
-    if (!result.success) process.exit(1);
-  } else {
-    const status = getSyncStatus(forgehiveDir);
-    console.log(`Memory: ${status.files} Dateien`);
-    console.log(status.hasRemote
-      ? `Remote: ${status.remote}/${status.branch}`
-      : "Kein Remote konfiguriert. Nutze: fh sync push [--remote origin --branch forgehive-memory]");
-  }
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/sync.ts test/sync.test.ts src/cli.ts
-git commit -m "feat: add fh sync push/pull for team memory sharing via git"
-```
-
----
-
-## Task 7: Background Agent Execution (`src/background.ts`)
-
-**Files:**
-- Create: `src/background.ts`
-- Create: `test/background.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```typescript
-// test/background.test.ts
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { buildAgentPrompt, resolveAgent } from "../src/background.ts";
-
-describe("buildAgentPrompt()", () => {
-  it("includes the issue URL in the prompt", () => {
-    const prompt = buildAgentPrompt("https://github.com/user/repo/issues/42", "kai");
-    assert.ok(prompt.includes("https://github.com/user/repo/issues/42"));
-  });
-
-  it("includes the agent name in the prompt", () => {
-    const prompt = buildAgentPrompt("https://linear.app/team/issue/ENG-42", "vera");
-    assert.ok(prompt.includes("vera") || prompt.includes("Vera") || prompt.includes("Security"));
-  });
-
-  it("returns a non-empty string", () => {
-    const prompt = buildAgentPrompt("https://example.com/issue/1", "kai");
-    assert.ok(prompt.length > 50);
-  });
-});
-
-describe("resolveAgent()", () => {
-  it("resolves kai for code tasks by default", () => {
-    const agent = resolveAgent(undefined);
-    assert.equal(agent, "kai");
-  });
-
-  it("resolves vera for security label", () => {
-    const agent = resolveAgent("security");
-    assert.equal(agent, "vera");
-  });
-
-  it("resolves nora for research label", () => {
-    const agent = resolveAgent("research");
-    assert.equal(agent, "nora");
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-node --import tsx/esm --test test/background.test.ts
-```
-Expected: FAIL
-
-- [ ] **Step 3: Write the implementation**
-
-```typescript
-// src/background.ts
-import fs from "node:fs";
-import path from "node:path";
-import { spawn } from "node:child_process";
-
-const AGENT_ROLES: Record<string, string> = {
-  kai: "Senior Engineer — implements features and fixes bugs",
-  sam: "QA & Test Architect — writes tests and checks quality",
-  viktor: "System Architect — designs architecture and reviews structure",
-  vera: "Security Analyst — reviews for OWASP, GDPR, auth issues",
-  nora: "Senior Research Analyst — researches options and summarizes findings",
-  eli: "Technical Writer — writes documentation and changelogs",
-  suki: "UX Designer — reviews UI/UX and user flows",
-  remy: "Creative Strategist — explores creative approaches",
-};
-
-const LABEL_TO_AGENT: Record<string, string> = {
-  security: "vera",
-  research: "nora",
-  docs: "eli",
-  documentation: "eli",
-  design: "suki",
-  ux: "suki",
-  architecture: "viktor",
-  arch: "viktor",
-  test: "sam",
-  qa: "sam",
-};
-
-export function resolveAgent(label: string | undefined): string {
-  if (!label) return "kai";
-  return LABEL_TO_AGENT[label.toLowerCase()] ?? "kai";
-}
-
-export function buildAgentPrompt(issueUrl: string, agentId: string): string {
-  const role = AGENT_ROLES[agentId] ?? "Senior Engineer";
-  return `You are ${agentId} — ${role}.
-
-Your task: Resolve the following issue autonomously.
-
-Issue URL: ${issueUrl}
-
-Instructions:
-1. Read the issue at the URL above (use web fetch or gh CLI if available)
-2. Understand what needs to be done
-3. Implement the solution following the project's conventions (read .forgehive/ for context)
-4. Write tests for any new code
-5. Commit your changes with a descriptive message
-6. Report what you did
-
-Work autonomously. Do not ask for clarification — use your best judgment based on the issue description and codebase context.`;
-}
-
-export interface BackgroundRunResult {
-  pid: number | undefined;
-  logFile: string;
-  message: string;
-}
-
-export function runBackgroundAgent(
-  forgehiveDir: string,
-  issueUrl: string,
-  agentId: string
-): BackgroundRunResult {
-  const logsDir = path.join(forgehiveDir, "background-runs");
-  fs.mkdirSync(logsDir, { recursive: true });
-
-  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const logFile = path.join(logsDir, `${agentId}-${timestamp}.log`);
-  const prompt = buildAgentPrompt(issueUrl, agentId);
-
-  const logStream = fs.openSync(logFile, "w");
-  const child = spawn(
-    "claude",
-    ["-p", prompt, "--output-format", "text"],
-    {
-      cwd: path.dirname(forgehiveDir),
-      detached: true,
-      stdio: ["ignore", logStream, logStream],
-    }
-  );
-
-  child.unref();
-  fs.closeSync(logStream);
-
-  return {
-    pid: child.pid,
-    logFile,
-    message: `Agent ${agentId} gestartet (PID ${child.pid}). Log: ${logFile}`,
-  };
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-```bash
-node --import tsx/esm --test test/background.test.ts
-```
-Expected: 5 passing
-
-- [ ] **Step 5: Wire `fh run` in cli.ts**
-
-Add import:
-```typescript
-import { runBackgroundAgent, resolveAgent } from "./background.ts";
-```
-
-Add handler:
-```typescript
-} else if (command === "run") {
-  const issueUrl = subcommand;
-  if (!issueUrl) {
-    console.error("Usage: fh run <issue-url> [--agent <name>]");
-    process.exit(1);
-  }
-  const agentArg = rest.includes("--agent") ? rest[rest.indexOf("--agent") + 1] : undefined;
-  const labelArg = rest.includes("--label") ? rest[rest.indexOf("--label") + 1] : undefined;
-  const agentId = agentArg ?? resolveAgent(labelArg);
-  const result = runBackgroundAgent(forgehiveDir, issueUrl, agentId);
-  console.log(`✔ ${result.message}`);
-  console.log(`  fh run status   — aktive Sessions anzeigen`);
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/background.ts test/background.test.ts src/cli.ts
-git commit -m "feat: add fh run for background agent execution via claude -p"
-```
-
----
-
-## Task 8: New Slash Commands (Markdown Files)
-
-**Files:**
-- Create: `forgehive/commands/fh-deploy.md`
-- Create: `forgehive/commands/fh-test-this.md`
-- Create: `forgehive/commands/fh-docs.md`
-- Modify: `forgehive/commands/fh-sprint.md`
-
-- [ ] **Step 1: Create `/fh-deploy`**
-
-```markdown
-<!-- forgehive/commands/fh-deploy.md -->
-You are running a deployment workflow using ForgeHive.
-
-## Deployment Protocol
-
-### Step 1: Pre-deploy checks
-
-1. Run the full test suite — stop if any test fails:
-   - Node.js: `npm test`
-   - Python: `pytest`
-   - Go: `go test ./...`
-2. Run `fh security scan` — stop if CRITICAL or HIGH findings
-3. Show `git diff main...HEAD --stat` — confirm scope is as expected
-4. Check for uncommitted changes (`git status`) — commit or stash first
-
-### Step 2: Build
-
-Run the build command from `capabilities.yaml` or ask the user:
-- Node.js: `npm run build`
-- Python: detect from `pyproject.toml` or `setup.py`
-
-Report bundle size and any build warnings.
-
-### Step 3: Deploy to staging
-
-Check `.forgehive/capabilities.yaml` for deploy configuration. If MCP is connected for the deploy service, use it. Otherwise ask: **"Wie deploye ich in die Staging-Umgebung?"**
-
-After deploying, run smoke tests:
-- Check the health endpoint if one exists
-- Verify the app responds with 200
-
-### Step 4: Confirm and promote to production
-
-Ask: **"Staging sieht gut aus — soll ich in Production deployen?"**
-
-Wait for explicit confirmation before proceeding.
-
-### Step 5: Post-deploy
-
-After successful production deploy:
-1. Create a git tag: `git tag v<version> && git push origin v<version>`
-2. Run `fh changelog` to update CHANGELOG.md
-3. Report: deployment complete, version, timestamp
-
-### Rollback
-
-If anything fails after production deploy:
-1. Identify the last known good version
-2. Trigger rollback via the deploy service
-3. Report what failed and why
-```
-
-- [ ] **Step 2: Create `/fh-test-this`**
-
-```markdown
-<!-- forgehive/commands/fh-test-this.md -->
-You are Sam — QA & Test Architect. Your job is to write tests for the current changes.
-
-## Test-This Protocol
-
-### Step 1: Identify what changed
-
-1. Run `git diff HEAD --stat` to see which files changed
-2. Run `git diff HEAD` to see the actual changes
-3. Note: which functions/classes were added or modified?
-
-### Step 2: Load testing skill
-
-Read `.forgehive/skills/expert/testing-strategies.md` for the project's testing conventions.
-
-Check which test framework is in use (from `capabilities.yaml`):
-- `node:test` → use `describe/it` with `node:assert/strict`
-- `jest` → use `describe/it` with `expect`
-- `pytest` → use `def test_` functions
-- `go test` → use `func TestX(t *testing.T)`
-
-### Step 3: Write tests
-
-For each changed function or class, write:
-1. A **happy path test** — normal input, expected output
-2. An **edge case test** — empty input, boundary values, null/undefined
-3. An **error case test** — invalid input, should throw or return error
-
-Place tests in the appropriate test file (same name as source file, `test/` directory or `*.test.ts` suffix).
-
-### Step 4: Run tests
-
-Run the test suite and confirm all new tests pass:
-```bash
-npm test        # or pytest, go test, etc.
-```
-
-If tests fail, fix the implementation or the test until all pass.
-
-### Step 5: Coverage check
-
-If coverage tooling is available, run it and report the coverage percentage for the changed files.
-
-### Step 6: Commit
-
-```bash
-git add <test-files>
-git commit -m "test: add tests for <what you tested>"
-```
-```
-
-- [ ] **Step 3: Create `/fh-docs`**
-
-```markdown
-<!-- forgehive/commands/fh-docs.md -->
-You are Eli — Technical Writer. Your job is to write or update documentation.
-
-## Documentation Protocol
-
-Ask the user: **"Was soll ich dokumentieren?"**
-
-Options:
-1. **README update** — reflect recent features/changes
-2. **API reference** — document endpoints or exported functions
-3. **CHANGELOG** — run `fh changelog` and review the output
-4. **ADR** — document an architecture decision (`fh memory adr "<title>"`)
-5. **Inline docs** — add JSDoc/docstrings to changed functions
-6. **ONBOARDING** — run `fh onboard` and review
-
-### For README updates
-
-1. Read the current `README.md`
-2. Read `.forgehive/memory/project.md` for context
-3. Read `git log --oneline -20` for recent changes
-4. Update sections that are outdated — do NOT rewrite sections that are current
-5. Add a section for any major features added since last README update
-
-### For API reference
-
-1. Find all exported functions in `src/` (TypeScript) or `__init__.py` (Python)
-2. For each exported function: name, parameters with types, return type, one-sentence description, example
-3. Write to `docs/API.md` or update existing file
-
-### For inline documentation
-
-1. Read the changed files from `git diff HEAD --name-only`
-2. For each public function missing a JSDoc/docstring: add a single-line description
-3. Only document the WHY when it's non-obvious — never document WHAT the code does
-
-### Quality check
-
-Before committing:
-- All links in Markdown files resolve
-- Code examples in docs are syntactically valid
-- No placeholder text ("TODO", "TBD", "...")
-```
-
-- [ ] **Step 4: Update `/fh-sprint` with MCP awareness**
-
-Replace the entire content of `forgehive/commands/fh-sprint.md` Step 2 ("Collect backlog items") section with this enhanced version that adds MCP integration:
-
-In `forgehive/commands/fh-sprint.md`, replace the **Step 2** section:
-
-```markdown
-### 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?"**
-
-**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 MCP connected:**
-Accept free-text input — one item per line.
-```
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add forgehive/commands/fh-deploy.md forgehive/commands/fh-test-this.md forgehive/commands/fh-docs.md forgehive/commands/fh-sprint.md
-git commit -m "feat: add /fh-deploy, /fh-test-this, /fh-docs slash commands; enhance /fh-sprint with MCP"
-```
-
----
-
-## Task 9: Multi-Model Routing
-
-**Files:**
-- Modify: `forgehive/party/defaults.yaml`
-- Modify: `src/cli.ts` (fix version string)
-
-- [ ] **Step 1: Update defaults.yaml with model fields**
-
-Replace `forgehive/party/defaults.yaml` with:
-
-```yaml
-sets:
-  design:
-    agents: [suki, viktor]
-    trigger: "/design-party"
-    description: "UX + Architektur parallel"
-    models:
-      suki: claude-sonnet-4-6
-      viktor: claude-opus-4-7
-  build:
-    agents: [viktor, kai, sam]
-    trigger: "/party"
-    description: "Architektur + Engineering + QA"
-    models:
-      viktor: claude-opus-4-7
-      kai: claude-sonnet-4-6
-      sam: claude-haiku-4-5
-  review:
-    agents: [kai, sam, eli]
-    trigger: "/review-party"
-    description: "Code Review + QA + Doku"
-    models:
-      kai: claude-opus-4-7
-      sam: claude-sonnet-4-6
-      eli: claude-sonnet-4-6
-  full:
-    agents: [nora, eli, remy, suki, viktor, kai, sam]
-    trigger: "/full-party"
-    description: "Alle Agenten"
-    models:
-      viktor: claude-opus-4-7
-      kai: claude-opus-4-7
-      nora: claude-sonnet-4-6
-      eli: claude-sonnet-4-6
-      sam: claude-sonnet-4-6
-      suki: claude-sonnet-4-6
-      remy: claude-haiku-4-5
-  security:
-    agents: [vera, sam]
-    trigger: "/security-party"
-    description: "Security Review + QA"
-    models:
-      vera: claude-opus-4-7
-      sam: claude-sonnet-4-6
-```
-
-- [ ] **Step 2: Fix version string in cli.ts**
-
-In `src/cli.ts`, change line 35:
-```typescript
-// From:
-  console.log("0.6.1");
-// To:
-  console.log("0.7.0");
-```
-
-- [ ] **Step 3: Update package.json version**
-
-In `package.json`, change `"version": "0.6.3"` to `"version": "0.7.0"`.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add forgehive/party/defaults.yaml src/cli.ts package.json
-git commit -m "feat: add multi-model routing to party sets, bump to v0.7.0"
-```
-
----
-
-## Task 10: Full Test Run, Build, and Publish
-
-- [ ] **Step 1: Run all tests**
-
-```bash
-cd /home/stefan/projekte/forgehive
-npm test
-```
-
-Expected: All tests pass. Target: ~260+ tests (previous 217 + ~7 new test files × ~5 tests each).
-
-If any test fails, fix it before proceeding.
-
-- [ ] **Step 2: Type check**
-
-```bash
-npm run typecheck
-```
-
-Expected: 0 errors.
-
-- [ ] **Step 3: Build**
-
-```bash
-npm run build
-```
-
-Expected: `dist/cli.js` built successfully, shebang on line 1 (`head -1 dist/cli.js` shows `#!/usr/bin/env node`).
-
-- [ ] **Step 4: Update help text in cli.ts**
-
-In `src/cli.ts`, update the unknown command handler's help text to include all new commands:
-
-```typescript
-console.error("Verfügbar: 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]");
-```
-
-- [ ] **Step 5: Final commit**
-
-```bash
-git add src/cli.ts
-git commit -m "chore: update help text for v0.7.0 commands"
-```
-
-- [ ] **Step 6: Publish**
-
-```bash
-npm publish
-```
-
-Expected: `forgehive@0.7.0` published successfully.
-
-- [ ] **Step 7: Update memory**
-
-Update `/home/stefan/.claude/projects/-home-stefan-projekte-framework-os/memory/project.md`:
-- Version: v0.7.0
-- New commands: ci, map, onboard, changelog, metrics, sync, run
-- New slash commands: /fh-deploy, /fh-test-this, /fh-docs
-- Updated: /fh-sprint (MCP), party defaults.yaml (model routing)