blot-git 0.6.0__tar.gz → 0.7.0__tar.gz

{blot_git-0.6.0 → blot_git-0.7.0}/.pre-commit-hooks.yaml

@@ -1,6 +1,6 @@
 # Lets users of the pre-commit framework add blot with:
 #   - repo: https://github.com/Sym-jay/Blot
-#     rev: v0.6.0
+#     rev: v0.7.0
 #     hooks: [{id: blot}]
 # The first commit indexes the repo's history; later commits refresh the index incrementally.
 - id: blot

{blot_git-0.6.0 → blot_git-0.7.0}/CLAUDE.md

@@ -7,12 +7,14 @@ always changes with another (`forgot-related-file`). Mascot: Sora the slime. Own
 
 ## Layout
 - `src/blot/`: stdlib-only on Python 3.11+ (3.10 also needs `tomli`; keep it that way)
-  - `cli.py` commands: index, check, why, install-hook, guard, install-agent-hook, bench. `check`/`why` build/refresh the index themselves.
+  - `cli.py` commands: index, check, why, map, mcp, install-hook, guard, install-agent-hook, install-mcp, bench.
+    `check`/`why`/`map`/`mcp` build/refresh the index themselves (`index.open_index`).
   - `index.py` builds `.git/blot.db` (parallel `git log` slices for 2000+ commits); `store.py` SQLite schema v2
   - `classify.py` fix severity 0/1/2 + refactor detection: most precision lives here
   - `checks/` one file per check; `trace.py` blame that follows lines past refactor commits
+  - `fixmap.py` (`blot map`), `mcp.py` (stdio MCP server, both protocol eras; `install-mcp` in `hooks.py`)
   - `guard.py` (Claude Code hook; installer in `hooks.py`), `why.py`, `github.py` (`index --github` via `gh api graphql`), `bench.py` (cases + `--replay N`)
-- `bench/cases.json` scripted real-world cases (32/32); `bench/labels/` hand verdicts for every replay
+- `bench/cases.json` scripted real-world cases (33/33); `bench/labels/` hand verdicts for every replay
   warning on the 5 reference repos; `bench/RESULTS.md` replay numbers and precision
 - `action.yml` GitHub Action; `.github/workflows/blot.yml` runs it on Blot's own PRs
 - `assets/sora/build_sprites.py` and `assets/demo/make_demo.py` regenerate the mascot and demo GIF
@@ -22,7 +24,7 @@ always changes with another (`forgot-related-file`). Mascot: Sora the slime. Own
 ```bash
 python -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"
 .venv/Scripts/python -m pytest -q
-.venv/Scripts/blot bench --workdir <short path>     # must stay 32/32
+.venv/Scripts/blot bench --workdir <short path>     # must stay 33/33
 ```
 - Any change to `classify.py` or a check: on each of the 5 clones, checked out at the `head` in its
   labels file, run `blot bench --replay 500 --labels bench/labels/<repo>.json --update-labels`. Keep a
@@ -50,19 +52,24 @@ python -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"
 - Writing code through bash heredocs mangles `\b`, `\n`, `\s`: use the Edit tool for regexes/strings.
 - `gh api` paths: no leading slash (Git Bash rewrites it).
 
