forgehive 0.9.0 → 1.0.0

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-369%20passing-success" alt="369 tests">
-  <img src="https://img.shields.io/badge/bundle-293KB-lightgrey" alt="293KB bundle">
+  <img src="https://img.shields.io/badge/tests-493%20passing-success" alt="493 tests">
+  <img src="https://img.shields.io/badge/bundle-302.3KB-lightgrey" alt="302.3KB bundle">
   <img src="https://img.shields.io/badge/license-Elastic%202.0-orange" alt="Elastic License 2.0">
 </p>
 
@@ -33,7 +33,10 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 - **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
+- **Party Mode** — specialized agent sets; build/design use worktrees, review/security use real independent subagents
+- **Autonomous Loop** — `fh auto` runs a story through plan → implement → test → PR with minimal human intervention
+- **Outcome Tracking** — unified JSONL log of all runs; per-agent performance aggregates feed `fh next`
+- **Intelligence Layer** — `fh next` detects your lifecycle phase and recommends the single most valuable action
 - **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
@@ -48,9 +51,9 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 
 ---
 
-## Status: v0.8.0 — Stable
+## Status: v1.0.0 — Stable
 
-369 passing tests back the commands listed below. The v0.8 feature set has been validated end-to-end.
+493 passing tests back the commands listed below. The v1.0 feature set has been validated end-to-end.
 
 **Stable — use with confidence:**
 
@@ -76,6 +79,14 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 | `fh product status` — PRD → Epic → Story pipeline tree | stable |
 | `fh product roadmap` — generate ROADMAP.md | stable |
 | `fh epic create --prd PRD-N` — link epic to a PRD | stable |
+| `fh status` — daily driver dashboard (sprint · code health · watch events · next) | stable |
+| `fh watch --smart` — file watcher with test runner + agent routing | stable |
+| `fh auto` — autonomous development loop (plan → implement → test → PR) | stable |
+| `fh auto --auto` — fully automated mode (skips gate-1 and gate-2 checkpoints) | stable |
+| `fh auto resume / status / list` — run management | stable |
+| `fh outcomes` — unified outcome store (auto + party runs, per-agent aggregates) | stable |
+| `fh next` — intelligence layer (phase detection + next-step recommendation) | stable |
+| Smart Party Mode — review/security parties use real subagents (independent opinions) | stable |
 | `fh onboard` — generates ONBOARDING.md | stable |
 | `fh changelog` — semantic changelog from git | stable |
 | `fh metrics` — developer metrics by author/type | stable |
@@ -138,7 +149,7 @@ npm link           # makes 'fh' available globally
 Verify the installation:
 
 ```bash
-fh --version       # should print 0.8.0
+fh --version       # should print 1.0.0
 fh --help          # lists all available commands
 ```
 
@@ -193,7 +204,7 @@ fh security report gdpr   # generates a CISO-ready compliance report
 | `fh init` | Set up forgehive in the current project. Use --force to re-initialize an existing setup |
 | `fh confirm` | Confirm `capabilities.yaml` — activates context for Claude |
 | `fh rollback` | Remove `.forgehive/` and the CLAUDE.md block cleanly |
-| `fh status` | Show current project status, drift warning if scan is outdated |
+| `fh status` | Daily driver dashboard — sprint, code health, watch events |
 
 > Running `fh init` on a project that already has `.forgehive/` prints a warning and exits. Use `fh init --force` to re-initialize (overwrites `capabilities.yaml` and scans again). To update only the scan, use `fh scan --update`.
 
@@ -216,7 +227,7 @@ The scan stores a hash of the project state. `fh scan --check` compares the curr
 
 | Command | Description |
 |---|---|
-| `fh status` | Show status of `.forgehive/`, confirmation state, last scan date |
+| `fh status` | Daily driver dashboard — sprint progress, code health, and last 5 watch events |
 | `fh cost` | Show Claude session costs from `~/.claude/` (all time) |
 | `fh cost today` | Costs for today only |
 | `fh cost week` | Costs for the current week |
@@ -228,6 +239,137 @@ The scan stores a hash of the project state. `fh scan --check` compares the curr
 
 ---
 
