research-git 0.0.2__tar.gz → 0.0.4__tar.gz

{research_git-0.0.2/src/research_git.egg-info → research_git-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: research-git
-Version: 0.0.2
+Version: 0.0.4
 Summary: A memory system that captures code ideas as semantic capsules you can regenerate onto today's codebase
 Author: Stepzero Lab
 License-Expression: MIT
@@ -43,15 +43,13 @@ Dynamic: license-file
   <strong>Git recovers history. It can't recover an entangled idea onto today's code.</strong>
 </p>
 
----
-
-**You're deep into building an agent. You've tried twenty things — a restructured system prompt, splitting one overloaded tool into three, a re-ranking step before retrieval, a scratchpad for intermediate reasoning, two different few-shot sets — half of them commented in and out, all tangled together in one working tree. Now you want *one* of those ideas back. Not the stale commit it lived in. The idea itself, re-applied to the agent you have today.**
-
-Git can't do that. Its unit is a *tree snapshot*, not an *idea*. `git checkout` drags back everything from that moment and throws away all the infrastructure you've built since. You can't pull one feature forward without rolling back the rest.
+<p align="center">
+  <img src="assets/hero.png" alt="Capture a code idea as a clean semantic unit — regenerate it onto today's codebase." width="800" />
+</p>
 
-research-git makes the **idea** the unit. It captures each change as a self-contained **Feature Capsule**, stores it in a graph, and — when you want it back — *regenerates* it onto your current code instead of pasting a stale patch. The capsule is a specification of intent; the code is always rebuilt against today's reality.
+research-git captures experiments as Feature Capsules, then regenerates the one you need onto your current agent, using your existing Coding Plan subscription, no pay-per-use API.
 
-The intelligent steps (segmenting a diff into capsules, regenerating one onto changed code) run as **subagents on your existing Claude subscription** — there is **no pay-per-use API** anywhere.
+> **Think of it as Git for agentic coding experiments: not just recovering old code, but bringing old ideas back into today’s code.**
 
 ---
 
@@ -104,9 +102,9 @@ Five steps: install → init → run → capture → recall.
 pip install research-git        # or, from a clone: pip install -e .
 
 # wire the plugin (agents + skills) and the MCP server into your client
-rgit install claude-code        # Claude Code (via the official `claude` CLI)
-rgit install codex              # Codex / Gemini / opencode: symlinks the skills into ~/.agents/skills/
-rgit install --list             # all platforms; add --dry-run to preview, --uninstall to remove
+rgit install                    # auto-detects every agent client on this machine and wires them all
+rgit install claude-code        # or pick one explicitly (claude-code / codex / gemini / opencode / generic)
+rgit install --list             # list platforms; --uninstall to remove
 ```
 
 `codex`, `gemini`, and `opencode` share the `~/.agents/skills/` convention — the installer symlinks each skill there and prints the one-line MCP server entry to drop into that client's config. It also writes a managed research-git guidance block into the client's global guidance file when the platform has one (`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, or `~/.gemini/GEMINI.md`). On an interactive terminal you're asked how proactive capture should be — `default`, `manual-only`, or `none`; pass `--guidance <mode>` to choose non-interactively. Start a new agent session after install so the guidance is loaded. Prefer the manual route on Claude Code? `/plugin marketplace add StepzeroLab/research-git` then `/plugin install research-git@research-git`.
@@ -118,6 +116,14 @@ cd your-project
 rgit init                       # creates .rgit/ (the store) at the git root
 ```
 
+**Optional — capture on every commit.** `rgit install <platform>` wires the agent side only; it deliberately does **not** touch your git hooks. If you also want every `git commit` to stage its own diff as a pending proposal automatically, opt in with:
+
+```bash
+rgit install-hooks              # adds a post-commit hook (never clobbers an existing one)
+```
+
+Good fit: solo research repos where you want nothing to slip through, even when you forget to capture. Skip it if the repo already has its own post-commit hook (the installer refuses to touch foreign hooks, so nothing breaks — it just won't install), if your team prefers deliberate manual capture, or in CI/shared clones where commit-time side effects are unwelcome. Without hooks you lose nothing: bare `rgit capture` takes the last commit when the tree is clean, `rgit capture A..B` a whole span, and `rgit review` is the gate either way — hooks only stage proposals, they never approve anything. Remove with `rgit install-hooks --uninstall`.
+
 ### 3. Run a variation and capture the idea
 
 Launch your work through `rgit run` — it executes your command, freezes a reproducible artifact, records the run + any metrics, and stages what changed:
@@ -134,6 +140,8 @@ rgit review              # list proposals
 rgit review --approve <proposal_id> --name rerank-retrieval
 ```
 