-## State (2026-11-06)
-- Released 0.6.0: checks, `why`, `--github`, agent guard (`blot guard` / `install-agent-hook`, tested
-  live in Claude Code 2026-11-06), bench/replay with labels, parallel indexing, pre-commit framework
-  support (`rev: v0.6.0`), GitHub Action (`uses: Sym-jay/Blot@v0.6.0`).
-- Launch: dev.to post published 2026-10-24; the CVE sentence there should mention the withdrawn advisory.
-- Open issues: #2–#4, #6 (bench cases); #33 (live guard report), #34 (quiet readded-bug case), #35–#36 (noise).
-- Precision (0.5.0, measured 2026-10-30): 57/109 useful (52%); Django 1.19 / 10 commits, others ≤ 0.6.
+## State (2026-11-14)
+- Released 0.7.0: checks, `why`, `map`, `--github`, agent guard (`blot guard` / `install-agent-hook`),
+  MCP server (`blot mcp` / `install-mcp`, tools `explain_lines` and `load_bearing_lines`), bench/replay
+  with labels, parallel indexing, pre-commit framework (`rev: v0.7.0`), GitHub Action (`@v0.7.0`).
+- Live-tested in Claude Code: the guard (2026-11-06: the agent cited fix 8efea0c it was undoing) and MCP
+  (2026-11-14: an agent called `load_bearing_lines` on its own and answered correctly).
+  Throwaway test folder: `Documentslask-guard-test` (guard hook + `.mcp.json`).
+- `blot map` takes ~1.5 s on Flask app.py. `trace_lines(whole_file=True)` drops `-C` from the first blame so
+  map and why agree; checks still use the old path.
+- Precision (2026-11-11, after #40): 59/108 useful (54.6%); Django 1.17 / 10 commits, others ≤ 0.6.
   `forgot-related-file` has 0 useful warnings in 45 labelled; candidate to become opt-in.
-- `--github` measured (2026-11-01): precision unchanged (52.5%), +7 useful warnings, almost no demotions.
+- `--github` measured (2026-11-01): precision unchanged, +7 useful warnings, almost no demotions.
 - Tried and dropped (2026-11-01): "fix word + PR number" as an offline fix rule: +85 warnings at 22%
   useful. Don't retry it without a narrower signal (see bench/RESULTS.md).
-- Agent guard (2026-11-04, branch `agent-guard`, unreleased): `blot guard` is a Claude Code PreToolUse
-  hook (`src/blot/guard.py`) running removed-fix + readded-bug on a proposed Edit/Write/MultiEdit;
-  `blot install-agent-hook` edits `.claude/settings.json`. Flask edit of `self_ref` warns in ~450 ms.
-  Not yet tried in a live Claude Code session.
-- Next: remaining noise (renames, API swaps, added arguments, docstrings) in bench/RESULTS.md.
+- Known recall limit: tracing only passes commits classified as refactors, so a big non-refactor rewrite
+  hides older fixes (e.g. Flask `c2705ffd` hides fix #2935 in `ctx.py` `copy()`).
+- Labels match on commit/check/path/cited commit, not line: when a rule moves a warning to another line,
+  re-check its label (#40 found two that way).
+- Contributors: Sandro850 (#30, #38, #40). Open issues: #2–#4, #6 (bench cases), #33 (guard reports),
+  #36 (keyword-argument noise).
+- Launch: dev.to post published 2026-10-24; the CVE sentence there should mention the withdrawn advisory.

{blot_git-0.6.0 → blot_git-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blot-git
-Version: 0.6.0
+Version: 0.7.0
 Summary: A pre-commit check that has read your project's history: warns when a change removes a fix, re-adds a fixed bug, or forgets a file that always changes too.
 Project-URL: Homepage, https://github.com/Sym-jay/Blot
 Project-URL: Issues, https://github.com/Sym-jay/Blot/issues
@@ -43,6 +43,7 @@ cd your-repo
 blot index           # optional: the first check indexes history itself
 blot install-hook    # adds Blot to your pre-commit hook
 blot why src/app.py:42   # which commit explains this line, skipping refactors
+blot map src/app.py      # which lines of the file exist because of bug fixes
 blot index --github  # optional: issue/PR titles and labels via the gh CLI
 ```
 
@@ -50,6 +51,11 @@ blot index --github  # optional: issue/PR titles and labels via the gh CLI
 an edit an agent is about to make, so the agent sees "this line exists because of fix 8efea0c" before
 it "simplifies" it away. It warns by default; `--ask` makes Claude Code ask you first.
 
+**Tell agents before they plan.** `blot mcp` is a stdio MCP server (standard library only) with two
+read-only tools, `load_bearing_lines` (like `blot map`) and `explain_lines` (like `blot why`), so an agent
+can look at a file's fixes before deciding what to change. `blot install-mcp` registers it in `.mcp.json`
+for Claude Code; `--local` registers it just for you.
+
 > **Status:** pre-alpha. All three checks work. Replayed on 500 recent commits each of Flask, requests, Express, Django and React, Blot warns on 0.6–9.5% of commits, and about half of its warnings (labelled by hand) are worth a reviewer's time; see the bench results on GitHub. Please report false alarms.
 
 Meet Sora the slime, read the docs, or contribute on GitHub: https://github.com/Sym-jay/Blot

{blot_git-0.6.0 → blot_git-0.7.0}/README.md

@@ -71,6 +71,61 @@ src/flask/app.py:355
 
 `blot why FILE:LINE` (or `FILE:START-END`) finds the commit that explains a line, skipping commits that only moved it. Plain `git blame` stops at the refactor.
 
+## Map a file's load-bearing lines
+
+```
+$ blot map src/flask/app.py
+src/flask/app.py: 3 load-bearing lines in 2 ranges, from 2 fixes
+
+355        | self_ref = weakref.ref(self)
+             8efea0c "Break reference cycle created by default in Flask instances." (2020-10-03)
+             traced past refactor 0ec7f71 "Split the App and Blueprint into Sansio and IO parts"
+
+1061-1062  | rv = self.response_class()
+           | rv.allow.update(methods)
+             dbf55de "Fixed an issue where the default `OPTIONS` response was not exposing all valid methods in the `Allow` header." (2010-07-28, fixes #97)
+             traced past refactor 0ec7f71 "Split the App and Blueprint into Sansio and IO parts"
+```
+
+`blot map FILE` runs `why` over a whole file and keeps the lines whose explaining commit is a bug fix:
+the lines `blot check` would warn about if you changed them. Consecutive lines from one fix are grouped.
+`--full` prints the whole file with the fix commit in the gutter, `--format json` gives the ranges and
+commits as JSON, `--rev` maps an older version, and `--min-severity 1` also counts routine fixes.
+On Flask's 1,625-line `app.py` it takes about 1.5 s.
+
+## Give agents the history before they edit (MCP)
+
+`blot mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on stdio, so a coding
+agent can ask about a file *before* it plans a change, instead of hearing about it from `blot guard` at
+the last moment. It has two read-only tools:
+
+| Tool | Same as | Arguments |
+|---|---|---|
+| `load_bearing_lines` | `blot map FILE` | `path`, optional `rev`, `min_severity` |
+| `explain_lines` | `blot why FILE:START-END` | `path`, `start`, optional `end`, `rev` |
+
+Each returns one paragraph per commit: short sha, date, subject, linked issues, the lines it explains
+and any refactor traced past. The same data comes back as JSON in `structuredContent`.
+
+```bash
+blot install-mcp           # adds `blot` to .mcp.json at the repo root and builds the index
+blot install-mcp --local   # or just for you, via `claude mcp add --scope local` (needs the claude CLI)
+```
+
+Claude Code asks each person once before it starts a server from `.mcp.json`. The entry names this
+machine's Python by absolute path, like `install-agent-hook` does, so prefer `--local` if your team
+commits `.mcp.json`. Other servers in the file are left alone; remove Blot's entry with
+`blot install-mcp --uninstall` (add `--local` if you installed it that way). To register it by hand:
+
+```bash
+claude mcp add --scope local --transport stdio blot -- python -m blot mcp
+```
+
+The server works on the repository it is started in (or `blot --repo PATH mcp`). It speaks MCP
+2026-07-28 and the earlier `initialize`-handshake versions (2024-11-05 to 2025-11-25), uses only the
+standard library, writes nothing but protocol messages to stdout, and answers a bad path or an
+untracked file with a tool error rather than exiting.
+
 ## Guard coding agents
 
 Coding agents are the most likely to "clean up" a line they don't understand. `blot guard` is a
@@ -127,7 +182,7 @@ jobs:
   blot:
     runs-on: ubuntu-latest
     steps:
-      - uses: Sym-jay/Blot@v0.6.0
+      - uses: Sym-jay/Blot@v0.7.0
 ```
 
 The action checks out the pull request with its full history, installs Blot, runs `blot index` and

{blot_git-0.6.0 → blot_git-0.7.0}/action.yml

@@ -1,6 +1,6 @@
 # Run Blot on a pull request and show its findings as warning annotations.
 # Usage (in a workflow triggered by pull_request):
-#   - uses: Sym-jay/Blot@v0.6.0
+#   - uses: Sym-jay/Blot@v0.7.0
 # See "Use in CI" in README.md.
 name: Blot
 description: History-aware checks on the commits of a pull request, shown as warning annotations

{blot_git-0.6.0 → blot_git-0.7.0}/bench/RESULTS.md

@@ -2,12 +2,12 @@
 
 Measured 2026-10-30 with `blot bench`, on Windows 11, Python 3.12.
 
-## Cases: 32/32 correct
+## Cases: 33/33 correct
 
 | Check | Cases | Precision | Recall |
 |---|---|---|---|
 | removed-fix | 24 (16 warn, 8 quiet) | 100% | 100% |
-| readded-bug | 5 (4 warn, 1 quiet) | 100% | 100% |
+| readded-bug | 6 (4 warn, 2 quiet) | 100% | 100% |
 | forgot-related-file | 3 (3 quiet) | n/a | n/a |
 
 A quiet case now fails if its scripted edit can't be applied (it used to pass without running).
@@ -58,7 +58,23 @@ code from earlier fixes and CVEs.
 | commits cited as fixes that weren't: `Fixed #21189: Cleaned up ...`, `Fixed #12882 - Moved ...`, `[DevTools] upgrade to Manifest V3`, `Change Flask.__init__ to accept ...`, error-message wording (6) | `Fixed #N:` / `Fixed #N -` ticket styles judged by their description; cleanups count as refactors; `[Tag]` prefixes and "change" subjects count as features; error messages are routine |
 | docstrings with `backticks` or (asides) (1) | they count as prose |
 
-### Noise still there (52 warnings)
+### Since 0.6.0: real docstrings (#40, by @Sandro850)
+
+`removed-fix` now parses the old Python file (`ast`, only when a warning is already on its way) and skips
+lines inside real module, class and function docstrings. That removed one Django noise warning. It also
+exposed two of **our** labels as wrong: in Flask `c2705ffd` and Django `ebcb13b3`, the warning used to point at
+a docstring line, but the same change also edits the fix's code (Flask's `copy()` passing
+`session=self.session`, from fix #2935; Django's `isinstance(normalized, (dict, str))` check, from the
+CVE-2026-15307 fix). Now the warning points at the code, and both are relabelled useful.
+
+| Repo | Before | After |
+|---|---|---|
+| pallets/flask | 3/4 (75%) | **4/4 (100%)** |
+| django/django | 40/59 (68%) | **41/58 (71%)** |
+| requests, Express, React | unchanged | unchanged |
+| **All five** | 57/109 (52.3%) | **59/108 (54.6%)** |
+
+### Noise still there (49 warnings)
 
 | Pattern | Warnings | Why there's no rule yet |
 |---|---|---|
@@ -67,7 +83,6 @@ code from earlier fixes and CVEs.
 | new argument or keyword argument on a fix's call | 3 | adding an argument can change behaviour |
 | formatter reflows with f-strings or joined lines (requests' Black commit) | 4 | dropping parentheses can change precedence |
 | deleting a legacy module or feature in pieces (React) | 6 | intentional, but only the commit message says so |
-| docstring lines that still read as code | 3 | needs to know it's inside a docstring, not just how the line looks |
 | other: code moved to another file, fix behaviour kept while restructuring, generic re-added lines | 16 | case by case |
 
 **`forgot-related-file` has shown no useful warning yet**: 0/45 before this release, 0/9 after. It

{blot_git-0.6.0 → blot_git-0.7.0}/bench/cases.json

@@ -439,5 +439,20 @@
       "warn": false
     },
     "notes": "Black's formatting change from 2a6f290b in should_strip_auth. Formatting only: must stay quiet."
+  },
+  {
+    "id": "requests-quiet-per-host-proxy-feature",
+    "repo": "https://github.com/psf/requests",
+    "at": "48fe34447de02bfe9827321fafe3277741d77c38",
+    "file": "requests/adapters.py",
+    "replace": [
+      "        u = urlparse(url.lower())\n        proxy = proxies.get(u.scheme+'://'+u.hostname, proxies.get(u.scheme))",
+      "        proxy = proxies.get(urlparse(url.lower()).scheme)"
+    ],
+    "expect": {
+      "check": "readded-bug",
+      "warn": false
+    },
+    "notes": "Re-adds the exact line removed by 48fe3444. Although the commit says Fixes #2722, it implements the per-host proxy feature rather than fixing a regression. Blot classifies it with severity 1, so its removed line must not be indexed as a bug fix."
   }
 ]

{blot_git-0.6.0 → blot_git-0.7.0}/bench/labels/django-django.json

@@ -579,8 +579,8 @@
    "path": "django/contrib/gis/gdal/raster/source.py",
    "line": 37,
    "cited": "f1949c1",
-   "verdict": "noise",
-   "reason": "docstring"
+   "verdict": "useful",
+   "reason": "extends the isinstance check from the CVE-2026-15307 fix to bytes (was mislabelled: the old warning pointed at the docstring line above)"
   },
   {
    "sha": "62ef9d40c",

{blot_git-0.6.0 → blot_git-0.7.0}/bench/labels/pallets-flask.json

@@ -49,8 +49,8 @@
    "path": "src/flask/ctx.py",
    "line": 348,
    "cited": "e08bcf9",
-   "verdict": "noise",
-   "reason": "docstring rewording"
+   "verdict": "useful",
+   "reason": "changes the copy() call that passes session=self.session, from fix #2935 (was mislabelled: the old warning pointed at the docstring line above)"
   }
  ]
 }