+### Daily Driver Dashboard
+
+```bash
+fh status
+```
+
+Opens the **Daily Driver Dashboard** — a three-section overview designed for the start of every session:
+
+**Sprint** — lists all `in-sprint` stories and `active` epics from `.forgehive/memory/`.
+
+**Code Health** — working-tree cleanliness (git status), days since last security scan (`.forgehive/security-last-scan.txt`), and number of open GitHub PRs (`.forgehive/github-pr-cache.json`).
+
+**Watch Events** — the last 5 events from `.forgehive/watch-events.jsonl` (test runs, failures, agent prompts logged by `fh watch --smart`).
+
+`fh status` is automatically called by Claude at session start when the forgehive CLAUDE.md block is present.
+
+---
+
+### Smart File Watcher
+
+```bash
+fh watch --smart
+```
+
+Watches `src/` and `test/` directories. On every save:
+
+1. Runs your project's test command (detected from `capabilities.yaml`)
+2. On failure: classifies the error type and prompts to start the right agent:
+   - Security/vulnerability/CVE keywords → **Vera** (security analyst)
+   - Type/interface/logic errors → **Kai** (senior engineer)
+   - Test/assertion/coverage failures → **Sam** (QA architect)
+3. Appends a structured event to `.forgehive/watch-events.jsonl` (visible in `fh status`)
+
+The event log rotates automatically at 500 entries (~25 KB).
+
+```bash
+fh watch             # standard watch mode (no routing)
+fh watch --smart     # watch + test runner + agent routing
+```
+
+---
+
+### Autonomous Development Loop
+
+```bash
+fh auto US-3                    # plan + implement + test + open PR for story US-3
+fh auto --auto US-3             # same, but skip both human checkpoints
+fh auto "fix the login timeout" # freetext — creates a story card, then runs
+fh auto resume <run-id>         # resume a paused or interrupted run
+fh auto status                  # show all active runs with current phase
+fh auto list                    # list all runs (active + completed)
+```
+
+`fh auto` runs a story through an 8-phase state machine and exits at each checkpoint for human review. The phases:
+
+| Phase | What happens |
+|---|---|
+| `analyzing` | Reads the story card and project context |
+| `planning` | Generates an implementation plan (saved to `runs/<id>/plan.md`) |
+| `gate-1` | **Human checkpoint** — review the plan before implementation starts |
+| `implementing` | Claude implements the plan on a new branch (`feat/US-N`) |
+| `testing` | Runs the test suite; records `testsPassed` in `outcomes.jsonl` |
+| `escalating` | Tests failed — Claude attempts a fix (up to 3 attempts) |
+| `gate-2` | **Human checkpoint** — review the diff before PR is opened |
+| `gate-stuck` | All 3 attempts failed — **always escalates to human, never skippable** |
+| `pr-creating` | Opens a PR via `gh pr create` |
+| `done` | Run complete; outcome recorded |
+
+With `--auto`, `gate-1` and `gate-2` are skipped automatically. `gate-stuck` is never skipped regardless of flags. Run state is persisted to `.forgehive/runs/<run-id>/state.yaml` — runs survive session restarts and can be resumed with `fh auto resume`.
+
+---
+
+### Outcome Tracking
+
+```bash
+fh outcomes                     # summary table: last 10 runs, per-agent averages
+```
+
+`fh outcomes` shows a summary of all runs logged to `.forgehive/outcomes.jsonl`. Both `fh auto` runs and review/security party runs write to this store.
+
+**Auto run signals:** `testsPassed`, `attempts` (up to 3), `prMerged` (updated lazily on next status check)
+
+**Party run signals:** `findingsCount`, `blockingCount` (Kai), `testGaps` (Sam), `docGaps` (Eli)
+
+**Rating:** After each review party, ForgeHive asks `[1-5 oder Enter zum Überspringen]`. The rating is stored in the run's outcome entry and feeds `fh next` recommendations.
+
+The store rotates automatically at 500 entries (keeps last 400) — same pattern as `watch-events.jsonl`.
+
+---
+
+### Intelligence Layer
+
+```bash
+fh next                         # show current phase and primary recommendation
+```
+
+`fh next` tells you exactly what to do next — which lifecycle phase you're in and the single most valuable action. It also appears as a compact Section 4 in `fh status`.
+
+**Phase detection (8 rules, priority order):**
+
+| Phase | Condition |
+|---|---|
+| `health-check` | Security scan age > 7 days |
+| `implementing` | Stories in-sprint + active `fh auto` run or no open PRs |
+| `review` | Stories in-sprint + open PRs with no recent review party |
+| `closing-sprint` | Done stories not yet in velocity record |
+| `planning` | Stories in backlog, none in-sprint |
+| `kickoff` | No stories at all |
+| `solutioning` | Epics exist with no linked stories |
+
+**Recommendations include outcome refinement** when ≥ 3 historical data points exist for an agent + task type:
+
+```
+Phase: Implementation
+
+  2 Stories in Sprint:
+    US-3: Add rate limiting to auth endpoints
+    US-5: Fix session timeout bug
+
+Empfehlung:
+  → fh auto US-3
+    Kai löst deine Bug-Fixes im Schnitt 8 Min (40% schneller als Ø)
+
+Auch fällig:
+  → fh security scan  (letzter Scan vor 9 Tagen)
+```
+
+At most one secondary recommendation is ever shown — highest priority wins when multiple hygiene items apply.
+
+---
+
 ### Security Suite
 
 The security suite consists of five commands:
