forgehive 0.7.7 → 0.7.8

package/README.md

@@ -45,9 +45,9 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 
 ---
 
-## Status: v0.7.5 — Stable
+## Status: v0.7.7 — Stable
 
-273 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
+297 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
 
 **Stable — use with confidence:**
 
@@ -125,7 +125,7 @@ npm link           # makes 'fh' available globally
 Verify the installation:
 
 ```bash
-fh --version       # should print 0.7.5
+fh --version       # should print 0.7.7
 fh --help          # lists all available commands
 ```
 
@@ -890,6 +890,8 @@ npm test            # node --import tsx/esm --test test/*.test.ts
 
 | Version | What's new |
 |---|---|
+| **0.7.7** | User Guide (`docs/user-guide.md`) included in npm package; Documentation table in README |
+| **0.7.6** | YAML shape fix in `fh docs user`; frontmatter regex fix; 8 new tests for HIGH RISK paths |
 | **0.7.5** | `fh --version` reads from `package.json` (no longer hardcoded) |
 | **0.7.4** | Party slash commands installed by `fh init` (`/party`, `/review-party`, `/design-party`, `/full-party`, `/security-party`) |
 | **0.7.3** | User Docs generation (`fh docs user`, `fh docs api`, `fh docs list`) |

package/dist/cli.js