{blot_git-0.6.0 → blot_git-0.7.0}/docs/PRD.md

@@ -106,6 +106,20 @@ competitors tested (code-archaeologist, lore, Entire), none guards an edit befor
 - `blot install-agent-hook [--local] [--ask] [--uninstall]` edits `.claude/settings.json` (or
   `settings.local.json`) without touching other hooks.
 
+### F8. `blot map FILE` and `blot mcp`: history before the agent plans (unreleased)
+- `blot map FILE [--rev R] [--format json] [--full] [--min-severity N]`: every line whose explaining commit
+  (traced past refactors, as `why` does) is a fix at or above `min_severity`, grouped into ranges per fix.
+  It considers the lines `removed-fix` guards (no blank, generic, prose or docstring lines). One blame
+  of the whole file plus refactor hops: ~1.5 s on Flask's 1,625-line `app.py`.
+- `blot mcp`: a stdio MCP server, stdlib only. Tools `explain_lines(path, start, end?, rev?)` (= `why`) and
+  `load_bearing_lines(path, rev?, min_severity?)` (= `map`) return one paragraph per commit plus
+  `structuredContent`. It speaks MCP 2026-07-28 (`server/discover`, per-request `_meta`) and the
+  `initialize` handshake of 2024-11-05 to 2025-11-25. Bad paths and untracked files are tool errors
+  (`isError: true`); only protocol messages go to stdout.
+- `blot install-mcp [--local] [--uninstall]` adds `blot` to `.mcp.json` without touching other servers,
+  or with `--local` runs `claude mcp add --scope local`.
+- Why: `why` explains rather than warns, so unlike `guard` it isn't hurt by the checks' noise (55% precision).
+
 ## 6. User flows
 
 **First run (2 minutes):**