@@ -633,7 +775,18 @@ fh party cleanup            # remove finished worktrees
 fh party --model-map "viktor:claude-opus-4-7,kai:claude-sonnet-4-6,sam:claude-haiku-4-5"
 ```
 
-**How isolation works:** `fh party run` creates one git worktree per agent under `.forgehive/worktrees/<agent-name>/`. Each agent works in its own branch and filesystem copy. Worktrees are cleaned up with `fh party cleanup` or automatically when the session ends cleanly.
+**Party execution modes:**
+
+| Set | Mode | Reason |
+|---|---|---|
+| `build` (Viktor + Kai + Sam) | Worktrees | Write code in parallel — filesystem isolation required |
+| `design` (Suki + Viktor) | Worktrees | Design artifacts + code — isolation required |
+| `review` (Kai + Sam + Eli) | Subagents | Review only — real independent opinions matter more than isolation |
+| `security` (Vera + Sam) | Subagents | Security review + test gap analysis — no code writing |
+
+**How worktree isolation works:** `fh party run` creates one git worktree per agent under `.forgehive/worktrees/<agent-name>/`. Each agent works in its own branch and filesystem copy. Worktrees are cleaned up with `fh party cleanup` or automatically when the session ends cleanly.
+
+**How subagent parties work:** Review and security parties spawn independent `claude -p` subprocesses with focused context (diff only — no full project history). Each agent responds independently and cannot see the other agents' output. ForgeHive synthesizes the three reviews into a final verdict.
 
 ---
 
@@ -1001,9 +1154,9 @@ Global credential store (chmod 600). Managed exclusively via `fh mcp auth` comma
 |---|---|
 | Runtime | Node.js ≥ 18, ESM |
 | Language | TypeScript |
-| Build | esbuild -> `dist/cli.js` (~293 KB, single bundle) |
+| Build | esbuild -> `dist/cli.js` (~302.3 KB, single bundle) |
 | Type check | `tsc --noEmit` |
-| Tests | `node:test` (native) + tsx ESM loader, 369 tests |
+| Tests | `node:test` (native) + tsx ESM loader, 398 tests |
 | Dependencies | `js-yaml` (sole runtime dependency) |
 
 ```bash
@@ -1018,6 +1171,8 @@ npm test            # node --import tsx/esm --test test/*.test.ts
 
 | Version | What's new |
 |---|---|
+| **1.0.0** | Autonomous Loop (`fh auto`), Outcome Tracking (`fh outcomes`), Smart Party Mode (subagent-based review/security), Intelligence Layer (`fh next`) |
+| **0.9.0** | Daily Driver: `fh status` dashboard (sprint · code health · watch events), `fh watch --smart` (test runner + agent routing), session-start auto-status |
 | **0.8.0** | GitHub Integration (`fh github setup/sync/pr`), Semantic Repo-Map (`fh map --semantic`), Intelligent Routing (`fh ask`), Product Workflow (`fh product prd/status/roadmap`) |
 | **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 |