diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
new file mode 100644
index 0000000..e5f5a5c
--- /dev/null
+++ b/docs/BENCHMARKS.md
@@ -0,0 +1,60 @@
+# NirmiqCodeSensei — Analysis Benchmarks (MS4)
+
+The analysis pipeline is CPU-bound and local (no network, no server fan-out), so
+the honest analog of "load handling" for this tool is **compute scaling**: how
+the analysis time grows with project size, and how much the MS4 incremental path
+saves when nothing changed.
+
+## Method
+
+A synthetic project generator (`scripts/_benchmark.mts`, a scratch harness — not
+committed) writes N interlinked TS/TSX files across realistic layers
+(`components`, `lib/services`, `lib/utils`, `app/*`, `hooks`). Each file imports
+the previous one (so the import graph and cycle detection are exercised) and
+contains branchy functions (so cyclomatic-complexity metrics are non-trivial).
+Every timed function is pure/local and touches no database:
+
+- **analyzeCode** — directory walk + AST parse (`@typescript-eslint/typescript-estree`) + DSA findings + import graph.
+- **computeSeniorReview** — all eight lenses over the already-collected corpus (no re-walk, no re-parse).
+- **computeSourceFingerprint** — the MS4 incremental-skip check (`sha256` of `path|size|mtime`, stat-only).
+
+The AST parser and lens pass are warmed once per size so JIT compilation doesn't
+skew the first measurement. Times are milliseconds.
+
+## Results (dev machine, Windows 11)
+
+| Files | analyzeCode | seniorReview | fingerprint | scanned |
+|------:|------------:|-------------:|------------:|--------:|
+| 50    | ~97 ms      | ~3 ms        | ~6 ms       | 50      |
+| 150   | ~130 ms     | ~4 ms        | ~13 ms      | 150     |
+| 300   | ~180 ms     | ~4 ms        | ~23 ms      | 300     |
+
+A full analysis of a 300-file project completes in **under ~200 ms** end to end
+(analyzeCode + seniorReview), comfortably interactive.
+
+## Interpretation
+
+- **The lens pass is effectively free.** `computeSeniorReview` stays flat at
+  ~3–4 ms regardless of project size, because it consumes the corpus that
+  `analyzeCode` already collected — it never re-walks the tree or re-parses ASTs.
+- **`analyzeCode` dominates and stays bounded.** It grows sub-linearly (~97 ms →
+  ~180 ms from 50 → 300 files) because AST parsing is capped at
+  `MAX_AST_FILES = 100`; beyond that only the cheaper regex/graph work grows.
+  Hard caps keep the worst case bounded on any repo:
+  - `MAX_FILES = 300` — files scanned per analysis.
+  - `MAX_AST_FILES = 100` — files given a full AST pass.
+  - `MAX_FILE_BYTES = 80 KB` — per-file size ceiling.
+  A project larger than these is analyzed on its most important files and marked
+  `truncated` (surfaced honestly in the learning-map summary), never hung.
+- **Incremental re-analysis pays off (MS4).** On an unchanged tree,
+  `reanalyzeProject` computes only the fingerprint (~23 ms at 300 files,
+  stat-only — no AST parse, no lens pass, no DB writes) and short-circuits. That
+  is roughly **8× cheaper** than a full re-analysis (~180 ms + persistence) and
+  avoids all database churn.
+
+## Reproducing
+
+Recreate `scripts/_benchmark.mts` from this methodology (synthetic N-file project
+→ time `analyzeCode`, `computeSeniorReview`, `computeSourceFingerprint`), run
+`npx tsx scripts/_benchmark.mts`, then delete it. Numbers vary with hardware; the
+shape (flat lens pass, bounded walk, cheap fingerprint) is what matters.
diff --git a/docs/MEGASPRINT_ROADMAP.md b/docs/MEGASPRINT_ROADMAP.md
index a2d4ad0..0a93657 100644
--- a/docs/MEGASPRINT_ROADMAP.md
+++ b/docs/MEGASPRINT_ROADMAP.md
@@ -19,7 +19,7 @@ free + BYOK path (`ANTHROPIC_API_KEY` optional; offline analyzer is the default)
 | **MS1** ✅ | Identity | Final distribution-ready name everywhere, incl. DB file / env / MCP internals, done once and safely | **DONE** — deep rename shipped; repo → `SheeshDarth/NirmiqCodeSensei`; DB boot-migration + `NCS_*` env fallback + `ncs_*` tools; gate green (16/16) |
 | **MS2** ✅ | Security | The app ingests users' private source code — it must be provably safe | **DONE** — symlink-confined walk, shell-free git, realpath+credential-dir blocks, prod CSP no `unsafe-eval`, `npm audit` critical-gate; self-scan security lens **A/100** |
 | **MS3** ✅ | Architecture & Data Integrity | Kill load-bearing hacks (description-as-path, no backup) | **DONE** — `sourcePath` column (migration 0008) retires the "Imported from:" hack; DB durability (`synchronous=NORMAL`, `busy_timeout`, boot integrity check, WAL checkpoint on exit) + downloadable backup; workspace error/loading boundaries; graph reconciliation already handled (`graphJson ?? buildKnowledgeGraph`). **#27/#28 module FKs deferred to MS4** (no analyzer-produced associations to populate them — REVIEW-012). Gate green (19/19) |