@@ -175,7 +189,7 @@ The user either reads the linked issue and adjusts the change, or commits anyway
 | GitHub only | GitLab and Bitbucket links; mailing lists (Linux, Postgres) |
 | | GitHub Action that comments on PRs |
 | | VS Code extension that shows warnings as you edit |
-| | MCP server, so AI agents can ask before editing (the `blot guard` hook, F7, covers Claude Code) |
+| | ~~MCP server, so AI agents can ask before editing~~ done (unreleased): `blot mcp` with `explain_lines` and `load_bearing_lines`, alongside the `blot guard` hook (F7) |
 
 ## 10. Success metrics
 
@@ -204,7 +218,7 @@ The user either reads the linked issue and adjusts the change, or commits anyway
 | 1 | **M1: index + config + hook installer** | `blot index` builds the DB on Flask in under 10 s; `install-hook` is safe with existing hooks |
 | 2 | **M2: three checks** | All unit tests pass, including the "trace past refactor" test (currently skipped) |
 | 3 | **M3: `why` + `--github` + output polish** ✅ | The Flask case prints the 2020 fix, traced past the 2023 refactor; `--github` adds issue titles and labels |
-| 4 | **M4: bench + launch** (32 cases ✅, replay precision 52% of the 80% target, launch pending) | 30 bench cases, precision ≥ 80%, PyPI release, README GIF, Show HN / r/Python post |
+| 4 | **M4: bench + launch** (33 cases ✅, replay precision 52% of the 80% target, launch pending) | 30 bench cases, precision ≥ 80%, PyPI release, README GIF, Show HN / r/Python post |
 
 ## 13. Open questions
 