+Committed before capturing? Just run `rgit capture` — on a clean tree it captures the last commit (and says which one); `rgit capture main..HEAD` takes a whole span. (With the optional post-commit hook installed, every commit stages itself automatically.)
+
 ### 4. Bring an idea back onto today's code
 
 Weeks later, after the agent has moved on:
@@ -198,7 +206,8 @@ The five-step loop above is the core. These show up as your store grows — run
 | Command | What it does |
 |---------|--------------|
 | `rgit watch` | free, deterministic background capture — stages raw material as you edit, so fleeting in-between states aren't lost |
-| `rgit install-hooks` | stage on every commit via a post-commit hook (won't touch an existing hook) |
+| `rgit capture [REV \| A..B]` | bare: auto-picks the working tree or, when clean, the last commit; pass a commit or an A..B range for precise control |
+| `rgit install-hooks` | opt-in: stage every commit's diff via a post-commit hook (not installed by `rgit install`; won't touch an existing hook) — see step 2 above |
 | `rgit run --from <capsule>` | run a recalled variant and link the new run as a `variant_of` the original |
 | `rgit compare <query>` | which variant won: ranked table, Δ vs baseline, ★ winner |
 | `rgit provenance <run_id>` | per-feature clean (capsule) vs agent-adapted (frozen) diff for a run |

{research_git-0.0.2 → research_git-0.0.4}/README.md

@@ -17,15 +17,13 @@
   <strong>Git recovers history. It can't recover an entangled idea onto today's code.</strong>
 </p>
 
----
-
-**You're deep into building an agent. You've tried twenty things — a restructured system prompt, splitting one overloaded tool into three, a re-ranking step before retrieval, a scratchpad for intermediate reasoning, two different few-shot sets — half of them commented in and out, all tangled together in one working tree. Now you want *one* of those ideas back. Not the stale commit it lived in. The idea itself, re-applied to the agent you have today.**
-
-Git can't do that. Its unit is a *tree snapshot*, not an *idea*. `git checkout` drags back everything from that moment and throws away all the infrastructure you've built since. You can't pull one feature forward without rolling back the rest.
+<p align="center">
+  <img src="assets/hero.png" alt="Capture a code idea as a clean semantic unit — regenerate it onto today's codebase." width="800" />
+</p>
 
-research-git makes the **idea** the unit. It captures each change as a self-contained **Feature Capsule**, stores it in a graph, and — when you want it back — *regenerates* it onto your current code instead of pasting a stale patch. The capsule is a specification of intent; the code is always rebuilt against today's reality.
+research-git captures experiments as Feature Capsules, then regenerates the one you need onto your current agent, using your existing Coding Plan subscription, no pay-per-use API.
 
-The intelligent steps (segmenting a diff into capsules, regenerating one onto changed code) run as **subagents on your existing Claude subscription** — there is **no pay-per-use API** anywhere.
+> **Think of it as Git for agentic coding experiments: not just recovering old code, but bringing old ideas back into today’s code.**
 
 ---
 
@@ -78,9 +76,9 @@ Five steps: install → init → run → capture → recall.
 pip install research-git        # or, from a clone: pip install -e .
 
 # wire the plugin (agents + skills) and the MCP server into your client
-rgit install claude-code        # Claude Code (via the official `claude` CLI)
-rgit install codex              # Codex / Gemini / opencode: symlinks the skills into ~/.agents/skills/
-rgit install --list             # all platforms; add --dry-run to preview, --uninstall to remove
+rgit install                    # auto-detects every agent client on this machine and wires them all
+rgit install claude-code        # or pick one explicitly (claude-code / codex / gemini / opencode / generic)
+rgit install --list             # list platforms; --uninstall to remove
 ```
 
 `codex`, `gemini`, and `opencode` share the `~/.agents/skills/` convention — the installer symlinks each skill there and prints the one-line MCP server entry to drop into that client's config. It also writes a managed research-git guidance block into the client's global guidance file when the platform has one (`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, or `~/.gemini/GEMINI.md`). On an interactive terminal you're asked how proactive capture should be — `default`, `manual-only`, or `none`; pass `--guidance <mode>` to choose non-interactively. Start a new agent session after install so the guidance is loaded. Prefer the manual route on Claude Code? `/plugin marketplace add StepzeroLab/research-git` then `/plugin install research-git@research-git`.