-| **MS4** | Algorithms & Analysis Depth | The analysis *is* the product — make it rigorous and calibrated | Defensible self-scan grade; incremental re-analysis; documented large-repo benchmarks |
+| **MS4** 🔄 | Algorithms & Analysis Depth | The analysis *is* the product — make it rigorous and calibrated | **In progress** — ✅ codeHealth scoring calibrated to code *density* not project size (self-scan F→**B(76)**, overall **A(95)**); size-relative `computeCodeHealthScore` + relativity test. ✅ incremental re-analysis — `computeSourceFingerprint` (path\|size\|mtime sha256) + `learning_maps.source_fingerprint` (0009); reanalyze short-circuits `{unchanged:true}` on an untouched tree. ✅ [benchmarks](BENCHMARKS.md) — 300-file full analysis <200ms, flat ~4ms lens pass, incremental skip ~8× cheaper; bounded by MAX_FILES/AST caps. Remaining: fold in #27/#28 module associations (REVIEW-012) |
 | **MS5** | Quality & Reliability (QA) | 16 tests is a foundation, not production confidence | Critical path e2e-covered; CI green on Win/mac/Linux from a clean clone |
 | **MS6** | Framework & Performance | Production Next.js build quality | Standalone build runs; perf/a11y budgets met; no UI-blocking analysis |
 | **MS7** | Distribution & Release | Turn the repo into installable, versioned software — the actual "deploy" | `npx nirmiqcodesensei@latest` runs on a fresh machine; tagged v1.0.0 GitHub Release; CHANGELOG current; scaling-N/A ADR recorded |