{blot_git-0.6.0 → blot_git-0.7.0}/docs/PYPI.md

@@ -18,6 +18,7 @@ cd your-repo
 blot index           # optional: the first check indexes history itself
 blot install-hook    # adds Blot to your pre-commit hook
 blot why src/app.py:42   # which commit explains this line, skipping refactors
+blot map src/app.py      # which lines of the file exist because of bug fixes
 blot index --github  # optional: issue/PR titles and labels via the gh CLI
 ```
 
@@ -25,6 +26,11 @@ blot index --github  # optional: issue/PR titles and labels via the gh CLI
 an edit an agent is about to make, so the agent sees "this line exists because of fix 8efea0c" before
 it "simplifies" it away. It warns by default; `--ask` makes Claude Code ask you first.
 
+**Tell agents before they plan.** `blot mcp` is a stdio MCP server (standard library only) with two
+read-only tools, `load_bearing_lines` (like `blot map`) and `explain_lines` (like `blot why`), so an agent
+can look at a file's fixes before deciding what to change. `blot install-mcp` registers it in `.mcp.json`
+for Claude Code; `--local` registers it just for you.
+
 > **Status:** pre-alpha. All three checks work. Replayed on 500 recent commits each of Flask, requests, Express, Django and React, Blot warns on 0.6–9.5% of commits, and about half of its warnings (labelled by hand) are worth a reviewer's time; see the bench results on GitHub. Please report false alarms.
 
 Meet Sora the slime, read the docs, or contribute on GitHub: https://github.com/Sym-jay/Blot

{blot_git-0.6.0 → blot_git-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "blot-git"
-version = "0.6.0"
+version = "0.7.0"
 description = "A pre-commit check that has read your project's history: warns when a change removes a fix, re-adds a fixed bug, or forgets a file that always changes too."
 readme = "docs/PYPI.md"  # text-only; the GitHub README's relative Sora images break on PyPI
 license = { text = "MIT" }

{blot_git-0.6.0 → blot_git-0.7.0}/src/blot/__init__.py

@@ -1,3 +1,3 @@
 """blot: history-aware pre-commit checks."""
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{blot_git-0.6.0 → blot_git-0.7.0}/src/blot/checks/base.py

@@ -63,3 +63,13 @@ def describe_commit(row: CommitRow, store: Store | None = None) -> str:
         refs = [store.describe_issue(ref) for ref in row.issues] if store else row.issues
         details.append("fixes " + ", ".join(refs))
     return f'{row.sha[:7]} "{row.subject}" ({", ".join(details)})'
+
+
+def describe_trail(row: CommitRow, via: list[str], store: Store) -> list[str]:
+    """describe_commit, then one 'traced past refactor 0ec7f71 "subject"' line per refactor hop."""
+    lines = [describe_commit(row, store)]
+    for sha in via:
+        ref = store.get_commit(sha)
+        if ref is not None:
+            lines.append(f'traced past refactor {sha[:7]} "{ref.subject}"')
+    return lines

{blot_git-0.6.0 → blot_git-0.7.0}/src/blot/checks/removed_fix.py

@@ -13,16 +13,26 @@ normalized text, preferring the same path. That is how a file split is followed
 
 from __future__ import annotations
 
-from blot.checks.base import Check, Finding, describe_commit, is_skipped
-from blot.diff import KeptLines, is_meaningful_line, normalize_line
+import subprocess
+
+from blot.checks.base import Check, Finding, describe_trail, is_skipped
+from blot.diff import (
+    KeptLines,
+    is_meaningful_line,
+    normalize_line,
+    python_docstring_lines,
+)
+from blot.git import run_git
 from blot.trace import RefactorOrigins, trace_lines
 
+
 class RemovedFix(Check):
     id = "removed-fix"
     description = "Changing code that a bug fix added"
 
     def run(self, changes, store, config) -> list[Finding]:
         origins = RefactorOrigins(store.repo)
+        docstrings: dict[tuple[str, str], set[int] | None] = {}
         findings: list[Finding] = []
         # a line that reappears anywhere in the change was moved, not removed
         moved = {normalize_line(text) for c in changes for _, text in c.added}
@@ -41,19 +51,33 @@ class RemovedFix(Check):
                 continue
 
             trail = trace_lines(store, store.rev, change.old_path, texts, origins)
+            candidates = []
+            for n in sorted(trail):
+                row = store.get_commit(trail[n].sha)
+                if row is not None and not row.is_refactor and row.severity >= config.min_severity:
+                    candidates.append((n, trail[n], row))
+            if not candidates:
+                continue
+
+            docstring_lines: set[int] | None = None
+            if change.old_path.endswith(".py"):
+                key = (store.rev, change.old_path)
+                if key not in docstrings:
+                    try:
+                        source = run_git(store.repo, "show", f"{store.rev}:{change.old_path}")
+                    except subprocess.CalledProcessError:
+                        docstrings[key] = None
+                    else:
+                        docstrings[key] = python_docstring_lines(source)
+                docstring_lines = docstrings[key]
 
             reported: set[str] = set()
-            for n in sorted(trail):
-                sha, via = trail[n].sha, trail[n].via
-                row = store.get_commit(sha)
-                if row is None or row.is_refactor or row.severity < config.min_severity or sha in reported:
+            for n, traced, row in candidates:
+                sha, via = traced.sha, traced.via
+                if (docstring_lines is not None and n in docstring_lines) or sha in reported:
                     continue
                 reported.add(sha)  # one finding per fix per file, at its first line
-                evidence = [describe_commit(row, store)]
-                for ref_sha in via:
-                    ref = store.get_commit(ref_sha)
-                    if ref is not None:
-                        evidence.append(f'traced past refactor {ref_sha[:7]} "{ref.subject}"')
+                evidence = describe_trail(row, via, store)
                 findings.append(Finding(
                     self.id, change.old_path, n,
                     "You're removing or changing a line that a bug fix added.\n"

{blot_git-0.6.0 → blot_git-0.7.0}/src/blot/cli.py

@@ -4,9 +4,12 @@ Commands:
     index         build or refresh the local history index (.git/blot.db)
     check         run all checks against staged changes (pre-commit) or a commit range
     why           show the history behind a line: fix commits, PR, linked issues
+    map           show which lines of a file exist because of bug fixes
+    mcp           MCP server on stdio for coding agents (explain_lines, load_bearing_lines)
     install-hook  add blot to .git/hooks/pre-commit
     guard         Claude Code hook: warn a coding agent before it edits a line a fix added
     install-agent-hook  add `blot guard` to .claude/settings.json
+    install-mcp   add `blot mcp` to .mcp.json (or `claude mcp add --scope local`)
     bench         measure accuracy: bench cases, or replay recent commits (--replay N)
 """
 
@@ -46,19 +49,9 @@ def _cmd_index(args: argparse.Namespace) -> int:
 
 
 def _open_index(repo: str):
-    """Open the index, building or refreshing it first.
+    from blot.index import open_index
 
-    The pre-commit framework installs Blot where users can't easily run `blot index`, so the hook
-    must look after the index itself: one full build on first use, then cheap incremental refreshes.
-    """
-    from blot.index import build_index
-    from blot.store import Store
-
-    if not os.path.exists(Store.db_path(repo)):
-        print("blot: first run, indexing this repo's history once (big repos can take a minute)...",
-              file=sys.stderr)
-    build_index(repo)
-    return Store.open(repo)
+    return open_index(repo)
 
 
 def _cmd_check(args: argparse.Namespace) -> int:
@@ -93,6 +86,48 @@ def _cmd_why(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_map(args: argparse.Namespace) -> int:
+    import json
+
+    from blot.fixmap import build_map, render, to_json
+    from blot.why import WhyError
+
+    min_severity = args.min_severity if args.min_severity is not None else load_config(args.repo).min_severity
+    store = _open_index(args.repo)
+    try:
+        fmap = build_map(store, args.file, args.rev, min_severity)
+        text = json.dumps(to_json(store, fmap), indent=2) + "\n" if args.format == "json" else render(store, fmap, args.full)
+    except WhyError as exc:
+        print(f"blot: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        store.close()
+    print(text, end="")
+    return 0
+
+
+def _cmd_mcp(args: argparse.Namespace) -> int:
+    from blot.mcp import serve_stdio
+
+    return serve_stdio(args.repo)
+
+
+def _cmd_install_mcp(args: argparse.Namespace) -> int:
+    from blot import hooks
+
+    if args.uninstall:
+        print(f"blot: MCP server {hooks.uninstall_mcp(args.repo, local=args.local)}")
+        return 0
+    try:
+        status, where = hooks.install_mcp(args.repo, local=args.local)
+    except (ValueError, RuntimeError) as exc:
+        print(f"blot: not installed: {exc}", file=sys.stderr)
+        return 1
+    print(f"blot: MCP server {status} ({where})")
+    _open_index(args.repo).close()  # a first index can take a minute: build it now, not in a tool call
+    return 0
+
+
 def _cmd_install_hook(args: argparse.Namespace) -> int:
     from blot import hooks
 
@@ -192,6 +227,24 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--rev", default="HEAD", help="explain the file as of this commit (default: HEAD)")
     p.set_defaults(func=_cmd_why)
 
+    p = sub.add_parser("map", help="show which lines of a file exist because of bug fixes")
+    p.add_argument("file", metavar="FILE", help="e.g. src/app.py")
+    p.add_argument("--rev", default="HEAD", help="map the file as of this commit (default: HEAD)")
+    p.add_argument("--format", choices=["text", "json"], default="text")
+    p.add_argument("--full", action="store_true", help="print the whole file with fix commits in the gutter")
+    p.add_argument("--min-severity", type=int, choices=[1, 2], default=None,
+                   help="1 also counts routine fixes (default: min-severity from config, normally 2)")
+    p.set_defaults(func=_cmd_map)
+
+    p = sub.add_parser("mcp", help="run an MCP server on stdio (explain_lines, load_bearing_lines) for coding agents")
+    p.set_defaults(func=_cmd_mcp)
+
+    p = sub.add_parser("install-mcp", help="register `blot mcp` with Claude Code (.mcp.json)")
+    p.add_argument("--uninstall", action="store_true", help="remove blot's entry")
+    p.add_argument("--local", action="store_true",
+                   help="just for you, in this project (runs `claude mcp add --scope local`) instead of .mcp.json")
+    p.set_defaults(func=_cmd_install_mcp)
+
     p = sub.add_parser("install-hook", help="add blot to .git/hooks/pre-commit")
     p.add_argument("--uninstall", action="store_true", help="remove blot's lines from the hook")
     p.set_defaults(func=_cmd_install_hook)

{blot_git-0.6.0 → blot_git-0.7.0}/src/blot/diff.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import ast
 import hashlib
 import re
 from dataclasses import dataclass, field
@@ -105,6 +106,30 @@ def is_meaningful_line(normalized: str) -> bool:
     return bool(normalized) and not is_trivial_line(normalized) and not is_prose_line(normalized)
 
 
+def python_docstring_lines(source: str) -> set[int] | None:
+    """Line numbers occupied by real Python docstrings, or None if parsing fails."""
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError, RecursionError):
+        return None
+
+    lines: set[int] = set()
+    scopes = (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+    for node in ast.walk(tree):
+        if not isinstance(node, scopes) or not node.body:
+            continue
+        first = node.body[0]
+        if not (
+            isinstance(first, ast.Expr)
+            and isinstance(first.value, ast.Constant)
+            and isinstance(first.value.value, str)
+        ):
+            continue
+        end = first.value.end_lineno or first.value.lineno
+        lines.update(range(first.value.lineno, end + 1))
+    return lines
+
+
 def line_hash(normalized: str) -> str:
     return hashlib.blake2b(normalized.encode("utf-8"), digest_size=8).hexdigest()