@@ -92,6 +90,14 @@ cd your-project
 rgit init                       # creates .rgit/ (the store) at the git root
 ```
 
+**Optional — capture on every commit.** `rgit install <platform>` wires the agent side only; it deliberately does **not** touch your git hooks. If you also want every `git commit` to stage its own diff as a pending proposal automatically, opt in with:
+
+```bash
+rgit install-hooks              # adds a post-commit hook (never clobbers an existing one)
+```
+
+Good fit: solo research repos where you want nothing to slip through, even when you forget to capture. Skip it if the repo already has its own post-commit hook (the installer refuses to touch foreign hooks, so nothing breaks — it just won't install), if your team prefers deliberate manual capture, or in CI/shared clones where commit-time side effects are unwelcome. Without hooks you lose nothing: bare `rgit capture` takes the last commit when the tree is clean, `rgit capture A..B` a whole span, and `rgit review` is the gate either way — hooks only stage proposals, they never approve anything. Remove with `rgit install-hooks --uninstall`.
+
 ### 3. Run a variation and capture the idea
 
 Launch your work through `rgit run` — it executes your command, freezes a reproducible artifact, records the run + any metrics, and stages what changed:
@@ -108,6 +114,8 @@ rgit review              # list proposals
 rgit review --approve <proposal_id> --name rerank-retrieval
 ```
 
+Committed before capturing? Just run `rgit capture` — on a clean tree it captures the last commit (and says which one); `rgit capture main..HEAD` takes a whole span. (With the optional post-commit hook installed, every commit stages itself automatically.)
+
 ### 4. Bring an idea back onto today's code
 
 Weeks later, after the agent has moved on:
@@ -172,7 +180,8 @@ The five-step loop above is the core. These show up as your store grows — run
 | Command | What it does |
 |---------|--------------|
 | `rgit watch` | free, deterministic background capture — stages raw material as you edit, so fleeting in-between states aren't lost |
-| `rgit install-hooks` | stage on every commit via a post-commit hook (won't touch an existing hook) |
+| `rgit capture [REV \| A..B]` | bare: auto-picks the working tree or, when clean, the last commit; pass a commit or an A..B range for precise control |
+| `rgit install-hooks` | opt-in: stage every commit's diff via a post-commit hook (not installed by `rgit install`; won't touch an existing hook) — see step 2 above |
 | `rgit run --from <capsule>` | run a recalled variant and link the new run as a `variant_of` the original |
 | `rgit compare <query>` | which variant won: ranked table, Δ vs baseline, ★ winner |
 | `rgit provenance <run_id>` | per-feature clean (capsule) vs agent-adapted (frozen) diff for a run |