diff --git a/lib/db/migrations/0009_mushy_sebastian_shaw.sql b/lib/db/migrations/0009_mushy_sebastian_shaw.sql
new file mode 100644
index 0000000..4db1a6f
--- /dev/null
+++ b/lib/db/migrations/0009_mushy_sebastian_shaw.sql
@@ -0,0 +1 @@
+ALTER TABLE `learning_maps` ADD `source_fingerprint` text;
\ No newline at end of file
diff --git a/lib/db/migrations/meta/0009_snapshot.json b/lib/db/migrations/meta/0009_snapshot.json
new file mode 100644
index 0000000..59c4879
--- /dev/null
+++ b/lib/db/migrations/meta/0009_snapshot.json
@@ -0,0 +1,801 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "6cd52e48-fc14-48e6-8be7-c91c7d989cf1",
+  "prevId": "a6406c08-668f-4cab-b772-b982d8ab36e6",
+  "tables": {
+    "concept_links": {
+      "name": "concept_links",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "project_feature": {
+          "name": "project_feature",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "concept_name": {
+          "name": "concept_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "concept_type": {
+          "name": "concept_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "explanation": {
+          "name": "explanation",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "practice_task": {
+          "name": "practice_task",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "source_file": {
+          "name": "source_file",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "code_snippet": {
+          "name": "code_snippet",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "ast_confidence": {
+          "name": "ast_confidence",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "concept_links_workspace_id_workspaces_id_fk": {
+          "name": "concept_links_workspace_id_workspaces_id_fk",
+          "tableFrom": "concept_links",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daily_logs": {
+      "name": "daily_logs",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "date": {
+          "name": "date",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "built_today": {
+          "name": "built_today",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "understood_today": {
+          "name": "understood_today",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "unclear_topics": {
+          "name": "unclear_topics",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "bugs_faced": {
+          "name": "bugs_faced",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "next_action": {
+          "name": "next_action",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "daily_logs_workspace_date": {
+          "name": "daily_logs_workspace_date",
+          "columns": [
+            "workspace_id",
+            "date"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "daily_logs_workspace_id_workspaces_id_fk": {
+          "name": "daily_logs_workspace_id_workspaces_id_fk",
+          "tableFrom": "daily_logs",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "debug_logs": {
+      "name": "debug_logs",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "suspected_cause": {
+          "name": "suspected_cause",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "actual_cause": {
+          "name": "actual_cause",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "fix_summary": {
+          "name": "fix_summary",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "lesson_learned": {
+          "name": "lesson_learned",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "prevention_rule": {
+          "name": "prevention_rule",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "debug_logs_workspace_id_workspaces_id_fk": {
+          "name": "debug_logs_workspace_id_workspaces_id_fk",
+          "tableFrom": "debug_logs",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "explain_back_questions": {
+      "name": "explain_back_questions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "learning_map_id": {
+          "name": "learning_map_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "question": {
+          "name": "question",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "difficulty": {
+          "name": "difficulty",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'beginner'"
+        },
+        "expected_points_json": {
+          "name": "expected_points_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'[]'"
+        },
+        "user_answer": {
+          "name": "user_answer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "score": {
+          "name": "score",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "confidence": {
+          "name": "confidence",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "explain_back_questions_workspace_id_workspaces_id_fk": {
+          "name": "explain_back_questions_workspace_id_workspaces_id_fk",
+          "tableFrom": "explain_back_questions",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "explain_back_questions_learning_map_id_learning_maps_id_fk": {
+          "name": "explain_back_questions_learning_map_id_learning_maps_id_fk",
+          "tableFrom": "explain_back_questions",
+          "tableTo": "learning_maps",
+          "columnsFrom": [
+            "learning_map_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "learning_maps": {
+      "name": "learning_maps",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "summary": {
+          "name": "summary",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "modules_json": {
+          "name": "modules_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'[]'"
+        },
+        "checkpoints_json": {
+          "name": "checkpoints_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'[]'"
+        },
+        "analysis_raw": {
+          "name": "analysis_raw",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "graph_json": {
+          "name": "graph_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "senior_review_json": {
+          "name": "senior_review_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "source_fingerprint": {
+          "name": "source_fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "learning_maps_workspace_id_workspaces_id_fk": {
+          "name": "learning_maps_workspace_id_workspaces_id_fk",
+          "tableFrom": "learning_maps",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "search_chunks": {
+      "name": "search_chunks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "file_path": {
+          "name": "file_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "chunk_type": {
+          "name": "chunk_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'file'"
+        },
+        "chunk_text": {
+          "name": "chunk_text",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "layer": {
+          "name": "layer",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "search_chunks_workspace_id_workspaces_id_fk": {
+          "name": "search_chunks_workspace_id_workspaces_id_fk",
+          "tableFrom": "search_chunks",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "session_logs": {
+      "name": "session_logs",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "tool_name": {
+          "name": "tool_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "action_summary": {
+          "name": "action_summary",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "explanation": {
+          "name": "explanation",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "risk_level": {
+          "name": "risk_level",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'safe'"
+        },
+        "outcome": {
+          "name": "outcome",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "source": {
+          "name": "source",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'hook'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "session_logs_workspace_id_workspaces_id_fk": {
+          "name": "session_logs_workspace_id_workspaces_id_fk",
+          "tableFrom": "session_logs",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "workspaces": {
+      "name": "workspaces",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "goal": {
+          "name": "goal",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "source_path": {
+          "name": "source_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'active'"
+        },
+        "progress_score": {
+          "name": "progress_score",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/lib/db/migrations/meta/_journal.json b/lib/db/migrations/meta/_journal.json
index ed8b235..77ddeab 100644
--- a/lib/db/migrations/meta/_journal.json
+++ b/lib/db/migrations/meta/_journal.json
@@ -64,6 +64,13 @@
       "when": 1783913305000,
       "tag": "0008_productive_warhawk",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1783969111777,
+      "tag": "0009_mushy_sebastian_shaw",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/lib/db/schema.ts b/lib/db/schema.ts
index 91d71e3..5aba5f9 100644
--- a/lib/db/schema.ts
+++ b/lib/db/schema.ts
@@ -45,6 +45,10 @@ export const learningMaps = sqliteTable("learning_maps", {
   graphJson: text("graph_json"),
   // Senior Review — multi-lens local static analysis (SeniorReview JSON)
   seniorReviewJson: text("senior_review_json"),
+  // Source-tree fingerprint (sha256 of path|size|mtime over scanned files) from
+  // the analysis run that produced this map. Lets reanalyze skip work when the
+  // source is unchanged (MS4 incremental re-analysis). Null for manual maps.
+  sourceFingerprint: text("source_fingerprint"),
   createdAt: integer("created_at")
     .notNull()
     .$defaultFn(() => Date.now()),
diff --git a/lib/services/code-analyzer.service.ts b/lib/services/code-analyzer.service.ts
index 964c6af..abbd1bd 100644
--- a/lib/services/code-analyzer.service.ts
+++ b/lib/services/code-analyzer.service.ts
@@ -14,6 +14,7 @@
  */
 
 import { readdirSync, readFileSync, statSync } from "fs";
+import { createHash } from "crypto";
 import path from "path";
 import { parse } from "@typescript-eslint/typescript-estree";
 import type { TSESTree } from "@typescript-eslint/typescript-estree";
@@ -128,6 +129,61 @@ function walk(
   }
 }
 
+/**
+ * Fast, content-independent fingerprint of a project's source tree, used to
+ * skip re-analysis when nothing changed (MS4 incremental re-analysis). Mirrors
+ * the analyzeCode() walk (same ignore dirs, extensions, symlink skip, size cap)
+ * but only *stats* files — no reads, no AST parsing — so it is far cheaper than
+ * a full analysis. Two trees with identical relative paths + sizes + mtimes
+ * hash to the same value; any add/remove/edit (which changes size or mtime)
+ * changes it. Returns a hex sha256, or null if the root can't be read.
+ *
+ * Trade-off: this is an mtime+size heuristic, not a content hash — an edit that
+ * preserves both (rare) would be missed. That is the standard build-cache
+ * tradeoff, chosen so the check stays cheap enough to run on every refresh.
+ */
+export function computeSourceFingerprint(root: string): string | null {
+  const parts: string[] = [];
+  const visit = (dir: string): void => {
+    if (parts.length >= MAX_FILES) return;
+    const entries = (() => {
+      try {
+        return readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return null;
+      }
+    })();
+    if (!entries) return;
+    for (const e of entries) {
+      if (parts.length >= MAX_FILES) return;
+      if (e.name.startsWith(".") && e.name !== ".") continue;
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name)) continue;
+        visit(path.join(dir, e.name));
+      } else if (CODE_EXT.test(e.name)) {
+        const full = path.join(dir, e.name);
+        try {
+          const st = statSync(full);
+          if (st.size <= MAX_FILE_BYTES) {
+            const rel = path.relative(root, full).split(path.sep).join("/");
+            parts.push(`${rel}|${st.size}|${Math.round(st.mtimeMs)}`);
+          }
+        } catch {
+          /* skip unreadable entries */
+        }
+      }
+    }
+  };
+  try {
+    visit(root);
+  } catch {
+    return null;
+  }
+  parts.sort();
+  return createHash("sha256").update(parts.join("\n")).digest("hex");
+}
+
 // ── Layer classification ─────────────────────────────────────────────────────
 const LAYER_COLOR: Record<string, string> = {
   "Routes & Pages": "#22d3ee",
diff --git a/lib/services/learning-map.service.ts b/lib/services/learning-map.service.ts
index 923913a..48daf44 100644
--- a/lib/services/learning-map.service.ts
+++ b/lib/services/learning-map.service.ts
@@ -96,6 +96,7 @@ export async function createLearningMapWithContent(
     analysisRaw?: string;
     graphJson?: string;
     seniorReviewJson?: string;
+    sourceFingerprint?: string;
     modules: Array<{
       title: string;
       summary: string;
@@ -136,6 +137,7 @@ export async function createLearningMapWithContent(
         analysisRaw: content.analysisRaw ?? null,
         graphJson: content.graphJson ?? null,
         seniorReviewJson: content.seniorReviewJson ?? null,
+        sourceFingerprint: content.sourceFingerprint ?? null,
         modulesJson,
         checkpointsJson,
       })
diff --git a/lib/services/project-analyzer.service.ts b/lib/services/project-analyzer.service.ts
index d0e7fad..44686ff 100644
--- a/lib/services/project-analyzer.service.ts
+++ b/lib/services/project-analyzer.service.ts
@@ -26,9 +26,12 @@ import {
   createConceptLink,
   createConceptLinkWithSource,
 } from "@/lib/services/concept-link.service";
-import { createLearningMapWithContent } from "@/lib/services/learning-map.service";
+import {
+  createLearningMapWithContent,
+  getLearningMapByWorkspaceId,
+} from "@/lib/services/learning-map.service";
 import { detectStack, generateLocalAnalysisText } from "@/lib/services/local-analyzer.service";
-import { analyzeCode } from "@/lib/services/code-analyzer.service";
+import { analyzeCode, computeSourceFingerprint } from "@/lib/services/code-analyzer.service";
 import {
   computeSeniorReview,
   enrichReviewWithAI,
@@ -111,6 +114,8 @@ export interface AnalysisResult {
   analysis: string;
   questionsCreated: number;
   conceptsCreated: number;
+  /** True when reanalyze short-circuited because the source was unchanged (MS4). */
+  unchanged?: boolean;
 }
 
 // Structured-output schema for AI analysis. Passed to messages.parse() via
@@ -496,6 +501,31 @@ export async function reanalyzeProject(
 
   const projectName = ws.data.title;
 
+  // MS4 incremental re-analysis — if the source tree is unchanged since the last
+  // run (same fingerprint), skip the whole expensive pass and keep the existing
+  // artifacts. Near-instant on an unchanged repo; a genuine edit (which changes
+  // a file's size or mtime) flips the fingerprint and forces a full refresh.
+  const currentFingerprint = computeSourceFingerprint(resolvedPath);
+  const existingMap = await getLearningMapByWorkspaceId(workspaceId);
+  if (
+    existingMap.ok &&
+    existingMap.data?.sourceFingerprint &&
+    currentFingerprint &&
+    existingMap.data.sourceFingerprint === currentFingerprint
+  ) {
+    return {
+      ok: true,
+      data: {
+        workspaceId,
+        workspaceName: projectName,
+        analysis: existingMap.data.analysisRaw ?? "",
+        questionsCreated: 0,
+        conceptsCreated: 0,
+        unchanged: true,
+      },
+    };
+  }
+
   // Compute fresh analysis BEFORE deleting anything, so a failed re-analysis
   // never wipes the existing content.
   const computed = await computeAnalysis(resolvedPath, projectName, anthropicApiKey);
@@ -796,11 +826,15 @@ async function persistAnalysis(
   const summary = analysisTruncated
     ? `${mapContent.summary ? mapContent.summary + "\n\n" : ""}⚠️ Large project — code analysis covered ${scannedFileCount} source files (ranked by importance); some files were not scanned.`
     : mapContent.summary;
+  // Fingerprint the source tree so a later reanalyze can skip work when nothing
+  // changed (MS4 incremental re-analysis).
+  const sourceFingerprint = computeSourceFingerprint(resolvedPath) ?? undefined;
   await createLearningMapWithContent(workspaceId, {
     ...mapContent,
     summary,
     graphJson,
     seniorReviewJson,
+    sourceFingerprint,
   });
 
   return { questionsCreated, conceptsCreated };
diff --git a/lib/services/senior-review.service.ts b/lib/services/senior-review.service.ts
index 3854802..59a12e0 100644
--- a/lib/services/senior-review.service.ts
+++ b/lib/services/senior-review.service.ts
@@ -193,13 +193,45 @@ const SEVERITY_PENALTY: Record<LensSeverity, number> = {
   info: 0,
 };
 
+function gradeForScore(score: number): LensScore["grade"] {
+  return score >= 90 ? "A" : score >= 75 ? "B" : score >= 60 ? "C" : score >= 40 ? "D" : "F";
+}
+
 function scoreLens(findings: LensFinding[], summary: string): LensScore {
   let score = 100;
   for (const f of findings) score -= SEVERITY_PENALTY[f.severity];
   score = Math.max(0, Math.round(score));
-  const grade =
-    score >= 90 ? "A" : score >= 75 ? "B" : score >= 60 ? "C" : score >= 40 ? "D" : "F";
-  return { score, grade, summary };
+  return { score, grade: gradeForScore(score), summary };
+}
+
+/**
+ * Calibrated, size-relative code-health score (MS4).
+ *
+ * The default per-finding penalty model punishes large codebases for merely
+ * having more code: eight complex functions score identically whether the
+ * project has 50 functions (genuinely unhealthy) or 5,000 (fine). Grade instead
+ * on the SHARE of the codebase that is unhealthy — a very-complex function
+ * (cyclomatic > 20) weighs double a merely-complex one (> 10) — so the score
+ * reflects code health, not project size. A healthy codebase keeps well under
+ * ~5% of its functions above complexity 10.
+ */
+export function computeCodeHealthScore(m: {
+  totalFunctions: number;
+  highComplexCount: number; // complexity > 20
+  medComplexCount: number; // 10 < complexity <= 20
+  oversizeFileCount: number; // loc > 500
+  totalFiles: number;
+}): { score: number; grade: LensScore["grade"] } {
+  const weightedComplexShare =
+    m.totalFunctions > 0
+      ? (m.highComplexCount * 2 + m.medComplexCount) / m.totalFunctions
+      : 0;
+  const oversizeShare =
+    m.totalFiles > 0 ? m.oversizeFileCount / m.totalFiles : 0;
+  const complexPenalty = Math.min(45, Math.round(weightedComplexShare * 120));
+  const sizePenalty = Math.min(20, Math.round(oversizeShare * 60));
+  const score = Math.max(0, 100 - complexPenalty - sizePenalty);
+  return { score, grade: gradeForScore(score) };
 }
 
 function cap(findings: LensFinding[]): LensFinding[] {
@@ -691,9 +723,31 @@ function runCodeHealthLens(input: SeniorReviewInput): CodeHealthLens {
   }
 
   const capped = cap(findings);
-  const summary = `${totalLoc.toLocaleString()} LOC across ${input.corpus.length} files (avg ${avgLoc}).`;
+
+  // Size-relative scoring: grade on the share of the codebase that is unhealthy,
+  // not the raw count of findings (which just grows with project size).
+  const highComplexCount = allFns.filter((fn) => fn.complexity > 20).length;
+  const medComplexCount = allFns.filter(
+    (fn) => fn.complexity > 10 && fn.complexity <= 20
+  ).length;
+  const oversizeFileCount = input.corpus.filter((f) => f.loc > 500).length;
+  const { score, grade } = computeCodeHealthScore({
+    totalFunctions: allFns.length,
+    highComplexCount,
+    medComplexCount,
+    oversizeFileCount,
+    totalFiles: input.corpus.length,
+  });
+
+  const complexCount = highComplexCount + medComplexCount;
+  const pctComplex =
+    allFns.length > 0 ? Math.round((complexCount / allFns.length) * 100) : 0;
+  const summary =
+    `${totalLoc.toLocaleString()} LOC across ${input.corpus.length} files (avg ${avgLoc}). ` +
+    `${complexCount}/${allFns.length} functions above complexity 10 (${pctComplex}%).`;
+
   return {
-    score: scoreLens(capped, summary),
+    score: { score, grade, summary },
     findings: capped,
     totalLoc,
     avgLoc,
diff --git a/tests/import-pipeline.test.mts b/tests/import-pipeline.test.mts
index 444a288..0bc3db0 100644
--- a/tests/import-pipeline.test.mts
+++ b/tests/import-pipeline.test.mts
@@ -14,7 +14,7 @@
  */
 import { test, before, after } from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "fs";
+import { mkdirSync, mkdtempSync, writeFileSync, appendFileSync, rmSync } from "fs";
 import path from "path";
 import os from "os";
 
@@ -30,7 +30,7 @@ const { eq } = await import("drizzle-orm");
 const { resolveProjectPath, analyzeProject, reanalyzeProject, IMPORTED_PROJECTS_DIR } =
   await import("@/lib/services/project-analyzer.service");
 const { analyzeCode } = await import("@/lib/services/code-analyzer.service");
-const { computeSeniorReview } = await import("@/lib/services/senior-review.service");
+const { computeSeniorReview, computeCodeHealthScore } = await import("@/lib/services/senior-review.service");
 const { detectStack } = await import("@/lib/services/local-analyzer.service");
 const { deleteWorkspace } = await import("@/lib/services/workspace.service");
 const { createDebugLog } = await import("@/lib/services/debug-log.service");
@@ -232,6 +232,52 @@ test("security lens: tightened detectors ignore prose, catch real usage", () =>
 let workspaceId: string;
 let seniorGeneratedAt = 0;
 
+test("codeHealth scoring is size-relative, not count-based (MS4 calibration)", () => {
+  // Healthy large project: 6 complex functions out of 400 (1.5%) → strong grade.
+  const large = computeCodeHealthScore({
+    totalFunctions: 400,
+    highComplexCount: 1,
+    medComplexCount: 5,
+    oversizeFileCount: 2,
+    totalFiles: 120,
+  });
+  assert.equal(large.grade, "A", `large healthy repo should be A, got ${large.grade} (${large.score})`);
+
+  // SAME absolute complex-function count in a tiny project (6 of 15 = 40%) must
+  // grade much worse — this is the calibration: density, not raw count.
+  const small = computeCodeHealthScore({
+    totalFunctions: 15,
+    highComplexCount: 1,
+    medComplexCount: 5,
+    oversizeFileCount: 0,
+    totalFiles: 5,
+  });
+  assert.ok(
+    small.score < large.score - 20,
+    `same complex count but denser must score much lower (large ${large.score}, small ${small.score})`
+  );
+
+  // Genuinely unhealthy: many high-complexity functions + oversized files → F.
+  const unhealthy = computeCodeHealthScore({
+    totalFunctions: 30,
+    highComplexCount: 8,
+    medComplexCount: 10,
+    oversizeFileCount: 3,
+    totalFiles: 6,
+  });
+  assert.equal(unhealthy.grade, "F", `dense high-complexity repo should be F, got ${unhealthy.grade} (${unhealthy.score})`);
+
+  // Empty project must not divide by zero.
+  const empty = computeCodeHealthScore({
+    totalFunctions: 0,
+    highComplexCount: 0,
+    medComplexCount: 0,
+    oversizeFileCount: 0,
+    totalFiles: 0,
+  });
+  assert.equal(empty.score, 100);
+});
+
 test("analyzeProject: local-heuristic import populates the workspace", async () => {
   const res = await analyzeProject({ projectPath: projectDir });
   assert.ok(res.ok, res.ok ? "" : res.error);
@@ -327,9 +373,17 @@ test("reanalyzeProject: replaces analysis artifacts, keeps user data", async ()
   const seeded = await createDebugLog(workspaceId, { title: "KEEP: my bug note" });
   assert.ok(seeded.ok);
 
+  // MS4 incremental: reanalyze short-circuits on an unchanged tree, so change a
+  // source file to represent the real "code changed → refresh" scenario.
+  appendFileSync(
+    path.join(projectDir, "src", "index.ts"),
+    "\nexport const _touch = 1;\n"
+  );
+
   const res = await reanalyzeProject(workspaceId);
   assert.ok(res.ok, res.ok ? "" : res.error);
   if (!res.ok) return;
+  assert.ok(!res.data.unchanged, "changed tree triggers a full re-analysis");
   assert.ok(res.data.questionsCreated > 0, "fresh questions persisted");
 
   const bugs = await db.select().from(schema.debugLogs)
@@ -352,6 +406,24 @@ test("reanalyzeProject: regenerates the senior review", async () => {
   );
 });
 
+test("reanalyzeProject: unchanged source short-circuits (MS4 incremental)", async () => {
+  // The prior test re-analysed and stored a fresh fingerprint; the tree hasn't
+  // changed since, so a second reanalyze must skip the work and report unchanged.
+  const before = await db.select().from(schema.explainBackQuestions)
+    .where(eq(schema.explainBackQuestions.workspaceId, workspaceId));
+
+  const res = await reanalyzeProject(workspaceId);
+  assert.ok(res.ok, res.ok ? "" : res.error);
+  if (!res.ok) return;
+  assert.equal(res.data.unchanged, true, "unchanged tree skips re-analysis");
+  assert.equal(res.data.questionsCreated, 0, "no new artifacts created");
+
+  // Existing artifacts are left intact (not cleared+regenerated).
+  const after = await db.select().from(schema.explainBackQuestions)
+    .where(eq(schema.explainBackQuestions.workspaceId, workspaceId));
+  assert.equal(after.length, before.length, "questions untouched on short-circuit");
+});
+
 test("reanalyzeProject: legacy workspaces (null sourcePath) fall back to the description marker", async () => {
   // Simulate a pre-0008 import: the path lives only in the description marker,
   // sourcePath is NULL. reanalyze must still recover the path and refresh.