@@ -6550,7 +6550,7 @@ function generateUserGuide(projectRoot2, forgehiveDir2) {
   lines.push("## Overview");
   lines.push("");
   if (memFiles["project.md"]) {
-    const content = memFiles["project.md"].replace(/^---[\s\S]*?---\n/, "").trim();
+    const content = memFiles["project.md"].replace(/^---[\s\S]*?---\n?/, "").trim();
     lines.push(content);
   } else {
     lines.push(`${projectName} is a ${lang ?? "software"} application.`);
@@ -6585,7 +6585,7 @@ function generateUserGuide(projectRoot2, forgehiveDir2) {
   }
   lines.push("```");
   lines.push("");
-  if (Array.isArray(entryPoints) && entryPoints.length > 0) {
+  if ((lang === "typescript" || lang === "javascript") && Array.isArray(entryPoints) && entryPoints.length > 0) {
     lines.push("## Getting Started");
     lines.push("");
     lines.push("```bash");
@@ -6596,7 +6596,7 @@ function generateUserGuide(projectRoot2, forgehiveDir2) {
   if (memFiles["stack.md"]) {
     lines.push("## Configuration");
     lines.push("");
-    const content = memFiles["stack.md"].replace(/^---[\s\S]*?---\n/, "").trim();
+    const content = memFiles["stack.md"].replace(/^---[\s\S]*?---\n?/, "").trim();
     lines.push(content);
     lines.push("");
   }
@@ -7671,6 +7671,7 @@ Setze diese Umgebungsvariablen:`);
   } else if (subcommand === "onboard") {
     const outputArg = rest.includes("--output") ? rest[rest.indexOf("--output") + 1] : null;
     const outputPath = outputArg ?? path32.join(projectRoot, "ONBOARDING.md");
+    fs31.mkdirSync(path32.dirname(outputPath), { recursive: true });
     const doc = generateOnboardingDoc(projectRoot, forgehiveDir);
     fs31.writeFileSync(outputPath, doc, "utf8");
     console.log(`\u2714 Onboarding-Dokument geschrieben: ${outputPath}`);
@@ -7680,12 +7681,11 @@ Setze diese Umgebungsvariablen:`);
     const since = sinceArg ?? getLatestTag(projectRoot) ?? void 0;
     const rawLog = getGitLogSince(projectRoot, since);
     const commits = parseGitLog(rawLog);
-    let pkg = {};
+    let pkgVersion = "unreleased";
     try {
-      pkg = JSON.parse(fs31.readFileSync(path32.join(projectRoot, "package.json"), "utf8"));
+      pkgVersion = JSON.parse(fs31.readFileSync(path32.join(projectRoot, "package.json"), "utf8")).version ?? "unreleased";
     } catch {
     }
-    const pkgVersion = pkg.version ?? "unreleased";
     const md = formatChangelog(commits, pkgVersion);
     const outputPath = outputArg ?? path32.join(projectRoot, "CHANGELOG.md");
     let existing = "";
@@ -7698,31 +7698,9 @@ Setze diese Umgebungsvariablen:`);
       console.error("Usage: fh docs adr <titel>");
       process.exit(1);
     }
-    const adrsDir = path32.join(forgehiveDir, "memory", "adrs");
-    fs31.mkdirSync(adrsDir, { recursive: true });
-    const existing = fs31.readdirSync(adrsDir).filter((f) => f.endsWith(".md")).length;
-    const adrId = String(existing + 1).padStart(4, "0");
-    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-    const filename = `${adrId}-${slug}.md`;
-    const content = `# ADR-${adrId}: ${title}
-
-**Datum:** ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
-**Status:** proposed
-
-## Kontext
-
-(Beschreibe das Problem oder die Situation.)
-
-## Entscheidung
-
-(Beschreibe die getroffene Entscheidung.)
-
-## Konsequenzen
-
-(Beschreibe die Auswirkungen dieser Entscheidung.)
-`;
-    fs31.writeFileSync(path32.join(adrsDir, filename), content, "utf8");
-    console.log(`\u2714 ADR erstellt: .forgehive/memory/adrs/${filename}`);
+    const adrPath = createAdr(forgehiveDir, projectRoot, title);
+    const adrFilename = path32.relative(projectRoot, adrPath);
+    console.log(`\u2714 ADR erstellt: ${adrFilename}`);
   } else {
     console.error("Verf\xFCgbar: fh docs [list|user|api|onboard|changelog|adr <titel>]");
   }

package/docs/user-guide.md

@@ -1,6 +1,6 @@
 # forgehive — User Guide
 
-> Version 0.7.6 · [npm](https://www.npmjs.com/package/forgehive) · `npm install -g forgehive`
+> Version 0.7.7 · [npm](https://www.npmjs.com/package/forgehive) · `npm install -g forgehive`
 
 forgehive (`fh`) gives Claude Code persistent memory about your project. Without it, Claude forgets everything between sessions — your stack, your conventions, your decisions. With it, Claude opens every session already knowing your codebase.
 
@@ -17,7 +17,7 @@ Requires **Node.js ≥ 18** and **Claude Code** (`claude` CLI). Installs two ali
 Verify:
 
 ```bash
-fh --version   # prints 0.7.6
+fh --version   # prints 0.7.7
 fh --help      # full command reference
 ```
 
@@ -106,7 +106,12 @@ The memory files in `.forgehive/memory/` are the most important part of forgehiv
 
 ```bash
 fh docs adr "Use Postgres over MongoDB"
-fh memory adr list    # list all ADRs
+```
+
+**List all ADRs:**
+
+```bash
+fh memory adr list
 ```
 
 **View all memory:**

package/forgehive/commands/fh-refactor.md

@@ -0,0 +1,116 @@
+You are running the ForgeHive refactor workflow.
+
+## Refactor Workflow
+
+**Agenten:** Kai (Plan) → Viktor + Sam + Eli (parallel)
+
+**Mission:** Strukturierter Code-Umbau — erst verstehen und planen, dann parallel implementieren, testen und dokumentieren.
+
+## Protocol
+
+### Step 0: Scope klären
+
+Frage den User:
+
+---
+
+**Was soll refactored werden?**
+
+Gib eine der folgenden Angaben:
+- **Freie Beschreibung** — z.B. „die Docs-Generierung soll sauberer modularisiert werden"
+- **Dateipfade** — z.B. `src/docs.ts`, `src/cli.ts`
+- **Ziel-Statement** — z.B. „extrahiere generateUserGuide in ein eigenes Modul"
+
+---
+
+Wenn der Scope unklar ist: frage nach, bis das Ziel eindeutig ist.
+
+Dann führt **Kai** (Principal Engineer) die Ist-Analyse durch:
+1. Lese alle betroffenen Dateien
+2. Führe `git diff HEAD` aus (aktuelle uncommitted Änderungen)
+3. Liste alle Exports der Scope-Dateien und wo sie importiert werden
+4. Identifiziere Abhängigkeiten (wer importiert was aus den Scope-Dateien)
+
+### Step 1: Refactor-Plan erstellen (Kai)
+
+Erstelle folgenden Plan:
+
+```
+## Refactor-Plan: <Ziel>
+
+**Ziel:** <Ein Satz>
+
+**Betroffene Dateien:**
+- src/foo.ts → src/foo/index.ts + src/foo/helpers.ts
+
+**Bewegte Exports:**
+- `helperFn` aus foo.ts → foo/helpers.ts (re-exportiert aus foo/index.ts)
+
+**Breaking Changes:** keine / [Liste]
+
+**Risiken:** [z.B. zirkuläre Imports möglich bei X]
+
+**Nicht geändert:** [öffentliche API, bestehende Tests für Y, ...]
+```
+
+⚠️ **USER-APPROVAL GATE** — kein Code ohne explizites OK. Warte auf Bestätigung.
+
+### Step 2: Parallel Party starten
+
+Nach Approval:
+
+```bash
+fh party run refactor
+```
+
+Alle drei Agenten erhalten Kai's genehmigten Refactor-Plan als Kontext.
+
+**Viktor** (Systems Architect):
+- Implementiert die Änderungen Datei für Datei nach Plan
+- Darf nicht ohne User-Freigabe vom Plan abweichen
+- Meldet unvorhergesehene Abhängigkeiten explizit
+
+**Sam** (Quality Architect):
+- Liest bestehende Tests für betroffene Dateien
+- Schreibt neue Tests für umbenannte/verschobene Exports
+- Fixiert Tests die durch den Refactor brechen
+- Führt Testsuit am Ende aus — alle grün?
+
+**Eli** (Documentation Architect):
+- Aktualisiert Inline-Kommentare in geänderten Dateien
+- Aktualisiert Referenzen in README und docs/
+- Schreibt CHANGELOG-Eintrag für den Refactor
+
+### Step 3: Verifikation
+
+```bash
+fh party status
+```
+
+Synthesebericht erstellen:
+
+```
+## Refactor-Abschlussbericht
+
+### Viktor — Implementierung
+[Was wurde umgebaut]
+
+### Sam — Tests
+[Welche Tests angepasst/neu — Teststatus: ✅ alle grün / ⚠️ N fehlgeschlagen]
+
+### Eli — Dokumentation
+[Was wurde aktualisiert]
+
+### Offene Punkte
+[Was blieb unerledigt oder braucht Follow-up]
+
+### Verdict: ✅ Fertig / ⚠️ Offen
+```
+
+Abschlussfrage: **„Soll ich direkt einen Commit erstellen?"**
+
+### Step 4: Cleanup
+
+```bash
+fh party cleanup
+```

package/forgehive/commands/review-party.md

@@ -8,55 +8,74 @@ You are running a Review Party using ForgeHive.
 
 ## Protocol
 
-### Step 1: Launch the party
+### Step 0: Scope selection
+
+**Before doing anything else**, ask the user what to review:
+
+---
+
+**Was soll reviewed werden?**
+
+1. **Aktuelle Änderungen** — uncommitted working tree (`git diff HEAD`)
+2. **Letzter Commit** — `git diff HEAD~1..HEAD`
+3. **Branch vs main** — alles seit dem Abzweigen (`git diff main...HEAD`)
+4. **Letzte N Commits** — Anzahl angeben
+5. **Commit-Range** — z.B. `abc123..def456`
+6. **Spezifische Dateien** — Dateipfade angeben
+7. **PR** — PR-Nummer oder Branch-Name angeben
+
+---
+
+Wait for the user's answer. Then resolve the scope to a concrete `git diff` command and show the `--stat` output to confirm:
 
-Run:
 ```bash
-fh party run --set review
+# Example for option 3:
+git diff main...HEAD --stat
 ```
 
-This spins up isolated git worktrees for Kai, Sam, and Eli. Each agent reviews the current diff in parallel.
-
-### Step 2: Set the scope
+If the diff is empty or the result looks wrong, say so and ask the user to clarify before proceeding.
 
-Before the party starts, specify what is being reviewed — a branch name, a PR, or a commit range:
+### Step 1: Launch the party
 
+Once the scope is confirmed, run:
 ```bash
-git diff main...HEAD --stat   # show what changed
+fh party run review
 ```
 
-Share this with the party so all three agents review the same surface area.
+This spins up isolated git worktrees for Kai, Sam, and Eli.
+
+### Step 2: Dispatch agents in parallel
 
-### Step 3: Parallel review
+Pass each agent the confirmed scope and diff summary. Each agent works independently:
 
-**Kai** (Principal Engineer) — in his worktree:
-- Reviews code quality and correctness
+**Kai** (Principal Engineer):
+- Reviews code quality and correctness within the scoped diff
 - Flags bugs, logic errors, and anti-patterns
 - Checks for ambiguous naming, hidden coupling, and missing error handling
 - Labels findings: `[BUG]`, `[DESIGN]`, `[NIT]`, `[Q]`, `[+]`
 
-**Sam** (Quality Architect) — in his worktree:
+**Sam** (Quality Architect):
 - Checks test coverage for the changed code
 - Identifies missing edge cases, error states, and boundary conditions
-- Flags paths that are high-risk but untested
-- Proposes specific tests for any gaps found
+- Flags high-risk untested paths
+- Proposes specific tests for gaps
 
-**Eli** (Documentation Architect) — in his worktree:
-- Checks if README and docs reflect the changes
+**Eli** (Documentation Architect):
+- Checks if README and docs reflect the changes in scope
 - Flags missing or outdated inline documentation
-- Reviews any CHANGELOG entries for accuracy
+- Reviews CHANGELOG entries for accuracy
 - Checks that public API changes are documented
 
-### Step 4: Check status
+### Step 3: Check status
 
-After each agent completes their review:
+After each agent completes:
 ```bash
 fh party status
 ```
 
-### Step 5: Synthesize findings
+### Step 4: Synthesize findings
 
-Collect the three reports and merge them into a unified review:
+Merge the three reports into a unified review:
 
 1. **Blocking issues** — anything from Kai or Sam that must be fixed before merge
 2. **Test gaps** — Sam's missing coverage items
@@ -65,7 +84,7 @@ Collect the three reports and merge them into a unified review:
 
 Present the synthesized report to the user and ask: **"Soll ich die Blocking Issues direkt fixen?"**
 
-### Step 6: Cleanup
+### Step 5: Cleanup
 
 ```bash
 fh party cleanup

package/forgehive/party/defaults.yaml

@@ -41,3 +41,11 @@ sets:
     models:
       vera: claude-opus-4-7
       sam: claude-sonnet-4-6
+  refactor:
+    agents: [viktor, sam, eli]
+    trigger: "/fh-refactor"
+    description: "Refactor — Implementierung + Tests + Doku parallel"
+    models:
+      viktor: claude-opus-4-7
+      sam: claude-sonnet-4-6
+      eli: claude-sonnet-4-6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgehive",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Context-aware AI development environment — one binary, your stack.",
   "type": "module",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "files": [
     "dist/",
-    "docs/",
+    "docs/user-guide.md",
     "forgehive/"
   ],
   "keywords": [