{research_git-0.0.2 → research_git-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "research-git"
-version = "0.0.2"
+version = "0.0.4"
 description = "A memory system that captures code ideas as semantic capsules you can regenerate onto today's codebase"
 readme = "README.md"
 license = "MIT"

{research_git-0.0.2 → research_git-0.0.4/src/research_git.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: research-git
-Version: 0.0.2
+Version: 0.0.4
 Summary: A memory system that captures code ideas as semantic capsules you can regenerate onto today's codebase
 Author: Stepzero Lab
 License-Expression: MIT
@@ -43,15 +43,13 @@ Dynamic: license-file
   <strong>Git recovers history. It can't recover an entangled idea onto today's code.</strong>
 </p>
 
----
-
-**You're deep into building an agent. You've tried twenty things — a restructured system prompt, splitting one overloaded tool into three, a re-ranking step before retrieval, a scratchpad for intermediate reasoning, two different few-shot sets — half of them commented in and out, all tangled together in one working tree. Now you want *one* of those ideas back. Not the stale commit it lived in. The idea itself, re-applied to the agent you have today.**
-
-Git can't do that. Its unit is a *tree snapshot*, not an *idea*. `git checkout` drags back everything from that moment and throws away all the infrastructure you've built since. You can't pull one feature forward without rolling back the rest.
+<p align="center">
+  <img src="assets/hero.png" alt="Capture a code idea as a clean semantic unit — regenerate it onto today's codebase." width="800" />
+</p>
 
-research-git makes the **idea** the unit. It captures each change as a self-contained **Feature Capsule**, stores it in a graph, and — when you want it back — *regenerates* it onto your current code instead of pasting a stale patch. The capsule is a specification of intent; the code is always rebuilt against today's reality.
+research-git captures experiments as Feature Capsules, then regenerates the one you need onto your current agent, using your existing Coding Plan subscription, no pay-per-use API.
 
-The intelligent steps (segmenting a diff into capsules, regenerating one onto changed code) run as **subagents on your existing Claude subscription** — there is **no pay-per-use API** anywhere.
+> **Think of it as Git for agentic coding experiments: not just recovering old code, but bringing old ideas back into today’s code.**
 
 ---
 
@@ -104,9 +102,9 @@ Five steps: install → init → run → capture → recall.
 pip install research-git        # or, from a clone: pip install -e .
 
 # wire the plugin (agents + skills) and the MCP server into your client
-rgit install claude-code        # Claude Code (via the official `claude` CLI)
-rgit install codex              # Codex / Gemini / opencode: symlinks the skills into ~/.agents/skills/
-rgit install --list             # all platforms; add --dry-run to preview, --uninstall to remove
+rgit install                    # auto-detects every agent client on this machine and wires them all
+rgit install claude-code        # or pick one explicitly (claude-code / codex / gemini / opencode / generic)
+rgit install --list             # list platforms; --uninstall to remove
 ```
 
 `codex`, `gemini`, and `opencode` share the `~/.agents/skills/` convention — the installer symlinks each skill there and prints the one-line MCP server entry to drop into that client's config. It also writes a managed research-git guidance block into the client's global guidance file when the platform has one (`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, or `~/.gemini/GEMINI.md`). On an interactive terminal you're asked how proactive capture should be — `default`, `manual-only`, or `none`; pass `--guidance <mode>` to choose non-interactively. Start a new agent session after install so the guidance is loaded. Prefer the manual route on Claude Code? `/plugin marketplace add StepzeroLab/research-git` then `/plugin install research-git@research-git`.
@@ -118,6 +116,14 @@ cd your-project
 rgit init                       # creates .rgit/ (the store) at the git root
 ```
 
+**Optional — capture on every commit.** `rgit install <platform>` wires the agent side only; it deliberately does **not** touch your git hooks. If you also want every `git commit` to stage its own diff as a pending proposal automatically, opt in with:
+
+```bash
+rgit install-hooks              # adds a post-commit hook (never clobbers an existing one)
+```
+
+Good fit: solo research repos where you want nothing to slip through, even when you forget to capture. Skip it if the repo already has its own post-commit hook (the installer refuses to touch foreign hooks, so nothing breaks — it just won't install), if your team prefers deliberate manual capture, or in CI/shared clones where commit-time side effects are unwelcome. Without hooks you lose nothing: bare `rgit capture` takes the last commit when the tree is clean, `rgit capture A..B` a whole span, and `rgit review` is the gate either way — hooks only stage proposals, they never approve anything. Remove with `rgit install-hooks --uninstall`.
+
 ### 3. Run a variation and capture the idea
 
 Launch your work through `rgit run` — it executes your command, freezes a reproducible artifact, records the run + any metrics, and stages what changed:
@@ -134,6 +140,8 @@ rgit review              # list proposals
 rgit review --approve <proposal_id> --name rerank-retrieval
 ```
 
+Committed before capturing? Just run `rgit capture` — on a clean tree it captures the last commit (and says which one); `rgit capture main..HEAD` takes a whole span. (With the optional post-commit hook installed, every commit stages itself automatically.)
+
 ### 4. Bring an idea back onto today's code
 
 Weeks later, after the agent has moved on:
@@ -198,7 +206,8 @@ The five-step loop above is the core. These show up as your store grows — run
 | Command | What it does |
 |---------|--------------|
 | `rgit watch` | free, deterministic background capture — stages raw material as you edit, so fleeting in-between states aren't lost |
-| `rgit install-hooks` | stage on every commit via a post-commit hook (won't touch an existing hook) |
+| `rgit capture [REV \| A..B]` | bare: auto-picks the working tree or, when clean, the last commit; pass a commit or an A..B range for precise control |
+| `rgit install-hooks` | opt-in: stage every commit's diff via a post-commit hook (not installed by `rgit install`; won't touch an existing hook) — see step 2 above |
 | `rgit run --from <capsule>` | run a recalled variant and link the new run as a `variant_of` the original |
 | `rgit compare <query>` | which variant won: ranked table, Δ vs baseline, ★ winner |
 | `rgit provenance <run_id>` | per-feature clean (capsule) vs agent-adapted (frozen) diff for a run |

research_git-0.0.4/src/rgit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.3"

{research_git-0.0.2 → research_git-0.0.4}/src/rgit/_plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "research-git",
   "description": "A memory system for the code you're exploring: capture each idea as a semantic Feature Capsule, recall it, and regenerate it onto today's codebase. Segmentation/regeneration run on natively-dispatched subagents (your subscription) — no pay-per-use API. MCP serves the graph read-only for sharing.",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "author": { "name": "Stepzero Lab" },
   "license": "MIT",
   "keywords": [

{research_git-0.0.2 → research_git-0.0.4}/src/rgit/_plugin/skills/rgit-capture/SKILL.md

@@ -26,9 +26,12 @@ Every `agents/<name>.md` reference below (`agents/capsule-segmenter.md`, `agents
 If the user just made changes and there is no open proposal yet, create one:
 
 ```
-rgit capture --trigger manual
+rgit capture                 # picks for you: uncommitted work, or the last commit when the tree is clean
+rgit capture main..HEAD      # a specific span of commits (any A..B range)
 ```
 
+The bare form auto-picks its source, so it works the same before or after a `git commit`; repeated captures of the same diff dedup into the existing proposal. If the repo has the post-commit hook installed (`rgit install-hooks`), each commit is captured automatically; don't capture the same commit twice.
+
 This runs the libcst symbol mapping + the free heuristic, producing one or more open proposals with a raw diff and a crude candidate. Proposals also appear automatically from `rgit run`, the post-commit hook, and the `rgit watch` daemon.
 
 ### 2. Read the pending captures

{research_git-0.0.2 → research_git-0.0.4}/src/rgit/agent_guidance.py

@@ -45,14 +45,22 @@ def render_global_block(mode: str = "default") -> str:
         "- Do not write repo preferences for one-off session instructions.\n"
         "\n"
         "Use:\n"
-        "- After meaningful code/research changes, consider "
-        "`rgit capture --trigger manual` and the `rgit-capture` skill.\n"
+        "- After meaningful code/research changes, run `rgit capture` — it "
+        "captures uncommitted work, or the last commit when the tree is "
+        "clean, so committing first is fine. Then use the `rgit-capture` "
+        "skill to segment.\n"
+        "- For a specific span of commits: `rgit capture main..HEAD` (any "
+        "A..B range works).\n"
+        "- If a post-commit hook is installed (`rgit install-hooks`), commits "
+        "are captured automatically; do not capture the same commit again.\n"
+        "- Skip mechanical formatting, dependency churn, generated files, or "
+        "changes with no reusable research/code idea.\n"
         "- For recall/resurrection requests, use the `rgit-recall` skill.\n"
         "- If `.rgit/` is missing in a git repo: when operating autonomously "
-        "(no human to ask), bootstrap the store with `rgit capture --init "
-        "--trigger manual` (store only — never install hooks unless asked); in "
-        "an interactive session, tell the user to run `rgit init` rather than "
-        "initializing silently.\n"
+        "(no human to ask), bootstrap the store with `rgit capture --init` "
+        "(store only — never install hooks unless asked); in an interactive "
+        "session, tell the user to run `rgit init` rather than initializing "
+        "silently.\n"
         "- In final feedback, mention any capsules created, approved, applied, "
         "or skipped, plus important graph relations.\n"
         f"{END}\n"

research_git-0.0.4/src/rgit/astmap.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Callable, Optional
+
+import libcst as cst
+from libcst.metadata import MetadataWrapper, PositionProvider
+
+from .gitutil import parse_git_diff_header, read_worktree_python
+
+_HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", re.M)
+
+
+def _changed_line_ranges(diff: str) -> dict[str, list[tuple[int, int]]]:
+    """file -> list of (start, end) ranges of *actually changed* new-side lines.
+
+    Only added lines — plus the new-side anchor of a deletion — count; unified-diff
+    context lines are walked to advance the new-side line counter but never recorded.
+    Using the whole hunk span (header length) would treat untouched neighbouring
+    symbols that merely appear as context as changed (issue #10).
+    """
+    result: dict[str, list[tuple[int, int]]] = {}
+    current: Optional[str] = None
+    in_hunk = False
+    new_line = 0
+    hunk_start = 0
+    for line in diff.splitlines():
+        matched, path = parse_git_diff_header(line, "+++")
+        if matched:
+            current = path
+            in_hunk = False
+            if current is not None:
+                result.setdefault(current, [])
+            continue
+        h = _HUNK.match(line)
+        if h:
+            new_line = hunk_start = int(h.group(1))
+            in_hunk = current is not None
+            continue
+        if not in_hunk:
+            continue
+        if not line:                      # empty context line
+            new_line += 1
+            continue
+        tag = line[0]
+        if tag == "+":                    # added line -> genuinely changed
+            result[current].append((new_line, new_line))
+            new_line += 1
+        elif tag == "-":                  # deletion -> anchor to the surviving line
+            anchor = new_line - 1 if new_line > hunk_start else new_line
+            result[current].append((anchor, anchor))
+        elif tag == " ":                  # context -> advance, do not record
+            new_line += 1
+        elif tag == "\\":                 # ""
+            continue
+        else:                             # non-body line ends the hunk (e.g. next `diff --git`)
+            in_hunk = False
+    return result
+
+
+class _SymbolFinder(cst.CSTVisitor):
+    METADATA_DEPENDENCIES = (PositionProvider,)
+
+    def __init__(self, ranges: list[tuple[int, int]]):
+        self.ranges = ranges
+        self.found: set[str] = set()
+
+    def _overlaps(self, node) -> bool:
+        pos = self.get_metadata(PositionProvider, node)
+        for s, e in self.ranges:
+            if pos.start.line <= e and pos.end.line >= s:
+                return True
+        return False
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> None:
+        if self._overlaps(node):
+            self.found.add(node.name.value)
+
+    def visit_ClassDef(self, node: cst.ClassDef) -> None:
+        if self._overlaps(node):
+            self.found.add(node.name.value)
+
+
+def changed_symbols(diff: str, repo: Path,
+                    read_source: Optional[Callable[[str], Optional[str]]] = None,
+                    ) -> list[dict]:
+    """[{file, symbol}] for each top-level def/class overlapping a diff hunk.
+
+    `read_source(file)` supplies the new-side source text (None skips the
+    file); the default reads the working tree. Committed-diff capture passes a
+    reader pinned to the captured commit, so symbol mapping cannot drift when
+    the worktree has moved past — or never matched — the diff being segmented
+    (e.g. a partially staged commit).
+    """
+    if read_source is None:
+        read_source = lambda file: read_worktree_python(repo, file)  # noqa: E731
+    out: list[dict] = []
+    for file, ranges in _changed_line_ranges(diff).items():
+        if not ranges:
+            continue
+        text = read_source(file)
+        if text is None:
+            continue
+        try:
+            wrapper = MetadataWrapper(cst.parse_module(text))
+        except (cst.ParserSyntaxError, UnicodeDecodeError):
+            continue
+        finder = _SymbolFinder(ranges)
+        wrapper.visit(finder)
+        for sym in sorted(finder.found):
+            out.append({"file": file, "symbol": sym})
+    return out
+
+
+def read_symbol_source(repo: Path, file: str, symbol: str) -> Optional[str]:
+    """Current source text of a top-level def/class, or None if absent."""
+    text = read_worktree_python(repo, file)
+    if text is None:
+        return None
+    try:
+        module = cst.parse_module(text)
+    except (cst.ParserSyntaxError, UnicodeDecodeError):
+        return None
+    for stmt in module.body:
+        if isinstance(stmt, (cst.FunctionDef, cst.ClassDef)) and stmt.name.value == symbol:
+            return module.code_for_node(stmt)
+    return None
+
+
+def symbol_at_line(repo: Path, file: str, line: int) -> Optional[str]:
+    """Name of the top-level def/class enclosing `line` (1-based), or None."""
+    text = read_worktree_python(repo, file)
+    if text is None:
+        return None
+    try:
+        wrapper = MetadataWrapper(cst.parse_module(text))
+    except (cst.ParserSyntaxError, UnicodeDecodeError):
+        return None
+    finder = _SymbolFinder([(line, line)])
+    wrapper.visit(finder)
+    found = sorted(finder.found)
+    return found[0] if found else None