repowise-dev
diff --git a/‎Makefile‎
Lines changed: 12 additions & 0 deletions b/‎Makefile‎
Lines changed: 12 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 29 additions & 4 deletions b/‎README.md‎
Lines changed: 29 additions & 4 deletions
diff --git a/‎docs/CLI_REFERENCE.md‎
Lines changed: 35 additions & 0 deletions b/‎docs/CLI_REFERENCE.md‎
Lines changed: 35 additions & 0 deletions
diff --git a/‎docs/CODE_HEALTH.md‎
Lines changed: 189 additions & 0 deletions b/‎docs/CODE_HEALTH.md‎
Lines changed: 189 additions & 0 deletions
@@ -53,6 +53,18 @@ check: lint format-check typecheck  ## Run all checks (no modifications)
 
 fix: format lint  ## Format + lint with auto-fix
 
+# ---------------------------------------------------------------------------
+# Code Health (Phase 4)
+# ---------------------------------------------------------------------------
+
+health-check:  ## Run the code-health analyzer against this repo and fail on regressions
+	uv run pytest tests/unit/health/ tests/unit/server/test_mcp.py -v
+	uv run repowise health --format json > /tmp/repowise-health-report.json || true
+	@echo "Health report → /tmp/repowise-health-report.json"
+
+health-bench:  ## Run the 3,000-file health analyzer perf benchmark
+	uv run pytest tests/integration/test_health_perf_benchmark.py -v -m slow
+
 # ---------------------------------------------------------------------------
 # Web UI
 # ---------------------------------------------------------------------------
 
@@ -3,7 +3,7 @@
 <img src=".github/assets/logo.png" width="280" alt="repowise" /><br />
 **The codebase intelligence layer for your AI coding agent.**
 
-Four intelligence layers. Eight MCP tools. Multi-repo workspaces. Auto-sync hooks. One `pip install`.
+Five intelligence layers. Nine MCP tools. Multi-repo workspaces. Auto-sync hooks. One `pip install`.
 
 [![PyPI version](https://img.shields.io/pypi/v/repowise?color=F59520&labelColor=0A0A0A)](https://pypi.org/project/repowise/)
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--v3-F59520?labelColor=0A0A0A)](https://www.gnu.org/licenses/agpl-3.0)
@@ -84,6 +84,21 @@ The layer nobody else has. Architectural decisions captured from git history, in
 
 These become structured decision records, queryable by Claude Code via `get_why()`.
 
+### ◈ Code Health Intelligence
+Twelve deterministic biomarkers compute a 1–10 health score per file — McCabe complexity, deep nesting, brain methods, native Rabin–Karp duplication detection, untested hotspots, primitive obsession, developer congestion, knowledge loss, and more. **Zero LLM calls, zero new runtime dependencies** — pure Python over tree-sitter and git data, designed to finish in under 30 seconds on a 3 000-file repo.
+
+Ingest LCOV, Cobertura, or Clover coverage reports to light up the test-coverage biomarkers. Rolling 50-row snapshot history powers `Declining Health` and `Predicted Decline` alerts. Deterministic, rule-based refactoring suggestions surface on the dashboard and via `get_health(include=["refactoring"])`. Per-file overrides via `.repowise/health-rules.json`.
+
+```bash
+repowise health                       # KPIs + lowest-scoring files
+repowise health --coverage cov.lcov   # ingest coverage, light up untested-hotspot
+repowise health --refactoring-targets # ranked by impact / effort
+repowise health --trend               # last 10 snapshots + alerts
+repowise status                       # one-line summary in the status report
+```
+
+See [`docs/CODE_HEALTH.md`](docs/CODE_HEALTH.md) for the user guide and [`docs/architecture/code-health.md`](docs/architecture/code-health.md) for the internals.
+
 ---
 
 ## Quickstart
@@ -175,7 +190,7 @@ Full guide: [docs/WORKSPACES.md](docs/WORKSPACES.md)
 
 ---
 
-## Eight MCP tools
+## Nine MCP tools
 
 Most tools are designed around data entities — one module, one file, one symbol — which forces AI agents into long chains of sequential calls. repowise tools are designed around **tasks**. Pass multiple targets in one call. Get complete context back. Every response carries an `_meta` envelope with `index_age_days`, `indexed_commit`, and a `stale_warning` that fires only when the indexed HEAD diverges from live `.git/HEAD` — silence means the index is current. Full reference: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)
 
