Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs(health): rename user-facing "biomarker" to "marker" (display copy only) (#619)

Raghav Chamadiya0ccc986e0471
diff --git a/README.md b/README.md
index befe114f1..ec8083f95 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ enough: you need to know **where** the risk concentrates and **how** to fix it.
repowise closes that loop. It indexes your codebase once and scores **every file
for defect risk, maintainability, and performance** from 25 deterministic
-biomarkers, calibrated against a real defect corpus, no LLM, in under 30 seconds
+markers, calibrated against a real defect corpus, no LLM, in under 30 seconds
([the proof ↓](#-code-health-the-layer-nobody-else-nails)). The same index then
**locates** the risk through a real dependency graph and git history, and
**generates the fix**: concrete, graph-aware refactoring plans (split this god
@@ -89,7 +89,7 @@ Each layer is queryable from the CLI, the MCP tools, and the local dashboard.
| **◈ Git** | hotspots (churn × complexity) · ownership % · co-change pairs (hidden coupling) · bus factor · contributor profiles · module health · reviewer suggestions | Behavioral signals static analysis can't see |
| **◈ Docs** | LLM-generated wiki per module/file · incremental on every commit · freshness + confidence scoring · hybrid RAG search (FTS + vector via RRF) · selectable wiki styles (comprehensive / reference / tutorial / caveman) | Stays current, rebuilt every commit |
| **◈ Decisions** | architectural decisions mined from **8 sources**, evidence-backed (verified / fuzzy / unverified), linked to graph nodes, connected by `supersedes`/`refines`/`conflicts_with` edges, tracked for staleness | **★ Captured nowhere else** |
-| **★ Code Health** | **25 deterministic biomarkers**, 1–10 per file · **three signals: defect risk · maintainability · performance** · coverage ingestion · trend alerts · **concrete graph-aware refactoring plans** (Extract Class / Helper / Move Method / Break Cycle / Split File) · **zero LLM, <30s** | **★ Defect-validated, with the fix attached. Our edge** |
+| **★ Code Health** | **25 deterministic markers**, 1–10 per file · **three signals: defect risk · maintainability · performance** · coverage ingestion · trend alerts · **concrete graph-aware refactoring plans** (Extract Class / Helper / Move Method / Break Cycle / Split File) · **zero LLM, <30s** | **★ Defect-validated, with the fix attached. Our edge** |
Full deep-dive on every layer (graph, git, docs, decisions, hooks, auto-sync,
dead code, CLAUDE.md generation): **[docs/INTELLIGENCE_LAYERS.md →](docs/INTELLIGENCE_LAYERS.md)**
@@ -105,10 +105,10 @@ concentrates through the graph and git history, then **fix** it with a concrete
refactoring plan your agent can execute.
<div align="center">
-<img src=".github/assets/health-loop.svg" alt="repowise code-health loop: 25 deterministic biomarkers fan into three signals (defect risk, maintainability, performance), the graph and git history locate where risk concentrates, and refactoring intelligence emits concrete plans (Extract Class, Extract Helper, Move Method, Break Cycle, Split File) your agent executes" width="100%" />
+<img src=".github/assets/health-loop.svg" alt="repowise code-health loop: 25 deterministic markers fan into three signals (defect risk, maintainability, performance), the graph and git history locate where risk concentrates, and refactoring intelligence emits concrete plans (Extract Class, Extract Helper, Move Method, Break Cycle, Split File) your agent executes" width="100%" />
</div>
-repowise scores **every file 1–10** from **25 deterministic biomarkers**:
+repowise scores **every file 1–10** from **25 deterministic markers**:
McCabe complexity, deep nesting, brain methods, class cohesion (LCOM4), god
classes, native Rabin–Karp clone detection, untested hotspots, function-level
churn, code-age volatility, ownership dispersion, change entropy, co-change
@@ -116,7 +116,7 @@ scatter, prior-defect history, test-quality smells, and more.
**Three signals, one index.** The headline 1–10 is **defect risk**: the
defect-calibrated, bug-predictive score in the table below. From the same
-biomarker stream, repowise surfaces two co-equal companion views:
+marker stream, repowise surfaces two co-equal companion views:
**maintainability** (cohesion, brain methods, DRY and god-class smells that
raise change-cost without predicting bugs) and **performance** (static N+1 /
I/O-in-loop risk, followed across files through the call graph: file-local
@@ -126,7 +126,7 @@ headline, so the bug-predictive number stays clean.
> **Zero LLM calls. Zero cloud requirement. Zero new runtime dependencies.**
> Pure Python over tree-sitter + git data, finishing in **under 30 seconds** on
-> a 3,000-file repo. The biomarker weights are **calibrated against a real defect
+> a 3,000-file repo. The marker weights are **calibrated against a real defect
> corpus, not hand-tuned**; only the learned constants ship and the runtime
> stays fully deterministic.
@@ -159,7 +159,7 @@ Ranking by repowise health surfaces **2.3× the defects under a fixed review
budget** (Popt Δ +0.144, recall Δ +0.098, density Δ all p = 0.003, paired and
significant; the ROC AUC edge is marginal). [Full methodology & CIs →](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/COMPARISON_REPORT.md)
-User guide & per-biomarker reference: **[docs/CODE_HEALTH.md](docs/CODE_HEALTH.md)**
+User guide & per-marker reference: **[docs/CODE_HEALTH.md](docs/CODE_HEALTH.md)**
### Refactoring intelligence
@@ -337,7 +337,7 @@ pattern scan) · **Costs** · **Workspace**
| Tier | Languages | What works |
|------|-----------|------------|
-| **Full** | Python · TypeScript · JavaScript · Java · Kotlin · Go · Rust · C++ · C# | AST parsing, import resolution, named bindings, call resolution, heritage extraction, docstrings; multi-project workspace resolvers; framework-aware edges; per-language dynamic-hint extractors; **code-health biomarkers** |
+| **Full** | Python · TypeScript · JavaScript · Java · Kotlin · Go · Rust · C++ · C# | AST parsing, import resolution, named bindings, call resolution, heritage extraction, docstrings; multi-project workspace resolvers; framework-aware edges; per-language dynamic-hint extractors; **code-health markers** |
| **Good** | C · Ruby · Swift · Scala · PHP | AST parsing, import resolution, named bindings, call resolution, heritage (mixins / derive / extensions / traits), docstrings; dedicated workspace-aware resolvers; Rails / Laravel / TYPO3 framework edges; dynamic-hint extractors |
| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · SQL · Terraform · Markdown · Shell | Included in the file tree; special handlers extract endpoints / targets where applicable |
| **Git-blame only** | Objective-C · Elixir · Erlang · Dart · Zig · Julia · Clojure · Haskell · OCaml · F# · … | Tracked in git history (blame, hotspots, co-change); no AST parsing yet |
@@ -445,7 +445,7 @@ diverges from live `.git/HEAD`.
| `get_risk(targets, changed_files?)` | Hotspot scores, dependents, co-change partners, ownership, test gaps, security signals. Pass `changed_files` for PR mode → a `directive` block (`will_break`, `missing_cochanges`, `missing_tests`, `governance_risk`). |
| `get_why(query?, targets?)` | Architectural decision records, status, evidence spans, and the supersession **lineage chain**. Falls back to git archaeology when no ADRs exist. |
| `get_dead_code(...)` | Unreachable code by confidence tier with cleanup-impact estimates; cross-repo consumer detection in workspace mode. |
-| `get_health(targets?, include?)` | Biomarker scores per file across three signals (defect · maintainability · performance). Dashboard mode → KPIs + lowest-scoring files + module rollup; targeted mode → per-file findings. Self-check before a PR via `include`: `accuracy` (does the score find the bugs), `signals` (per-file churn / owners / prior defects), `churn_complexity`, a dimension name to filter findings, plus `coverage`, `trend`, and `refactoring` → **structured, graph-aware refactoring plans** (split groups, move target, cut edges + blast radius), not template strings. |
+| `get_health(targets?, include?)` | Marker scores per file across three signals (defect · maintainability · performance). Dashboard mode → KPIs + lowest-scoring files + module rollup; targeted mode → per-file findings. Self-check before a PR via `include`: `accuracy` (does the score find the bugs), `signals` (per-file churn / owners / prior defects), `churn_complexity`, a dimension name to filter findings, plus `coverage`, `trend`, and `refactoring` → **structured, graph-aware refactoring plans** (split groups, move target, cut edges + blast radius), not template strings. |
Worked example (*"Add rate limiting to all API endpoints"* in 5 calls instead of
~30 greps+reads) and the full reference: **[docs/MCP_TOOLS.md →](docs/MCP_TOOLS.md)**
@@ -462,7 +462,7 @@ Worked example (*"Add rate limiting to all API endpoints"* in 5 calls instead of
| MCP server for AI agents | ✅ 9 tools | ❌ | ✅ 3 tools | ✅ | ✅ |
| Proactive agent hooks | ✅ Claude + Codex hooks | ❌ | ❌ | ❌ | ❌ |
| Auto-generated AI instructions (`CLAUDE.md`, `AGENTS.md`) | ✅ | ❌ | ❌ | ❌ | ❌ |
-| Code health score (1–10) | ✅ 25 biomarkers | ❌ | ❌ | ❌ | ✅ 25–30 |
+| Code health score (1–10) | ✅ 25 markers | ❌ | ❌ | ❌ | ✅ 25–30 |
| Brain Method / LCOM4 / god class | ✅ | ❌ | ❌ | ❌ | ✅ |
| Test-coverage intelligence | ✅ LCOV/Cobertura/Clover | ❌ | ❌ | ❌ | ❌ |
| Untested-hotspot detection | ✅ coverage × hotspot | ❌ | ❌ | ❌ | ❌ |
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md
index 7580da2dc..a8d3e8ecd 100644
--- a/docs/CLI_REFERENCE.md
+++ b/docs/CLI_REFERENCE.md
@@ -355,7 +355,7 @@ See [`docs/CHANGE_RISK.md`](./CHANGE_RISK.md) for the scoring model.
### `repowise health [PATH]`
-Compute per-file code-health scores from 25 deterministic biomarkers (McCabe complexity, nesting, brain methods, LCOM4 cohesion, god classes, native clone detection, untested hotspots, coverage gradient, function/ownership/churn/change-entropy organizational risk, test-quality smells, and more). 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.
+Compute per-file code-health scores from 25 deterministic markers (McCabe complexity, nesting, brain methods, LCOM4 cohesion, god classes, native clone detection, untested hotspots, coverage gradient, function/ownership/churn/change-entropy organizational risk, test-quality smells, and more). 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:**
@@ -368,7 +368,7 @@ Compute per-file code-health scores from 25 deterministic biomarkers (McCabe com
| `--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) |
+| `--safe-only` | Confidence ≥ 0.8 only (placeholder for v1 markers) |
| `--repo` | In workspace mode, target a specific repo (defaults to primary) |
| `--no-workspace` | Force single-repo mode |
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.md
index ffe682cdc..fe1ebaf57 100644
--- a/docs/CODE_HEALTH.md
+++ b/docs/CODE_HEALTH.md
@@ -1,7 +1,7 @@
# Code Health
Repowise computes a 1-10 health score for every file in your repo from twenty-five
-deterministic biomarkers: McCabe complexity, deep nesting, brain methods,
+deterministic markers: McCabe complexity, deep nesting, brain methods,
class cohesion (LCOM4), god classes, clone detection, untested hotspots,
function-level churn, code-age volatility, ownership dispersion, relative churn,
change entropy, co-change scatter, recent defect history, test-quality smells,
@@ -9,7 +9,7 @@ and more. **No LLM calls, no cloud requirement.** Pure Python over tree-sitter
and git data, designed to finish in under 30 seconds on a 3,000-file repo.
<div align="center">
-<img src="../.github/assets/health-loop.svg" alt="repowise code-health loop: 25 deterministic biomarkers fan into three signals (defect risk, maintainability, performance), the graph and git history locate where risk concentrates, and refactoring intelligence emits concrete plans (Extract Class, Extract Helper, Move Method, Break Cycle, Split File) your agent executes" width="100%" />
+<img src="../.github/assets/health-loop.svg" alt="repowise code-health loop: 25 deterministic markers fan into three signals (defect risk, maintainability, performance), the graph and git history locate where risk concentrates, and refactoring intelligence emits concrete plans (Extract Class, Extract Helper, Move Method, Break Cycle, Split File) your agent executes" width="100%" />
</div>
Code health runs as a loop: **measure** every file across three signals,
@@ -40,11 +40,11 @@ local server is running (`repowise serve`).
## The score
-Each file starts at 10.0. Biomarker findings deduct from the score; deductions
+Each file starts at 10.0. Marker 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 |
+| Category | Cap | Markers |
|------------------------|-------|------------|
| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk, change_entropy, co_change_scatter, prior_defect |
| Structural complexity | −2.5 | brain_method, low_cohesion, god_class, nested_complexity, bumpy_road, complex_conditional |
@@ -55,20 +55,20 @@ most:
| Test quality | −0.5 | large_assertion_block, duplicated_assertion_block |
| Error handling | −0.5 | error_handling |
-Twenty-five biomarkers across the categories above. `function_hotspot` and
+Twenty-five markers across the categories above. `function_hotspot` and
`code_age_volatility` are blame-based and sit in the organizational bucket: both
are tier-aware and stay silent on ESSENTIAL-tier repos until the per-line blame
index is built.
-Per-biomarker weight multipliers let the strongest empirical predictors deduct
+Per-marker weight multipliers let the strongest empirical predictors deduct
more than the uniform severity table alone allows. The weights are **calibrated
offline against a defect corpus, not hand-tuned**: each file is scored at the
pre-window commit (T0, no leakage) and a logistic regression with NLOC as an
-explicit control fits each biomarker's defect lift beyond file size. The runtime
+explicit control fits each marker's defect lift beyond file size. The runtime
stays deterministic; only the learned constants ship. The strongest predictors
are `co_change_scatter`, `change_entropy`, `ownership_risk`, and
`nested_complexity`; widely-firing smells that proved weak under leakage-free
-scoring are floored. The full per-biomarker table lives in the
+scoring are floored. The full per-marker table lives in the
[architecture doc](architecture/code-health.md#61-calibrated-weight-multipliers),
and the calibration with confidence intervals is in the
[benchmark report](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/BENCHMARK_REPORT.md).
@@ -84,7 +84,7 @@ The final score is clamped to `[1.0, 10.0]`. The three repo-level KPIs:
## Three health signals: defect risk, maintainability, and performance
Repowise surfaces three orthogonal health signals computed from the same
-biomarker stream by one shared scoring kernel: **defect risk** (the calibrated,
+marker stream by one shared scoring kernel: **defect risk** (the calibrated,
overall number), **maintainability**, and **performance**. They are co-equal
views, never blended into one number (the section on the overall score below
explains why).
@@ -92,7 +92,7 @@ explains why).
The score above is the defect-risk signal: it is calibrated against a defect
corpus, the bands are calibrated to it (Alert files carry roughly 17x the defect
rate of Healthy files), and it is the overall number surfaced everywhere. But
-not every code smell predicts bugs. A handful of biomarkers fire widely and
+not every code smell predicts bugs. A handful of markers fire widely and
matter a lot for how hard code is to read and change, yet proved weak as defect
predictors under leakage-free scoring, so the defect calibration floors them to
0.5 (`low_cohesion`, `brain_method`, `primitive_obsession`, `dry_violation`,
@@ -102,7 +102,7 @@ calibrated signal) and they get no credit for the real problem they describe
(maintainability).
Repowise therefore computes a second, parallel signal, maintainability, from the
-same biomarker stream:
+same marker stream:
- The floored smells above deduct at full weight (1.0) in maintainability
instead of the 0.5 the defect calibration imposes. The defect calibration does
@@ -371,7 +371,7 @@ last 6 months, 3.3x the 24% baseline (80% vs 24%).
It ranks every file by health score, takes the 20 lowest, and counts how many
were touched by a `fix:` commit in the trailing ~180-day window (the same
-signal the `prior_defect` biomarker uses). That precision is contrasted with the
+signal the `prior_defect` marker uses). That precision is contrasted with the
repo-wide base rate (the fraction of all files with a recent fix) to give the
lift. The same number appears on the web `health` and `overview` dashboards,
where it expands into a per-K table (worst 10/20/30), a concentration stat (what
@@ -404,7 +404,7 @@ checked against what actually broke:
is perfect. It beats raw churn by 0.10 AUC and a prior-defects baseline by 0.117
AUC (DeLong p < 1e-9).
- On the public PROMISE/jEdit defect dataset, which played no part in
- calibration, the same biomarkers score AUC **0.76 to 0.78**. That held-out
+ calibration, the same markers score AUC **0.76 to 0.78**. That held-out
result is the main evidence the signal is not overfit.
- The limits ship with the wins. Among files of similar size the signal is weak
(within-size-band AUC near 0.49), so part of the headline is simply that larger
@@ -414,7 +414,7 @@ checked against what actually broke:
Full methodology, confidence intervals, and the named head-to-head against
CodeScene are in the [benchmark hub](https://github.com/repowise-dev/repowise-bench).
-## The biomarkers
+## The markers
**brain_method**: A single function that is simultaneously long, deeply
nested, highly complex, and central to the dependency graph. The strongest
@@ -762,7 +762,7 @@ still shows in the bottom-right ("changes constantly but stays simple").
The file's Health tab lists its functions ranked by modification count, with
the 90-day recent-mod count, median age, and blame owner per function, the
same `git_function_blame` rollup the symbol page uses. It promotes per-function
-ownership and volatility out of the buried biomarker cards into a first-class
+ownership and volatility out of the buried marker cards into a first-class
table, so "which function in this file is the actual hotspot" is one glance away.
## Configuration
@@ -809,10 +809,10 @@ Accepted severity values are `low`, `medium`, `high`, `critical`. The named
noisier structural signals a 1-3 person repo can't support; an explicit
`severity_overrides` key always wins over the preset.
-Only the severity label is tunable. The per-biomarker weight multipliers and
+Only the severity label is tunable. The per-marker weight multipliers and
the category caps are the calibrated constants the benchmark numbers rest on
and are deliberately not overridable, so a team's local policy never changes
-what the published accuracy claims mean. Biomarkers that carry a continuous
+what the published accuracy claims mean. Markers that carry a continuous
deduction (`coverage_gradient`) are unaffected by severity remaps.
## Incremental updates
@@ -839,7 +839,7 @@ real strengths repowise does not claim to beat, noted under the table.
| Capability | Repowise | CodeScene | SonarQube | Code Climate / Qlty¹ | Codacy |
|---|---|---|---|---|---|
-| Per-file health / maintainability score | ✅ 1-10, 25 biomarkers | ✅ 1-10 Code Health | ⚠️ A-E ratings from rule counts | ✅ A-F grade | ✅ A-F grade |
+| Per-file health / maintainability score | ✅ 1-10, 25 markers | ✅ 1-10 Code Health | ⚠️ A-E ratings from rule counts | ✅ A-F grade | ✅ A-F grade |
| Score uses git / behavioral signals (churn, ownership, co-change, hotspots) | ✅ | ✅ its core | ❌ static rules only | ⚠️ churn-vs-complexity, no co-change | ❌ |
| Cross-file / call-graph analysis | ✅ interprocedural call graph | ⚠️ git temporal coupling, not a static call graph | ⚠️ cross-file taint (security only) | ❌ file-local | ❌ file-local |
| Defect-validated score vs a real bug corpus (published numbers) | ✅ mean ROC AUC 0.737, held-out 0.76-0.78 | ⚠️ "Code Red" study (defect density / cycle time), no per-file AUC | ❌ | ❌ | ❌ |
diff --git a/docs/COMMERCIAL.md b/docs/COMMERCIAL.md
index 69dd7d816..d15a14314 100644
--- a/docs/COMMERCIAL.md
+++ b/docs/COMMERCIAL.md
@@ -47,7 +47,7 @@ All of the following ship in `pip install repowise` today, free for internal use
factor, significant commits, contributor profiles, module health), Documentation
(LLM-generated wiki, freshness scoring, RAG search), Decision (architectural
decision records linked to graph nodes, staleness tracking), and Code Health
- (25 deterministic biomarkers, 1–10 score per file, coverage ingestion, trend
+ (25 deterministic markers, 1–10 score per file, coverage ingestion, trend
alerts).
- **Nine task-shaped MCP tools** — `get_overview`, `get_answer`, `get_context`,
`get_symbol`, `search_codebase`, `get_risk`, `get_why`, `get_dead_code`,
diff --git a/docs/COMPUTED_GLOSSARY.md b/docs/COMPUTED_GLOSSARY.md
index f4ac31641..5522a9afa 100644
--- a/docs/COMPUTED_GLOSSARY.md
+++ b/docs/COMPUTED_GLOSSARY.md
@@ -252,7 +252,7 @@ workspace overlays, MCP responses, and CLI output.
| --- | --- | --- | --- |
| ROC AUC (Area Under the ROC Curve) | A ranking-quality measure for a binary classifier. Given one file that later received a bug fix and one that did not, it is the probability the model scores the buggy file as riskier. 0.5 is random, 1.0 is perfect separation. Repowise's defect score reaches a cross-project mean of 0.737 across 21 repositories. | Defect-score benchmark harness (cross-project validation) | `roc_auc: 0.737` |
| Popt (effort-aware ranking) | A normalized cumulative-lift (Alberg-curve) score that ranks files by predicted risk against review effort measured in lines of code. It rewards a model that concentrates real defects in the fewest lines a reviewer would read. 0 is worst, 1 is best. It complements ROC AUC, which ignores file size. | Defect-score benchmark harness (cross-project validation) | `popt: 0.58` |
-| LCOM4 (Lack of Cohesion of Methods, version 4) | The number of connected components formed by a class's methods when two methods are linked if they share a field or one calls the other. 1 means a cohesive class; a value of 2 or more means the methods split into groups that share nothing, a signal the class should be split (the basis of the low_cohesion biomarker and the Extract Class refactoring). | `analysis/health/biomarkers/low_cohesion.py`, `analysis/health/complexity/class_analysis.py` | `lcom4: 3` |
+| LCOM4 (Lack of Cohesion of Methods, version 4) | The number of connected components formed by a class's methods when two methods are linked if they share a field or one calls the other. 1 means a cohesive class; a value of 2 or more means the methods split into groups that share nothing, a signal the class should be split (the basis of the low_cohesion marker and the Extract Class refactoring). | `analysis/health/biomarkers/low_cohesion.py`, `analysis/health/complexity/class_analysis.py` | `lcom4: 3` |
## Search, Answer Cache, And Retrieval
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
index 75b8bf3ab..57b2254af 100644
--- a/docs/CONFIG.md
+++ b/docs/CONFIG.md
@@ -64,7 +64,7 @@ Note: hand-editing `wiki_style` here and running `update` does not regenerate
existing pages, use `restyle`.
> **Code-health rules** are configured separately in
-> `.repowise/health-rules.json` (per-file biomarker overrides); see
+> `.repowise/health-rules.json` (per-file marker overrides); see
> [CODE_HEALTH.md](CODE_HEALTH.md#configuration).
### The `distill:` block
@@ -142,7 +142,7 @@ refactoring:
by default but never runs during indexing, only on an explicit request (set
`llm.enabled: false` to disable it).
- Per-path disables reuse the `.repowise/health-rules.json` glob mechanism (the
- same one biomarkers use).
+ same one markers use).
- Full reference: [REFACTORING.md](REFACTORING.md).
---
diff --git a/docs/INTELLIGENCE_LAYERS.md b/docs/INTELLIGENCE_LAYERS.md
index 34e755861..c2017faf5 100644
--- a/docs/INTELLIGENCE_LAYERS.md
+++ b/docs/INTELLIGENCE_LAYERS.md
@@ -165,7 +165,7 @@ codebase.
## Code Health Intelligence
repowise computes a **1–10 health score for every file** from **25 deterministic
-biomarkers**: McCabe complexity, deep nesting, brain methods, class cohesion
+markers**: McCabe complexity, deep nesting, brain methods, class cohesion
(LCOM4), god classes, native Rabin–Karp clone detection, untested hotspots,
function-level churn, code-age volatility, ownership dispersion, change entropy,
co-change scatter, prior-defect history, test-quality smells, and more.
@@ -174,13 +174,13 @@ co-change scatter, prior-defect history, test-quality smells, and more.
pure Python over tree-sitter and git data, designed to finish in under 30
seconds on a 3,000-file repo.
-The biomarker **weights are calibrated offline against a real defect corpus, not
+The marker **weights are calibrated offline against a real defect corpus, not
hand-tuned**: each file is scored at the pre-window commit (T0, no leakage) and
an L2-logistic regression (with NLOC as an explicit control) fits each
-biomarker's defect lift *beyond* file size. Only the learned constants ship; the
+marker's defect lift *beyond* file size. Only the learned constants ship; the
runtime stays fully deterministic.
-The same biomarker stream produces three orthogonal signals: defect risk
+The same marker stream produces three orthogonal signals: defect risk
(the calibrated headline number), maintainability, and performance risk. These
are co-equal views, never blended into one number. It does not stop at scoring:
the layer closes the loop into concrete, graph-aware refactoring plans
@@ -195,7 +195,7 @@ repowise status # one-line summary in the status report
```
- **Coverage ingestion**: LCOV, Cobertura, Clover, or normalized JSON light up
- the test-coverage biomarkers (`untested_hotspot`, `coverage_gap`,
+ the test-coverage markers (`untested_hotspot`, `coverage_gap`,
`coverage_gradient`).
- **Trend tracking**: a rolling 50-row snapshot history powers `Declining
Health` and `Predicted Decline` alerts.
@@ -211,7 +211,7 @@ repowise status # one-line summary in the status report
- **Per-file overrides** via `.repowise/health-rules.json`.
Validated against real defect history; see
-[`docs/CODE_HEALTH.md`](CODE_HEALTH.md) for the full user guide, the per-biomarker
+[`docs/CODE_HEALTH.md`](CODE_HEALTH.md) for the full user guide, the per-marker
reference, and the calibration story, and
[repowise-bench](https://github.com/repowise-dev/repowise-bench) for the
reproducible defect-prediction and head-to-head benchmarks.
diff --git a/docs/LANGUAGE_SUPPORT.md b/docs/LANGUAGE_SUPPORT.md
index f81f2dd56..698cb163b 100644
--- a/docs/LANGUAGE_SUPPORT.md
+++ b/docs/LANGUAGE_SUPPORT.md
@@ -21,18 +21,18 @@ pipeline stages produce meaningful output.
| Call graph edges | Y | partial | -- | -- | -- |
| Heritage (extends/implements) | Y | partial | -- | -- | -- |
| Named bindings | Y | -- | -- | -- | -- |
-| Code-health biomarkers | Y¹ | -- | -- | -- | -- |
+| Code-health markers | Y¹ | -- | -- | -- | -- |
| Dead code detection | Y | Y | Y | Y | -- |
| Semantic search & wiki pages | Y | Y | Y | Y | Y |
-¹ **Code-health biomarkers** require a per-language complexity-walker map
+¹ **Code-health markers** require a per-language complexity-walker map
(`analysis/health/complexity/languages.py`), independent of `.scm` parsing.
A language is only listed **Full** once it clears the
-[code-health checklist](#code-health-biomarker-coverage) below, except
+[code-health checklist](#code-health-marker-coverage) below, except
**Go**, whose class-level metrics (LCOM4 / god-class) are not computable
because Go methods attach to a type via an external receiver rather than
nesting in a class body; Go gets the function- and assertion-level
-biomarkers but is footnoted on the class-level ones.
+markers but is footnoted on the class-level ones.
---
@@ -71,14 +71,14 @@ All nine languages support:
- For XAML only: `<ResourceDictionary Source="..."/>` and `MergedDictionaries` entries resolve across `pack://application:,,,/`, `ms-appx:///`, repo-rooted and relative URIs, emitting xaml-to-xaml `dynamic_uses` edges
- For JVM (Java + Kotlin together) only: a unified `JvmWorkspaceIndex` warmup parsing Maven `pom.xml` reactors and Gradle `settings.gradle(.kts)` + source-sets + `gradle/libs.versions.toml` version catalogs; one walk groups every `.java` and `.kt` file by package directory so `import com.foo.Bar` fans out to every defining file in the package (siblings share importers), `import com.foo.*` / `import static com.foo.Bar.*` expand to all matching files, same-package implicit identifier access is honoured, and Kotlin↔Java cross-language resolution links callers across both source-roots (including `.kt` files hosted under `src/main/java`); type-reference resolution emits `type_use` edges for parameter / field / return / generic / `new T()` types (unwrapping arrays, generics, nullables), plus Kotlin `companion object` / `object` singleton / method-reference (`Foo::bar`) / `sealed … permits` resolution; source-generator-equivalent synthesis emits the symbols Lombok (`@Data` / `@Value` / `@Builder` / `@RequiredArgsConstructor` / `@Slf4j` / `@UtilityClass` / friends), Java `record`, Kotlin `data class` / `enum class` / `object`, and MapStruct / AutoValue / Immutables would produce at compile time, so a Lombok-only Spring service no longer reads its injected fields as unused; framework edges cover Spring (stereotypes with meta-annotation resolution; `@RequestMapping` family routing; Spring Data `JpaRepository` / `Crud` / `Mongo` / `R2dbc` / `Elasticsearch` / `Neo4j` / `Couchbase` / `Cassandra` interfaces and their derived-query methods as entry points; `@Bean` factories; single-constructor + `@Autowired` / `@Inject` / `@Resource` DI; Lombok-RAC/AAC constructor inference), Jakarta (JAX-RS `@Path`, CDI scopes, Servlet 3+ `@WebServlet`/`@WebFilter`/`@WebListener`, JPA `@Entity` + `@OneToMany`/`@ManyToOne`/`@ManyToMany`/`@OneToOne` association edges; both `javax.*` and `jakarta.*`), Quarkus (entry stereotypes + SmallRye `@Incoming("topic")` ↔ `@Outgoing("topic")` cross-linking), Micronaut (DI / routing, gated on Micronaut imports to disambiguate Spring's collisions), and Android (`AndroidManifest.xml` `android:name` references emit edges to the named class); JVM dynamic hints capture `Class.forName`, Mockito / mockk, MapStruct `Mappers.getMapper`, `SpringApplication.run` and Kotlin `runApplication<>`, Jackson / Gson `readValue` / `fromJson` / `treeToValue`; package-aware dead-code reachability rescues sibling-rescued packages, stereotype-annotated classes, `main(String[])` carriers, and FQNs listed in `META-INF/services/*` / `META-INF/spring.factories` (Boot 2) / `META-INF/spring/...AutoConfiguration.imports` (Boot 3) / JPMS `provides … with …`, all resolved during the workspace warmup; JVM never-flag patterns cover `module-info.java`, `package-info.java`, every conventional test source-set (`src/test/**`, `src/integrationTest/**`, `src/intTest/**`, `src/it/**`, `src/jmh/**`, generic `src/*Test/**`), generated source roots (`build/generated/**`, KAPT/KSP, `target/generated-sources/**`, GraalVM `aotSources`), generated suffix conventions (`Dagger*`, `AutoValue_*`, JPA `*_.java` metamodel, `*Grpc.java`, protoc `*OuterClass.java`), JUnit / TestNG / Spock / ArchUnit test-naming + annotation-marked entry points (`@Test` / `@PostConstruct` / `@EventListener` / `@Scheduled` / `@JmsListener` / `@KafkaListener` / `@RabbitListener` / `@SqsListener` / `@Incoming` / `@Outgoing` / `@Mojo` / `@Bean` / ...), and JVM contract methods (`equals` / `hashCode` / `toString` / `compareTo` / `clone` / serialization `readObject` / `writeObject` / `serialVersionUID` / Lombok `canEqual` / Kotlin `componentN` / `copy` / enum `values` / `valueOf`)
-#### Code-health biomarker coverage
+#### Code-health marker coverage
The code-health layer scores every source file from deterministic
-biomarkers (complexity, cohesion, test-quality, ...). These run off a
+markers (complexity, cohesion, test-quality, ...). These run off a
per-language complexity-walker map
(`analysis/health/complexity/languages.py`) that is **independent** of the
`.scm` ingestion queries: a language can parse perfectly for the graph yet
-still need this map before health biomarkers fire. To keep "Full" meaning
+still need this map before health markers fire. To keep "Full" meaning
"health works", a language must clear this checklist (each item has a green
fixture under `tests/fixtures/lang_samples/<lang>/` + a walker test):
@@ -418,7 +418,7 @@ without touching the shared pipeline files:
complexity walker keeps its own per-language node-type map
(`LanguageNodeMap`), independent of the ingestion `.scm` queries. Add a
map for a language to get McCabe complexity, nesting, cognitive
- complexity, and the per-function biomarkers; optionally set
+ complexity, and the per-function markers; optionally set
`class_kinds` / `self_identifiers` / `member_access_kinds` to also get
class-level metrics (LCOM4 cohesion, god-class), and
`assert_kinds` / `assert_call_kinds` to get test-quality assertion-block
@@ -468,7 +468,7 @@ without touching the shared pipeline files:
Extract Method suggestion --- never a wrong one. Adding a language is one
module plus the `assignment_kinds` / `local_decl_kinds` and control-flow
lines on its `LanguageNodeMap` --- no core edits. The full dataflow pass runs
- only for functions a structural biomarker already flagged
+ only for functions a structural marker already flagged
(`large_method` / `brain_method` / `complex_method`), so it stays within the
health-pass budget.
diff --git a/docs/MCP_TOOLS.md b/docs/MCP_TOOLS.md
index 1468d62d1..6561dda64 100644
--- a/docs/MCP_TOOLS.md
+++ b/docs/MCP_TOOLS.md
@@ -26,7 +26,7 @@ repowise mcp --transport sse --port 7338 # legacy SSE transport
| `get_risk` | Modification risk | Before changing hotspot files |
| `get_why` | Architectural decisions | Before structural changes |
| `get_dead_code` | Unreachable code | Cleanup tasks |
-| `get_health` | Code-health biomarker scores | Before refactoring, find the worst files |
+| `get_health` | Code-health marker scores | Before refactoring, find the worst files |
| `list_repos` | List the repos a server is serving | Discovering workspace repo aliases |
| `get_blast_radius` | Cross-repo downstream impact (workspace only) | Before changing a service other repos consume |
| `get_conformance` | Architecture rule violations + cycles (workspace only) | Auditing or before changing service boundaries |
@@ -425,7 +425,7 @@ get_dead_code(min_confidence=0.8, include_internals=true)
## `get_health`
-Code-health biomarker scores: the same deterministic biomarkers the
+Code-health marker scores: the same deterministic markers the
`repowise health` CLI computes, across three signals (defect risk,
maintainability, performance), exposed for agentic workflows. Zero LLM calls.
Use it to **self-check a change before opening a PR**: the same signals a
@@ -443,7 +443,7 @@ code-health merge-gate judges it on.
**Returns:** Dashboard mode (no `targets`) returns repo-level KPIs (hotspot
health, average health, worst performer, maintainability / performance pillar
averages), the lowest-scoring files, and a per-module NLOC-weighted rollup.
-Targeted mode returns per-file biomarker findings with severity, per-dimension
+Targeted mode returns per-file marker findings with severity, per-dimension
scores, and the score breakdown. Each finding carries a `dimension`
(`defect` / `maintainability` / `performance`).
diff --git a/docs/REFACTORING.md b/docs/REFACTORING.md
index b68163398..be031b723 100644
--- a/docs/REFACTORING.md
+++ b/docs/REFACTORING.md
@@ -20,13 +20,13 @@ computed with no re-parse, **no LLM, no network**, inside the same <30s budget.
LLM layer (code generation) is a separate, strictly opt-in step ([below](#opt-in-code-generation)).
<div align="center">
-<img src="../.github/assets/health-loop.svg" alt="repowise code-health loop: biomarkers fan into three signals, the graph and git history locate risk, and refactoring intelligence emits concrete plans an agent executes" width="100%" />
+<img src="../.github/assets/health-loop.svg" alt="repowise code-health loop: markers fan into three signals, the graph and git history locate risk, and refactoring intelligence emits concrete plans an agent executes" width="100%" />
</div>
## The five detectors
Each detector is a self-contained module registered into a registry (adding a
-refactoring type is a new file + a registry entry, like the biomarker registry).
+refactoring type is a new file + a registry entry, like the marker registry).
A detector degrades to **"no suggestion" on any missing signal, never a wrong
one**, and produces stable-sorted, deterministic output.
@@ -61,7 +61,7 @@ web).
| `file_path`, `target_symbol`, `line_start`, `line_end` | What the refactoring acts on. |
| `plan` | The concrete, type-specific plan: the split `groups` (methods + fields), the move `{method, from_class, to_class}`, the clone `occurrences` + `suggested_site`, the cycle + `cut_edges`, or the file-split `groups` (`{name, symbols, suggested_file}`) + `residual` core + `shim_required`. |
| `evidence` | The signals that justify it: `lcom4`, `wmc`, clone token/line counts + `co_change_count`, Jaccard distances, cycle size, or the split's `modularity` + `symbol_count` + `group_count` + intra/cut edge counts. |
-| `impact_delta` | The health score the refactoring would recover (the deduction of the biomarker it answers); `0` for the graph-native types that answer no biomarker. |
+| `impact_delta` | The health score the refactoring would recover (the deduction of the marker it answers); `0` for the graph-native types that answer no marker. |
| `effort_bucket` | `S` \| `M` \| `L` \| `XL`, from the target's size. |
| `blast_radius` | What else must move: the callers, co-change partners, and importing files. |
| `confidence` | `low` \| `medium` \| `high` (drives the `min_confidence` surface gate). |
@@ -167,7 +167,7 @@ the plan and the reviewable diff, not auto-applied edits.
Per-path disables reuse the existing `.repowise/health-rules.json` glob
mechanism, so a refactoring type can be silenced for generated or vendored paths
-the same way a biomarker is:
+the same way a marker is:
```json
{
@@ -179,7 +179,7 @@ the same way a biomarker is:
## See also
-- [`docs/CODE_HEALTH.md`](CODE_HEALTH.md): the biomarkers and the three health
+- [`docs/CODE_HEALTH.md`](CODE_HEALTH.md): the markers and the three health
signals the suggestions are built on.
- [`docs/INTELLIGENCE_LAYERS.md`](INTELLIGENCE_LAYERS.md): how code health fits
the five-layer index.
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index 95cd472db..838fb0b84 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -388,7 +388,7 @@ This is how you connect repowise to Claude Code, Cursor, Cline, Windsurf, and ot
| `get_risk` | Modification risk assessment — hotspot score, dependents, co-change partners, bus factor, blast radius, test gaps, 0–10 risk score |
| `get_why` | Why code is structured the way it is — architectural decisions, git archaeology. Three modes: NL search, path-based, health dashboard. |
| `get_dead_code` | Tiered dead code report grouped by confidence with cleanup impact estimates |
-| `get_health` | 25-biomarker code-health scores — dashboard KPIs + lowest-scoring files, or per-file findings; `include` for refactoring suggestions and trend alerts |
+| `get_health` | 25-marker code-health scores — dashboard KPIs + lowest-scoring files, or per-file findings; `include` for refactoring suggestions and trend alerts |
In workspace mode, tools are workspace-aware — pass `repo="backend"` to target a specific repo or `repo="all"` to query across the entire workspace. The default repo is used when `repo` is omitted.
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index fbdacbdc2..409e42502 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -3,10 +3,10 @@
Companion to the user-facing [`docs/CODE_HEALTH.md`](../CODE_HEALTH.md). This
document is for contributors: where every piece lives, how data flows from
parsed source to the dashboard, and the extension points for adding
-biomarkers, languages, coverage formats, or alerts.
+markers, languages, coverage formats, or alerts.
> **TL;DR.** Health analysis is a deterministic, zero-LLM Python pipeline:
-> tree-sitter walks every file once -> biomarkers vote -> scores aggregate per
+> tree-sitter walks every file once -> markers vote -> scores aggregate per
> category -> results land in four SQLAlchemy tables. The MCP server, CLI,
> and Next.js dashboard all read from those tables: no JSON cache, no
> intermediate files, no LLM in the loop.
@@ -45,7 +45,7 @@ them. Its only writes are to its own four tables.
Three architectural rules govern the whole layer:
-1. **Zero LLM.** Every biomarker is AST, git, or coverage math.
+1. **Zero LLM.** Every marker is AST, git, or coverage math.
2. **No JSON caches.** SQLite is the single source of truth; everything
else reads from it.
3. **No new runtime dependencies.** Pure Python over tree-sitter (already
@@ -275,20 +275,20 @@ paths (`git_meta_map[path]["is_hotspot"]`), and the analyzer returns a
Duplication runs **once up-front** (it is cross-file by nature); each
`FileContext` gets a slice of the global clone report. The `dry_violation`
-biomarker reads `ctx.clones` and ranks pairs by co-change frequency from
+marker reads `ctx.clones` and ranks pairs by co-change frequency from
`git_meta_map[path]["co_change_partners_json"]`, so active clones rank higher
than dormant ones.
---
-## 5. The 26 biomarkers and their categories
+## 5. The 26 markers and their categories
-Each biomarker is a stateless class implementing the `Biomarker` Protocol from
+Each marker is a stateless class implementing the `Biomarker` Protocol from
`biomarkers/base.py`: a `name` (`"brain_method"`, `"nested_complexity"`, ...), a
`category` (see `scoring.CATEGORY_CAPS`), and a `detect(ctx: FileContext)` method
returning a list of `BiomarkerResult`s.
-| Category | Cap | Biomarkers |
+| Category | Cap | Markers |
|------------------------|------|------------|
| Organizational | −3.5 | developer_congestion, knowledge_loss, hidden_coupling, function_hotspot, code_age_volatility, ownership_risk, churn_risk, change_entropy, co_change_scatter, prior_defect |
| Structural complexity | −2.5 | brain_method, low_cohesion, god_class, nested_complexity, bumpy_road, complex_conditional |
@@ -373,7 +373,7 @@ and decayed with the same τ=180d half-life as co-change. The decay-weighted sum
per file is `git_meta["change_entropy"]`. `enrich.compute_percentiles` then
derives `change_entropy_pct` by ranking **only files with positive entropy**
(zero-entropy files, the ESSENTIAL tier or files only ever changed alone,
-keep pct 0.0 so the biomarker stays silent). Both fields are persisted on
+keep pct 0.0 so the marker stays silent). Both fields are persisted on
`git_metadata` (migration `0025`) and the additive-reconcile path back-fills
them on legacy DBs.
@@ -391,7 +391,7 @@ references (a static utility, or an unmapped language) reports `lcom4 = 1`
turn signal on, never produce a false-positive flood. See
`complexity/README.md` for the full heuristic and its limits.
-`error_handling` is the **advisory maintainability** biomarker: swallowed
+`error_handling` is the **advisory maintainability** marker: swallowed
catches (an empty/comment-only `catch` / `except: pass` body), Python
catch-all `except:` / `except Exception:`, Rust `.unwrap()` / `.expect()` /
panic-family macros, and Go's empty `if err != nil {}` or blank-identifier
@@ -399,7 +399,7 @@ discard of a call's error. The walker collects each occurrence (with its
line) in a whole-tree pass (module-level code included) reusing the
`LanguageNodeMap` catch kinds for the seven catch-shaped languages and
dedicated recognizers for Rust/Go; an unsupported language or parse failure
-yields no hits ("no signal", never a guess). The biomarker emits one LOW
+yields no hits ("no signal", never a guess). The marker emits one LOW
finding per occurrence (0.15 after its floored 0.5 weight) in its own
`error_handling` category capped at −0.5, mirroring `test_quality`'s
advisory framing. It is deliberately **excluded from the defect-weight
@@ -433,7 +433,7 @@ via `registered_biomarkers(extra=...)`.
Every file starts at **10.0**. Each finding contributes a per-severity
deduction (`low=0.3, medium=0.7, high=1.2, critical=2.0`), scaled by the
-biomarker's calibrated weight multiplier (§6.1). `score_file()` then groups the
+marker's calibrated weight multiplier (§6.1). `score_file()` then groups the
weighted findings by category, sums the raw deductions per category, and either
accepts the sum or, when it exceeds the cap, scales every per-finding deduction
in that category proportionally so the total equals the cap. This keeps the
@@ -445,7 +445,7 @@ The per-finding scaled deduction lands on `HealthFinding.health_impact`
via `attach_impacts()`: that's what the dashboard's "−2.0" badge shows.
Snapshot tests in `tests/unit/health/test_scoring_snapshot.py` lock the
-category caps, severity deductions, biomarker-to-category mapping, and two
+category caps, severity deductions, marker-to-category mapping, and two
known-fixture scores. A retune intentionally requires updating the
snapshot in the same PR.
@@ -455,25 +455,25 @@ snapshot in the same PR.
deduct more than the uniform severity table alone allows. The multipliers are
**calibrated offline against a defect corpus, not hand-tuned**: each file is
scored at the pre-window commit (T0, no leakage) and an L2-logistic regression,
-with NLOC as an explicit control, fits each biomarker's defect lift beyond file
+with NLOC as an explicit control, fits each marker's defect lift beyond file
size. The runtime stays deterministic; only the learned constants ship. The
full calibration, with confidence intervals, is published in the
[benchmark report](https://github.com/repowise-dev/repowise-bench/blob/master/health-defect/BENCHMARK_REPORT.md)
and reproduced by `local-stash/calibrate_health_weights.py`.
-| Weight | Biomarkers | Rationale |
+| Weight | Markers | Rationale |
|---|---|---|
| 1.8 | `co_change_scatter` | Strongest calibrated predictor. |
| 1.51 | `change_entropy` | History Complexity Metric; second strongest. |
| 1.38 | `ownership_risk` | Long-run minor-contributor dispersion. |
| 1.34 | `nested_complexity` | Strongest structural predictor. |
-| 1.1–1.33 | remaining structural complexity / size biomarkers | Moderate calibrated lift. |
+| 1.1–1.33 | remaining structural complexity / size markers | Moderate calibrated lift. |
| 1.3 / 1.2 / 1.1 | `untested_hotspot` / `churn_risk` / `code_age_volatility` | Coverage-dependent and rarely-firing; keep prior weights the corpus could not fairly measure. |
| 1.0 | `prior_defect` | Neutral by design: largely redundant with the other process signals, kept for its explanatory value. |
| 0.5 (floored) | `developer_congestion`, `dry_violation`, `low_cohesion`, `brain_method`, `primitive_obsession`, `bumpy_road` | Fire widely but proved weak under leakage-free scoring; kept as maintainability and parity signals, not disabled. |
| 0.4 (de-rated) | `knowledge_loss` | Weakest of the floored set. |
-The same biomarker stream feeds the **maintainability** signal under an
+The same marker stream feeds the **maintainability** signal under an
independent, expert-set weight table (the floored smells deduct at full weight
there), and the **performance** signal under its own bounded `performance`
category. The three signals share one scoring kernel against separate
@@ -536,7 +536,7 @@ health-breakdown response, and the standalone trend route (§13).
### Per-file signals (`signals.py`)
The same state-free pattern, applied to the git-layer + topology fields we
-already persist but only buried inside biomarker detail cards (or omitted
+already persist but only buried inside marker detail cards (or omitted
entirely). `file_signals(git_meta, degrees)` joins one `GitMetadata` row with
the file's graph degree into a `FileSignals` grouped as **Process**
(`prior_defect_count`, `change_entropy_pct` normalized 0-100, 90-day line
@@ -580,7 +580,7 @@ Four tables, all in the repo's `.repowise/wiki.db`. Foreign-keyed to
### `health_findings`
-One row per biomarker hit. Lifecycle: `open → acknowledged | resolved |
+One row per marker hit. Lifecycle: `open → acknowledged | resolved |
false_positive` (matches Dead Code). Bulk-deleted-and-rewritten on full
init; selectively upserted on `repowise update`.
@@ -593,7 +593,7 @@ init; selectively upserted on `repowise update`.
| `severity` | `low` / `medium` / `high` / `critical` |
| `function_name` | nullable for file-level findings |
| `line_start`, `line_end` | nullable |
-| `details_json` | per-biomarker evidence (CCN values, clone span, etc.) |
+| `details_json` | per-marker evidence (CCN values, clone span, etc.) |
| `health_impact` | per-finding scaled deduction |
| `reason` | one-line summary string |
| `status` | lifecycle |
@@ -622,7 +622,7 @@ KPI + per-file score history. Rolling delete on insert keeps the latest
### `coverage_files`
Per-file coverage, overwritten on every `--coverage` run. Carries the
-explicit `covered_lines_json` array so the `coverage_gap` biomarker can
+explicit `covered_lines_json` array so the `coverage_gap` marker can
flag the exact uncovered surface, not just the percent.
---
@@ -686,7 +686,7 @@ Defined in `tool_health.py`. Modes:
`top_biomarkers`, `coverage_pct`, `branch_coverage_pct`.
- `get_context(targets, include=["health"])`: per-file `score`,
`max_ccn`, `max_nesting`, `nloc`, `module`, `duplication_pct`, top
- 2 biomarkers (each with a `suggestion` string), a coverage block, and a
+ 2 markers (each with a `suggestion` string), a coverage block, and a
null-dropped `signals` block (process/people/topology, see §8).
- `get_overview()`: adds a `code_health` block: avg, repo `band`, hotspot,
worst performer, open finding count, and the NLOC-weighted `distribution`.
@@ -729,7 +729,7 @@ Three routes under `/repos/[id]/health/`:
|---|---|
| `/health` | KPI cards, lowest-scoring file table, top findings, **per-module rollup** (added in Phase 4) |
| `/health/coverage` | Coverage summary, untested-hotspot warnings, module-level bars, per-file drill-down |
-| `/health/refactoring-targets` | Cards sorted by impact-per-effort, each with severity, biomarker, score, NLOC, effort bucket, **deterministic suggestion** |
+| `/health/refactoring-targets` | Cards sorted by impact-per-effort, each with severity, marker, score, NLOC, effort bucket, **deterministic suggestion** |
Plus a sidecar `HealthRisksPanel` on the Hotspots, Ownership, and Graph
pages: surfaces the lowest-scoring files inline without touching the
@@ -804,11 +804,11 @@ Other perf notes:
| Suite | What it locks |
|---|---|
| `tests/unit/health/test_complexity_walker.py` | Per-language CCN, nesting, cognitive assertions on handcrafted fixtures |
-| `tests/unit/health/test_<biomarker>.py` | Each biomarker: positive in two languages + one negative |
+| `tests/unit/health/test_<biomarker>.py` | Each marker: positive in two languages + one negative |
| `tests/unit/health/test_duplication.py` | Tokenizer normalization, rolling-hash determinism, co-change weighting |
| `tests/unit/health/test_coverage_parsers.py` | LCOV / Cobertura / Clover / repowise-JSON happy paths + edge cases |
| `tests/unit/health/test_scoring.py` | Deduction caps, clamping, KPI math |
-| `tests/unit/health/test_scoring_snapshot.py` | **Stability guard**: caps, severity table, biomarker-to-category mapping, two known fixture scores |
+| `tests/unit/health/test_scoring_snapshot.py` | **Stability guard**: caps, severity table, marker-to-category mapping, two known fixture scores |
| `tests/unit/health/test_trends.py` | Declining + predicted alerts, ordering, per-file series + `file_trend` |
| `tests/unit/health/test_signals.py` | `file_signals` join: no-signal vs real-zero, entropy 0-1 to 0-100, owner handoff |
| `tests/unit/health/test_churn_complexity.py` | `churn_complexity_points`: no-churn omission, complexity never filters, danger-product sort, percentile scaling |
@@ -824,11 +824,11 @@ Other perf notes:
## 19. Extension points
-### Add a biomarker
+### Add a marker
1. New file under `biomarkers/` implementing the `Biomarker` Protocol.
2. Append to `_DETECTOR_FACTORIES` in `biomarkers/registry.py`.
-3. Add the biomarker-to-category mapping in
+3. Add the marker-to-category mapping in
`scoring._BIOMARKER_CATEGORY`.
4. Add a suggestion template in `suggestions._TEMPLATES`.
5. Add at least three test cases (two positive in different languages,
@@ -892,8 +892,8 @@ phases may revisit; the constraints kept v1 shippable.
|---|---|
| Tweak a category cap | `scoring.CATEGORY_CAPS` (snapshot test will fail; update it) |
| Tweak a severity deduction | `scoring._SEVERITY_DEDUCTION` (ditto) |
-| Add a new biomarker | `biomarkers/*.py`, `registry.py`, `scoring.py`, `suggestions.py` |
-| Change the suggestion text for a biomarker | `suggestions._TEMPLATES` |
+| Add a new marker | `biomarkers/*.py`, `registry.py`, `scoring.py`, `suggestions.py` |
+| Change the suggestion text for a marker | `suggestions._TEMPLATES` |
| Adjust the trend-alert threshold | `trends.DECLINE_THRESHOLD` / `DECLINE_LOOKBACK` |
| Change snapshot retention | `crud.HEALTH_SNAPSHOT_RETENTION` |
| Add a new MCP `include` flag | `tool_health.py`: append handling near the existing `"coverage"` / `"refactoring"` branches |
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd.py b/packages/cli/src/repowise/cli/commands/health_cmd.py
index d729228bd..69d8152e6 100644
--- a/packages/cli/src/repowise/cli/commands/health_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/health_cmd.py
@@ -1,4 +1,4 @@
-"""``repowise health`` — code-health biomarker report.
+"""``repowise health`` — code-health marker report.
Mirrors the dead-code CLI: ingest → analyze → render. Reads from
``HealthFileMetric`` / ``HealthFinding`` if a fresh index exists, falls
@@ -43,7 +43,7 @@ from repowise.cli.helpers import (
"--safe-only",
is_flag=True,
default=False,
- help="Phase-3 placeholder — currently a no-op for v1 biomarkers.",
+ help="Phase-3 placeholder — currently a no-op for v1 markers.",
)
@click.option(
"--repo",
@@ -124,7 +124,7 @@ def health_command(
trend_view: bool,
badge_view: bool,
) -> None:
- """Compute code-health scores from biomarkers (CCN, nesting, brain-method).
+ """Compute code-health scores from markers (CCN, nesting, brain-method).
Runs in-process — no LLM, no network. Re-uses the repowise ingestion
parser, graph builder, and git indexer.
@@ -414,10 +414,10 @@ def health_command(
console.print(table)
if findings:
- console.print(f"\n[bold]{len(findings)}[/bold] biomarker findings:")
+ console.print(f"\n[bold]{len(findings)}[/bold] marker findings:")
f_table = Table()
f_table.add_column("Severity", style="magenta")
- f_table.add_column("Biomarker", style="cyan")
+ f_table.add_column("Marker", style="cyan")
f_table.add_column("File")
f_table.add_column("Function")
f_table.add_column("Impact", justify="right")
@@ -683,7 +683,7 @@ def _render_refactoring_targets(
table.add_column("Impact", justify="right")
table.add_column("Effort", justify="center")
table.add_column("Ratio", justify="right")
- table.add_column("Primary biomarker")
+ table.add_column("Primary marker")
for t in targets:
table.add_row(
t["file_path"],
diff --git a/packages/core/src/repowise/core/analysis/health/README.md b/packages/core/src/repowise/core/analysis/health/README.md
index 1a90a4b02..6e5dbc839 100644
--- a/packages/core/src/repowise/core/analysis/health/README.md
+++ b/packages/core/src/repowise/core/analysis/health/README.md
@@ -1,7 +1,7 @@
# Code Health analysis layer
Fifth intelligence layer alongside Graph, Git, Docs, and Decisions. Computes a
-per-file health score (1.0–10.0) from twenty-six deterministic biomarkers,
+per-file health score (1.0–10.0) from twenty-six deterministic markers,
ingests test-coverage data, tracks repo-level KPIs over time, and surfaces
refactoring targets ranked by impact-per-effort.
@@ -32,7 +32,7 @@ report = analyzer.analyze(changed_files={"a.py", "b.py"})
### Returned shapes
-- `report.findings` — `list[HealthFindingData]`. One row per biomarker hit.
+- `report.findings` — `list[HealthFindingData]`. One row per marker hit.
- `report.metrics` — `list[HealthFileMetricData]`. One row per analyzed file.
- `report.kpis` — `{"hotspot_health", "average_health", "worst_performer_path",
"worst_performer_score", "file_count"}`. Skipped on incremental runs.
@@ -43,7 +43,7 @@ Three SQLAlchemy tables back the layer (Alembic-managed, no JSON files):
| Table | Purpose | Writer |
|-------|---------|--------|
-| `health_findings` | One row per biomarker hit. Lifecycle: `open` → `acknowledged` / `resolved` / `false_positive`. | `save_health_findings` / `upsert_health_findings` |
+| `health_findings` | One row per marker hit. Lifecycle: `open` → `acknowledged` / `resolved` / `false_positive`. | `save_health_findings` / `upsert_health_findings` |
| `health_file_metrics` | Per-file aggregate + final score. | `save_health_metrics` / `upsert_health_metrics` |
| `health_snapshots` | KPI history (50-row rolling window). | `save_health_snapshot` |
| `coverage_files` | Per-file coverage (line + branch). | `save_coverage_files` |
@@ -115,7 +115,7 @@ Hotspots & churn dashboard tab.
`suggestions.suggestion_for(biomarker_type)` returns the canonical, static
text used by both the MCP `get_health(include=["refactoring"])` response and
the dashboard's `RefactoringCard`. Templates live in `suggestions.py` —
-adding a new biomarker means adding a new `_TEMPLATES` entry.
+adding a new marker means adding a new `_TEMPLATES` entry.
## Module rollups
@@ -147,7 +147,7 @@ extension points.
## Extension points
-- **New biomarker.** Drop a file under `biomarkers/`, implement
+- **New marker.** Drop a file under `biomarkers/`, implement
`Biomarker.detect(ctx) -> list[BiomarkerResult]`, register in
`biomarkers/registry.py`, add a suggestion in `suggestions.py`, add the
category mapping in `scoring._BIOMARKER_CATEGORY`.
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/README.md b/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
index ce96c30d8..c2f98cd61 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/README.md
@@ -98,7 +98,7 @@ Error handling (cap −0.5, own category `error_handling`):
pass in the complexity walker, so module-level code is covered too.
Caps were recalibrated to lift `organizational` (was −1.0) and de-rate
-`size_and_complexity` / `duplication` per plan §3.1. A per-biomarker
+`size_and_complexity` / `duplication` per plan §3.1. A per-marker
weight multiplier in `scoring._BIOMARKER_WEIGHT_MULTIPLIER` lets the
strongest empirical predictors deduct more than the uniform severity
table alone would allow.
@@ -134,7 +134,7 @@ dict (JSON-serialised into `HealthFinding.details_json` for the UI), and a
`reason` string. `health_impact` is filled in by the scorer. An optional
`deduction` field carries a continuous deduction magnitude (health points,
pre-weight/pre-cap); when set the scorer uses it instead of the discrete
-severity → deduction table, letting a biomarker (e.g. `coverage_gradient`)
+severity → deduction table, letting a marker (e.g. `coverage_gradient`)
express a per-finding signal that varies continuously while staying linear and
attributable.
@@ -149,12 +149,12 @@ attributable.
## Extension points
-To add a 13th biomarker:
+To add a 13th marker:
1. New file `biomarkers/my_marker.py` with a class implementing the
`Biomarker` protocol.
2. Append to `_DETECTOR_FACTORIES` in `registry.py`.
-3. Add the biomarker → category mapping in `scoring._BIOMARKER_CATEGORY`.
+3. Add the marker → category mapping in `scoring._BIOMARKER_CATEGORY`.
4. Add a suggestion template in `suggestions._TEMPLATES`.
5. Add a unit test under `tests/unit/health/`.
6. Update this README's "Registered v1 detectors" list.
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py
index b5bac04ab..131a9ae39 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/brain_method.py
@@ -1,7 +1,7 @@
"""Brain Method — long, complex, and central in one symbol.
-CodeScene's signature biomarker: a function that does too much. We flag
-when **all three** conditions hold:
+A function that does too much. We flag when **all three** conditions
+hold:
- NLOC ≥ 70 (the function is long)
- CCN ≥ 9 (it has many decision paths)
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/bumpy_road.py b/packages/core/src/repowise/core/analysis/health/biomarkers/bumpy_road.py
index d7d64ab8a..fd2c8c048 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/bumpy_road.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/bumpy_road.py
@@ -3,12 +3,11 @@
A "bumpy road" function is one with several distinct nesting humps —
not one deep block (that's `nested_complexity`) and not one big linear
list of branches (that's `complex_method`) but multiple medium-depth
-blocks sitting side by side. SonarSource's terminology.
+blocks sitting side by side.
We use the walker's ``bumps`` metric — the count of top-level body
statements that reach nesting depth ≥ 2 — and fire when it crosses a
-configurable threshold while CCN is also non-trivial. Threshold pair
-matches CodeScene's documented defaults.
+configurable threshold while CCN is also non-trivial.
"""
from __future__ import annotations
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/code_age_volatility.py b/packages/core/src/repowise/core/analysis/health/biomarkers/code_age_volatility.py
index f77214202..87106b475 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/code_age_volatility.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/code_age_volatility.py
@@ -18,8 +18,7 @@ Tier-aware: when ``ctx.blame_index`` is ``None`` (ESSENTIAL git tier),
or empty, the detector emits zero findings. Function-level no-op is the
documented "no signal" outcome until ``backfill_blame()`` runs.
-Severity (calibrated against the 1-year / 2-year ages used in CodeScene
-case studies):
+Severity (calibrated against the 1-year / 2-year age boundaries):
* MEDIUM ``median_age >= 365d`` and ``recent_mod_count >= 2``.
* HIGH ``median_age >= 730d`` OR ``recent_mod_count >= 5`` (with
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
index 92988bab4..0b81782c7 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/complex_method.py
@@ -1,7 +1,7 @@
"""Complex Method — high cyclomatic complexity.
-Flags functions with CCN ≥ 9. Conservative threshold; CodeScene defaults
-to 9 as the boundary between "ok" and "complex".
+Flags functions with CCN ≥ 9. A conservative threshold for the boundary
+between "ok" and "complex".
"""
from __future__ import annotations
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.py b/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.py
index 3943ebacd..edf4e33f3 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/developer_congestion.py
@@ -1,9 +1,8 @@
"""Developer Congestion — too many hands on a single file.
When a file has a large contributor count over a 90-day window and is
-also a hotspot, coordination cost explodes. CodeScene calls this
-"Developer Congestion" — strongly correlated with regression rates in
-their published industry studies.
+also a hotspot, coordination cost explodes. This pattern is strongly
+correlated with regression rates in published industry studies.
Fires when ALL of:
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/god_class.py b/packages/core/src/repowise/core/analysis/health/biomarkers/god_class.py
index 32db0a4e8..ce140bb93 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/god_class.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/god_class.py
@@ -1,7 +1,7 @@
"""God Class — a class that is large, has many methods, and hides a brain.
-CodeScene's structural module smell: a single class that has accreted too
-many responsibilities. We flag when **all three** hold:
+A structural module smell: a single class that has accreted too many
+responsibilities. We flag when **all three** hold:
- ``total_nloc ≥ 200`` — the class is large
- ``method_count ≥ 15`` — it has many methods
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py b/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py
index 59e0cab17..23b3e1a53 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/nested_complexity.py
@@ -1,8 +1,7 @@
"""Nested Complexity — deeply indented control flow.
-Flags functions whose maximum nesting depth exceeds 4. Inspired by
-CodeScene's "Deep, Nested Complexity" — strongly correlated with
-defect density in their published studies.
+Flags functions whose maximum nesting depth exceeds 4. Deep nesting is
+strongly correlated with defect density in published studies.
"""
from __future__ import annotations
diff --git a/packages/core/src/repowise/core/analysis/health/biomarkers/primitive_obsession.py b/packages/core/src/repowise/core/analysis/health/biomarkers/primitive_obsession.py
index fa91733ad..5dcc28c8c 100644
--- a/packages/core/src/repowise/core/analysis/health/biomarkers/primitive_obsession.py
+++ b/packages/core/src/repowise/core/analysis/health/biomarkers/primitive_obsession.py
@@ -4,8 +4,7 @@ A proxy for the OOP smell: when a function signature carries 5+ raw
parameters, the call sites usually pass strings/ints/bools that *should*
be a value object. We don't try to inspect parameter *types* (too much
language-specific machinery) — the raw count is a strong-enough
-correlation in practice and matches CodeScene's "Primitive Obsession"
-default.
+correlation in practice.
Constructors (`__init__`, `init`) get a small grace allowance — wide
dataclass-style ctors are an idiomatic pattern, not a smell.
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/README.md b/packages/core/src/repowise/core/analysis/health/complexity/README.md
index 6736c8441..913078b43 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/README.md
+++ b/packages/core/src/repowise/core/analysis/health/complexity/README.md
@@ -36,7 +36,7 @@ Tree-sitter AST walker. Single AST pass per file computes:
- **nloc** — non-comment lines of code per function.
- **assertion_blocks** — runs of ≥ 2 consecutive assertion statements,
each `(start_line, end_line, count)`. Opt-in per language via
- `assert_kinds` / `assert_call_kinds`. Feeds the test-quality biomarkers
+ `assert_kinds` / `assert_call_kinds`. Feeds the test-quality markers
(`large_assertion_block`, `duplicated_assertion_block`).
It also emits **class-level** aggregates (`ClassComplexity`) for languages
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py b/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py
index 022cca279..bcf24c1d3 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/cyclomatic.py
@@ -1,7 +1,7 @@
"""The CCN / cognitive / max-nesting engine.
``_walk_function_body`` is the recursive per-function walk: it accumulates
-McCabe cyclomatic complexity, SonarSource cognitive complexity, max nesting
+McCabe cyclomatic complexity, cognitive complexity, max nesting
depth, ``bumps`` (independent heavy branches), and a side-channel of compound
boolean conditions. The helpers above it classify branch / loop / case / catch
nodes and pull condition subtrees out for the boolean-operator tally.
@@ -180,8 +180,7 @@ def _walk_function_body(
``bumps`` counts how many *direct* children of the function body
contain nested control flow that reaches a depth of ≥ 2. A function
- with several heavy independent branches is "bumpy" in
- CodeScene/SonarSource terminology.
+ with several heavy independent branches is "bumpy".
``complex_conditions`` is an additive side-channel — collected for
every branch/loop/case construct encountered. The CCN / cognitive
@@ -269,7 +268,7 @@ def _walk_function_body(
ccn += ccn_increment
new_depth = depth + nesting_increment
if nesting_increment:
- # SonarSource cognitive: each nesting node adds (1 + depth).
+ # Cognitive complexity: each nesting node adds (1 + depth).
cognitive += 1 + depth
elif ccn_increment:
# Flat +1 for boolean operators (no nesting impact).
diff --git a/packages/core/src/repowise/core/analysis/health/complexity/walker.py b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
index cb408fb5e..7a889d6ab 100644
--- a/packages/core/src/repowise/core/analysis/health/complexity/walker.py
+++ b/packages/core/src/repowise/core/analysis/health/complexity/walker.py
@@ -8,7 +8,7 @@ through its body, accumulating:
loop / case / catch / boolean operator.
- **max_nesting** — deepest stack of nesting-contributing nodes within
the function body.
-- **cognitive** — SonarSource-style weighted score: each nesting node
+- **cognitive** — a weighted nesting score: each nesting node
adds ``1 + current_depth`` (so deeper nesting hurts more); boolean
operators add a flat +1; jumps (``return``/``break``/``continue``)
do not contribute (kept simple in v1).
diff --git a/packages/core/src/repowise/core/analysis/health/duplication/README.md b/packages/core/src/repowise/core/analysis/health/duplication/README.md
index f5b2f23a2..fa509f189 100644
--- a/packages/core/src/repowise/core/analysis/health/duplication/README.md
+++ b/packages/core/src/repowise/core/analysis/health/duplication/README.md
@@ -34,7 +34,7 @@ report = detect_clones(parsed_files, git_meta_map)
5. **Co-change correlation** — for each surviving pair we look up
`git_meta_map[file_a]['co_change_partners_json']` (and the reverse
direction). The max count attaches to `ClonePair.co_change_count`
- so the `dry_violation` biomarker can rank *active* duplicates
+ so the `dry_violation` marker can rank *active* duplicates
higher than dormant ones — the Phase-3 hard constraint.
## Inputs
@@ -51,14 +51,14 @@ report = detect_clones(parsed_files, git_meta_map)
- `duplication_pct`: per-file duplicate-line percentage — the union
of clone-pair line ranges over file NLOC, so overlapping pairs
don't double-count the same physical lines.
- - `pairs_by_file`: lookup map used by the `dry_violation` biomarker.
+ - `pairs_by_file`: lookup map used by the `dry_violation` marker.
## Extension points
- **Tunables** — `DEFAULT_WINDOW_TOKENS` (sensitivity) and
`DEFAULT_MIN_LINES` (output filter) are arguments to `detect_clones`.
Future `HealthConfig` knobs can be threaded through here without
- touching biomarker code.
+ touching marker code.
- **Tokenizer** — to support a new language with different identifier
/ literal node types, extend the kind sets in `tokenizer.py`. The
rolling hash is language-agnostic.
diff --git a/packages/core/src/repowise/core/analysis/health/trends.py b/packages/core/src/repowise/core/analysis/health/trends.py
index 8845dae4d..fd5036b3c 100644
--- a/packages/core/src/repowise/core/analysis/health/trends.py
+++ b/packages/core/src/repowise/core/analysis/health/trends.py
@@ -206,8 +206,8 @@ def recent_kpis(history: list[Any], limit: int = 10) -> list[dict[str, Any]]:
#
# The snapshot writer stores a compact ``{path: score}`` map per snapshot
# (``HealthSnapshot.per_file_scores_json``). These helpers turn that rolling
-# window into a single file's score-over-time series — CodeScene's signature
-# view. Like the repo-level helpers above they are intentionally state-free:
+# window into a single file's score-over-time series. Like the repo-level
+# helpers above they are intentionally state-free:
# callers pass the snapshot history (oldest → newest) and get plain data back,
# so the logic stays unit-testable without a DB and is reused verbatim by the
# PR bot's in-comment sparkline.
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health.py b/packages/server/src/repowise/server/mcp_server/tool_health.py
index fd54c3cd0..42fe2be02 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health.py
@@ -1,4 +1,4 @@
-"""MCP tool: get_health — code-health biomarkers and per-file scores."""
+"""MCP tool: get_health — code-health markers and per-file scores."""
from __future__ import annotations
@@ -216,15 +216,15 @@ async def get_health(
repo: str | None = None,
limit: int = 20,
) -> dict:
- """Code-health biomarkers and per-file scores.
+ """Code-health markers and per-file scores.
Dashboard mode (no ``targets``) returns repo-level KPIs + the
lowest-scoring files. Targeted mode returns per-file findings and
metrics for each path in ``targets``.
- Biomarkers in v1: ``brain_method``, ``nested_complexity``,
- ``complex_method``. Phase 2 adds coverage biomarkers; Phase 3 adds
- duplication + organizational biomarkers.
+ Markers in v1: ``brain_method``, ``nested_complexity``,
+ ``complex_method``. Phase 2 adds coverage markers; Phase 3 adds
+ duplication + organizational markers.
Three-signal health: every file metric carries per-dimension scores. ``score``
is the overall, defect-calibrated number surfaced everywhere (== ``defect_score``);
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 572183d32..90d3ae890 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -22,7 +22,7 @@ src/
git/ hotspot-table, ownership-table/treemap, churn viz, …
graph/ graph-flow (Sigma), toolbar, legend, panels (+ sigma/)
graph-primitives/
- health/ file-table, kpi-cards, biomarkers, score tokens
+ health/ file-table, kpi-cards, markers, score tokens
hooks/ use-debounce, …
jobs/ generation-progress, job-log
modules/ module health detail
diff --git a/packages/ui/src/health/ai-prompt-builder.ts b/packages/ui/src/health/ai-prompt-builder.ts
index 0aa51c334..f641534df 100644
--- a/packages/ui/src/health/ai-prompt-builder.ts
+++ b/packages/ui/src/health/ai-prompt-builder.ts
@@ -279,8 +279,8 @@ export function buildAiPrompt({
const completionContract = [
"1. A short plan (3–6 bullets) describing the structural change before any edits.",
"2. The edits themselves, scoped to the file above (plus tests / direct helpers if needed).",
- "3. A diff-style summary of what changed and why each change reduces a specific biomarker.",
- "4. An estimate of the new biomarker state for that file: which findings should disappear, which remain.",
+ "3. A diff-style summary of what changed and why each change reduces a specific marker.",
+ "4. An estimate of the new marker state for that file: which findings should disappear, which remain.",
];
return [
diff --git a/packages/ui/src/health/biomarker-list.tsx b/packages/ui/src/health/biomarker-list.tsx
index e98b4893b..52733757f 100644
--- a/packages/ui/src/health/biomarker-list.tsx
+++ b/packages/ui/src/health/biomarker-list.tsx
@@ -101,7 +101,7 @@ export function BiomarkerList({
if (filtered.length === 0) {
return (
<div className="rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] p-6 text-sm text-[var(--color-text-secondary)]">
- No biomarker findings match the current filters.
+ No marker findings match the current filters.
</div>
);
}
diff --git a/packages/ui/src/health/findings-view.tsx b/packages/ui/src/health/findings-view.tsx
index 4ab32fd16..e536fd0bd 100644
--- a/packages/ui/src/health/findings-view.tsx
+++ b/packages/ui/src/health/findings-view.tsx
@@ -277,11 +277,11 @@ export function FindingsView({ adapter }: { adapter: CodeHealthAdapter }) {
<>
<div className="flex flex-wrap items-center gap-2">
<FilterSelect
- label="Biomarker"
+ label="Marker"
value={biomarker}
onChange={setBiomarker}
options={[
- { value: "all", label: "All biomarkers" },
+ { value: "all", label: "All markers" },
...biomarkerOptions.map((b) => ({ value: b, label: biomarkerLabel(b) })),
]}
/>
@@ -325,7 +325,7 @@ export function FindingsView({ adapter }: { adapter: CodeHealthAdapter }) {
onChange={(v) => setGroupBy(v as GroupBy)}
options={[
{ value: "none", label: "Flat list" },
- { value: "biomarker", label: "By biomarker" },
+ { value: "biomarker", label: "By marker" },
{ value: "module", label: "By module" },
{ value: "effort", label: "By effort" },
]}
@@ -497,7 +497,7 @@ export function FindingsView({ adapter }: { adapter: CodeHealthAdapter }) {
}}
filePath={promptTarget?.file_path ?? null}
title="AI fix prompt"
- description="A ready-to-paste prompt that gives your AI coding agent every biomarker, line range, score deduction, and constraint needed to refactor this file in one focused pass."
+ description="A ready-to-paste prompt that gives your AI coding agent every marker, line range, score deduction, and constraint needed to refactor this file in one focused pass."
getPrompt={
promptTarget
? (flavor) => buildAiPrompt({ target: promptTarget, flavor })
diff --git a/packages/web/src/app/repos/[id]/code-health/page.tsx b/packages/web/src/app/repos/[id]/code-health/page.tsx
index dacdf0795..3aadd5cf4 100644
--- a/packages/web/src/app/repos/[id]/code-health/page.tsx
+++ b/packages/web/src/app/repos/[id]/code-health/page.tsx
@@ -145,7 +145,7 @@ export default function CodeHealthPage() {
<PageShell
title="Code Health"
icon={<HeartPulse className="h-5 w-5 text-[var(--color-success)]" />}
- description="Per-file health scores from complexity, duplication, coverage, churn, and ownership biomarkers — ranked into a fix-next queue."
+ description="Per-file health scores from complexity, duplication, coverage, churn, and ownership markers — ranked into a fix-next queue."
maxWidth="wide"
actions={
<Button size="sm" variant="outline" onClick={() => mutate()}>
diff --git a/plugins/claude-code/README.md b/plugins/claude-code/README.md
index cbb6a3a7b..7941d46c6 100644
--- a/plugins/claude-code/README.md
+++ b/plugins/claude-code/README.md
@@ -40,7 +40,7 @@ MCP tools and skills activate automatically.
Graph (tree-sitter dependency graph, 15 languages) · Git (hotspots, ownership,
co-change, bus factor) · Docs (LLM-generated wiki + semantic search) · Decisions
(architectural rationale mined from eight sources) · Code Health (1–10
-defect-validated score from deterministic biomarkers).
+defect-validated score from deterministic markers).
### Slash commands
@@ -82,7 +82,7 @@ Registered automatically when the plugin is enabled:
| `get_risk` | Per-file hotspot, dependents, co-changes, owners; PR `directive` block with `changed_files` |
| `get_why` | Architectural decisions — search, path-anchored, or health dashboard |
| `get_dead_code` | Unused/unreachable findings tiered by confidence |
-| `get_health` | 1–10 code-health score and biomarker findings per file |
+| `get_health` | 1–10 code-health score and marker findings per file |
## Setup modes
diff --git a/plugins/claude-code/commands/health.md b/plugins/claude-code/commands/health.md
index 2881308b4..9dad0d406 100644
--- a/plugins/claude-code/commands/health.md
+++ b/plugins/claude-code/commands/health.md
@@ -1,11 +1,11 @@
---
-description: Show Repowise code-health — KPIs, lowest-scoring files, refactoring targets, trends, or per-file biomarkers.
+description: Show Repowise code-health — KPIs, lowest-scoring files, refactoring targets, trends, or per-file markers.
allowed-tools: Bash, Read
---
# Repowise Health
-Report the code-health layer: a deterministic 1–10 score per file from biomarkers
+Report the code-health layer: a deterministic 1–10 score per file from markers
(complexity, deep nesting, brain methods, cohesion, duplication, untested
hotspots, and more). No LLM — works even in index-only mode.
@@ -13,7 +13,7 @@ hotspots, and more). No LLM — works even in index-only mode.
1. If `.repowise/` doesn't exist: "This repo isn't indexed yet. Run `/repowise:init` first." Stop.
2. Decide the mode from `$ARGUMENTS` (see below), run the command, and present a
- readable summary — score(s), the top biomarker findings, and what they mean.
+ readable summary — score(s), the top marker findings, and what they mean.
Don't dump the raw table verbatim.
## Modes
@@ -29,7 +29,7 @@ Handle `$ARGUMENTS`:
- "trend" / "trends" → `repowise health --trend` (last snapshots + declining / predicted-decline alerts)
- "module <name>" → `repowise health --module <name>`
- "safe" → `repowise health --safe-only`
-- a coverage file (e.g. `cov.lcov`, `coverage.xml`) → `repowise health --coverage <file>` to light up untested-hotspot / coverage-gap biomarkers (LCOV, Cobertura, Clover)
+- a coverage file (e.g. `cov.lcov`, `coverage.xml`) → `repowise health --coverage <file>` to light up untested-hotspot / coverage-gap markers (LCOV, Cobertura, Clover)
Other flags: `--format json` for machine-readable output, `--repo <alias>` /
`--no-workspace` in workspace mode.
diff --git a/plugins/claude-code/skills/code-health/SKILL.md b/plugins/claude-code/skills/code-health/SKILL.md
index 9a2da367e..15bcaa699 100644
--- a/plugins/claude-code/skills/code-health/SKILL.md
+++ b/plugins/claude-code/skills/code-health/SKILL.md
@@ -10,7 +10,7 @@ user-invocable: false
# Code Health with Repowise
-Repowise scores **every file 1–10** from deterministic biomarkers — McCabe
+Repowise scores **every file 1–10** from deterministic markers — McCabe
complexity, deep nesting, brain methods, class cohesion (LCOM4), god classes,
clone detection, untested hotspots, function-level churn, ownership dispersion,
and more. Zero LLM calls; pure local analysis. The weights are calibrated
@@ -23,7 +23,7 @@ not just *bigger*.
lowest-scoring files. Start here for "how healthy is this codebase?" or "what
should we clean up?".
- **Targeted** — `get_health(targets=["src/x.py", "src/y.py"])`: per-file score
- and the specific biomarker findings driving it. Use before/after a refactor,
+ and the specific marker findings driving it. Use before/after a refactor,
or to explain *why* a file is flagged.
## Useful `include` flags
@@ -39,11 +39,11 @@ not just *bigger*.
1. For "what should I refactor?" → dashboard mode, then
`get_health(targets=[worst files], include=["refactoring"])` and present the
ranked suggestions, not just the scores.
-2. For a specific file → report the score, the top 2–3 biomarker findings, and
+2. For a specific file → report the score, the top 2–3 marker findings, and
what each one means in plain language. Avoid dumping the raw payload.
3. Before editing a flagged file → cross-check `get_risk(targets=[...])`; a file
that is both low-health *and* a churn hotspot deserves the most care.
-4. Untested-hotspot / coverage questions → tell the user coverage biomarkers
+4. Untested-hotspot / coverage questions → tell the user coverage markers
light up once they ingest a report: `repowise health --coverage cov.lcov`
(LCOV / Cobertura / Clover).
diff --git a/plugins/claude-code/skills/pre-modification/SKILL.md b/plugins/claude-code/skills/pre-modification/SKILL.md
index 5526efb3f..425fcce99 100644
--- a/plugins/claude-code/skills/pre-modification/SKILL.md
+++ b/plugins/claude-code/skills/pre-modification/SKILL.md
@@ -41,7 +41,7 @@ If `get_risk` shows:
Call `get_context(targets=["file.py"])` first to understand the full context: what uses this file, what decisions govern it, and why it's structured this way. This prevents accidentally violating architectural decisions.
For a heavy refactor, also call `get_health(targets=["file.py"])` — the
-biomarker findings (complexity, deep nesting, low cohesion, duplication) tell
+marker findings (complexity, deep nesting, low cohesion, duplication) tell
you *what* to improve while you're in there, and give you a before/after score.
## Error handling