@@ -189,6 +204,7 @@ Most tools are designed around data entities — one module, one file, one symbo
 | `get_risk(targets, changed_files?)` | Hotspot scores, dependents, co-change partners, ownership, test gaps, security signals. Pass `changed_files` for PR mode → response carries a `directive` block (`will_break`, `missing_cochanges`, `missing_tests`) for one-glance review plus cross-repo blast radius. | Before modifying files — understand what could break |
 | `get_why(query?, targets?)` | Architectural decision records, their status (active / proposed / deprecated / superseded), and the commits that are evidence for them. Falls back to git archaeology when no ADRs exist for a file. | Before architectural changes — understand existing intent |
 | `get_dead_code(min_confidence?, include_internals?)` | Unreachable code sorted by confidence tier with cleanup impact estimates. In workspace mode, cross-repo consumer detection lowers confidence on findings that other repos import. | Cleanup tasks |
+| `get_health(targets?, include?)` | Twelve deterministic biomarker scores per file. Dashboard mode returns KPIs + the lowest-scoring files + a per-module NLOC-weighted rollup; targeted mode returns per-file findings. `include` flags layer richer data: `"coverage"`, `"refactoring"` (rule-based suggestions), `"trend"` (snapshot diff + declining/predicted-decline alerts). `module:foo` targets expand to a module's file set. | Before refactoring — find the worst-scoring files and what to fix first |
 
 ### Tool call comparison — a real task
 
@@ -197,7 +213,7 @@ Most tools are designed around data entities — one module, one file, one symbo
 | Approach | Tool calls | Time to first change | What it misses |
 |---|---|---|---|
 | Claude Code alone (no MCP) | grep + read ~30 files | ~8 min | Ownership, prior decisions, hidden coupling |
-| **repowise (8 tools)** | **5 calls** | **~2 min** | **Nothing** |
+| **repowise (9 tools)** | **5 calls** | **~2 min** | **Nothing** |
 
 The 5 calls for that task:
 
@@ -457,11 +473,20 @@ The "why" usually walks out the door — when a teammate leaves, or when you reo
 | Auto-generated documentation | ✅ | ✅ Gemini | ✅ | ✅ PR2Doc | ❌ |
 | Private repo — no cloud | ✅ | ❌ in development | ❌ OSS forks only | ✅ Enterprise tier | ✅ |
 | Dead code detection | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Code health score (1–10) | ✅ 12 biomarkers | ❌ | ❌ | ❌ | ✅ 25–30 |
+| Brain Method detection | ✅ | ❌ | ❌ | ❌ | ✅ |
+| Complexity biomarkers | ✅ native tree-sitter | ❌ | ❌ | ❌ | ✅ |
+| Test coverage intelligence | ✅ LCOV/Cobertura/Clover | ❌ | ❌ | ❌ | ❌ |
+| Untested hotspot detection | ✅ coverage × hotspot | ❌ | ❌ | ❌ | ❌ |
+| DRY violation detection | ✅ native (no npm) | ❌ | ❌ | ❌ | ✅ |
+| Health trend tracking | ✅ rolling 50 snapshots | ❌ | ❌ | ❌ | ✅ |
+| Declining health alerts | ✅ | ❌ | ❌ | ❌ | ✅ |
+| Refactoring recommendations | ✅ deterministic | ❌ | ❌ | ❌ | ✅ |
 | Git intelligence (hotspots, ownership, co-changes) | ✅ | ❌ | ❌ | ❌ | ✅ |
 | Bus factor analysis | ✅ | ❌ | ❌ | ❌ | ✅ |
 | Architectural decision records | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Multi-repo workspace intelligence | ✅ co-changes, contracts, federated MCP | ❌ | ❌ | ❌ | ❌ |
-| MCP server for AI agents | ✅ 8 tools | ❌ | ✅ 3 tools | ✅ | ✅ |
+| MCP server for AI agents | ✅ 9 tools | ❌ | ✅ 3 tools | ✅ | ✅ |
 | Proactive agent hooks | ✅ PreToolUse + PostToolUse | ❌ | ❌ | ❌ | ❌ |
 | Auto-generated CLAUDE.md | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Doc freshness scoring | ✅ | ❌ | ❌ | ⚠️ staleness only | ❌ |
 
@@ -257,6 +257,41 @@ repowise dead-code resolve <id>          # mark resolved / false positive
 
 ---
 
+### `repowise health [PATH]`
+
+Compute per-file code-health scores from twelve deterministic biomarkers (CCN, nesting, brain methods, duplication, untested hotspots, organizational risk). Zero LLM calls — pure Python over tree-sitter + git data. See [`docs/CODE_HEALTH.md`](./CODE_HEALTH.md) for the user guide and [`docs/architecture/code-health.md`](./architecture/code-health.md) for the internals.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--file <path>` | Deep-dive a single file (relative path) |
+| `--module <prefix>` | Restrict the report to files whose path starts with this prefix |
+| `--refactoring-targets` | Print top refactoring candidates ranked by impact / effort |
+| `--trend` | Print the last 10 health snapshots + any active alerts (declining / predicted decline) |
+| `--coverage <path>` | Ingest a coverage report (LCOV / Cobertura / Clover). Repeat for multiple files |
+| `--coverage-format` | Override coverage-format auto-detection: `lcov`, `cobertura`, `clover` |
+| `--format` | Output: `table` (default), `json`, `md` |
+| `--safe-only` | Confidence ≥ 0.8 only (placeholder for v1 biomarkers) |
+| `--repo` | In workspace mode, target a specific repo (defaults to primary) |
+| `--no-workspace` | Force single-repo mode |
+
+```bash
+repowise health                                       # KPIs + lowest-scoring files
+repowise health --file packages/server/.../app.py     # one file in detail
+repowise health --module packages/server              # restrict to a directory
+repowise health --refactoring-targets                 # ranked by impact / effort
+repowise health --trend                               # snapshot history + alerts
+repowise health --coverage coverage.lcov              # ingest coverage
+repowise health --format json | jq .kpis              # machine-readable
+```
+
+`repowise init` and `repowise update` populate the health tables automatically —
+no separate command needed. `repowise status` shows a one-line summary
+(`Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: <path>)`).
+
+---
+
 ### `repowise decision`
 
 Manage architectural decision records.
 
@@ -0,0 +1,189 @@
+# Code Health
+
+Repowise computes a 1–10 health score for every file in your repo from twelve
+deterministic biomarkers — McCabe complexity, deep nesting, brain methods,
+clone detection, untested hotspots, organizational risk, and more. **No LLM
+calls, no cloud requirement.** Pure Python over tree-sitter + git data,
+designed to finish in under 30 seconds on a 3 000-file repo.
+
+## Quick start
+
+```bash
+repowise init          # full index — populates health tables
+repowise health        # KPIs + 20 worst-scoring files + top findings
+repowise update        # re-score only changed files on each subsequent run
+```
+
+Open `http://localhost:7777/repos/<id>/health` for the dashboard once the
+local server is running (`repowise serve`).
+
+## The score
+
+Each file starts at 10.0. Biomarker findings deduct from the score; deductions
+are capped per category so any one category can drive the score down by at
+most:
+
+| Category               | Cap   | Biomarkers |
+|------------------------|-------|------------|
+| Structural complexity  | −3.5  | brain_method, nested_complexity, bumpy_road |
+| Size & complexity      | −2.0  | complex_method, large_method, primitive_obsession |
+| Duplication            | −1.5  | dry_violation |
+| Test coverage          | −2.0  | untested_hotspot, coverage_gap |
+| Organizational         | −1.0  | developer_congestion, knowledge_loss |
+
+The final score is clamped to `[1.0, 10.0]`. The three repo-level KPIs:
+
+- **Hotspot Health** — NLOC-weighted average over the top-25 % hotspot files.
+- **Average Health** — NLOC-weighted average over all files.
+- **Worst Performer** — single lowest-scoring file.
+
+## The 12 biomarkers
+
+**brain_method** — A single function that is simultaneously long, deeply
+nested, highly complex, and central to the dependency graph. The strongest
+single signal of fragile code.
+
+**nested_complexity** — Functions with control-flow nesting ≥ 4 levels.
+Hard to read, hard to test, hard to refactor.
+
+**bumpy_road** — Multiple branches stacked at the same depth — usually a
+sign the function is doing several jobs that should be split.
+
+**complex_method** — Cyclomatic complexity ≥ 9. Each branch is a path the
+test suite has to cover.
+
+**large_method** — Functions that exceed the NLOC threshold. Length on its
+own is not always a bug, so this is a milder signal.
+
+**primitive_obsession** — Many primitive parameters in one signature. A
+dataclass or parameter object would name the inputs.
+
+**dry_violation** — Cross-file code clones, detected by a native Rabin–Karp
+rolling hash over tree-sitter tokens (variable renames don't hide a clone).
+Pairs are ranked by co-change so dormant duplicates rank lower than active
+ones.
+
+**untested_hotspot** — A hotspot file with low or zero coverage and many
+dependents. The textbook "write tests before refactoring" case.
+
+**coverage_gap** — Non-test files with meaningful uncovered surface.
+Severity grades along coverage depth.
+
+**developer_congestion** — Too many active authors touching the same file.
+Usually an ownership problem dressed up as a code problem.
+
+**knowledge_loss** — The primary authors of the file are no longer active
+on the project. Refactor while someone still remembers why.
+
+## Test coverage
+
+Pass coverage reports straight into the analyzer:
+
+```bash
+pytest --cov --cov-report=lcov:coverage.lcov
+repowise health --coverage coverage.lcov
+
+# Cobertura, Clover, or multiple sources also work:
+repowise health \
+  --coverage backend/coverage.xml --coverage-format cobertura \
+  --coverage frontend/lcov.info
+```
+
+Coverage data feeds into `untested_hotspot` and `coverage_gap`, and shows up
+on the `/repos/<id>/health/coverage` dashboard.
+
+## Refactoring targets
+
+```bash
+repowise health --refactoring-targets
+```
+
+Ranks candidates by `total_impact / effort_bucket` so the biggest wins for
+the least work surface first. Each row carries a deterministic, rule-based
+suggestion (`"Split this function. It carries high cyclomatic complexity..."`).
+
+For agentic workflows, the same data is one MCP call away:
+
+```python
+get_health(include=["refactoring"])           # dashboard + suggestions
+get_health(targets=["src/api/server.py"])     # one file in detail
+get_health(targets=["module:src.api"])        # everything in a module
+```
+
+## Trends
+
+Every health run writes a `HealthSnapshot` row (rolling 50 entries per repo).
+Two alerts run over the history:
+
+- **Declining Health** — current `hotspot_health` is ≥ 0.5 below the
+  snapshot 5 runs ago.
+- **Predicted Decline** — the three most recent snapshots are each
+  strictly below the one before.
+
+Inspect from the CLI:
+
+```bash
+repowise health --trend
+```
+
+Or from MCP:
+
+```python
+get_health(include=["trend"])
+```
+
+## Configuration
+
+Per-file overrides live in `.repowise/health-rules.json`:
+
+```json
+{
+  "disabled_biomarkers": ["primitive_obsession"],
+  "rules": [
+    {
+      "glob": "tests/**/*.py",
+      "disabled_biomarkers": ["large_method", "complex_method"]
+    },
+    {
+      "glob": "src/legacy/**",
+      "disabled_biomarkers": ["dry_violation"]
+    }
+  ]
+}
+```
+
+## Incremental updates
+
+`repowise update` only re-scores the changed files. Findings and metrics for
+unchanged files stay put — no nightly full re-index needed.
+
+## Status one-liner
+
+`repowise status` includes a single-line health summary:
+
+```
+Health: 7.4 (avg) · 6.2 (hotspots) · 2.1 (worst: payments/processor.ts)
+```
+
+## Comparison
+
+| Feature                          | Repowise | CodeScene | DeepSource | Sourcery |
+|----------------------------------|:--:|:--:|:--:|:--:|
+| Code health score (1–10)         | ✅ 12 biomarkers | ✅ 25–30 | ❌ | ❌ |
+| Brain Method detection           | ✅ | ✅ | ❌ | ❌ |
+| Test coverage intelligence       | ✅ LCOV/Cobertura/Clover | ❌ | ❌ | ❌ |
+| Untested hotspot detection       | ✅ coverage × hotspot | ❌ | ❌ | ❌ |
+| DRY violation detection          | ✅ native (no npm) | ✅ | ❌ | ❌ |
+| Health trend tracking            | ✅ | ✅ | ❌ | ❌ |
+| Declining health alerts          | ✅ | ✅ | ❌ | ❌ |
+| Refactoring recommendations      | ✅ deterministic | ✅ | ❌ | ❌ |
+| Free for internal use            | ✅ AGPL-3.0 | ❌ $15–30/author | ✅ public repos | ❌ |
+
+## See also
+
+- [`packages/core/src/repowise/core/analysis/health/README.md`][hr] —
+  developer overview of the layer.
+- Sub-package READMEs: `complexity/`, `coverage/`, `duplication/`,
+  `biomarkers/`.
+
+[hr]: ../packages/core/src/repowise/core/analysis/health/README.md