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

{research_git-0.0.3/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.3
+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.3 → 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.3 → research_git-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "research-git"
-version = "0.0.3"
+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.3 → 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.3
+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.3 → 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.3 → 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.3 → research_git-0.0.4}/src/rgit/astmap.py

@@ -1,34 +1,16 @@
 from __future__ import annotations
 import re
 from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional
 
 import libcst as cst
 from libcst.metadata import MetadataWrapper, PositionProvider
 
-from .gitutil import _within, parse_git_diff_header
+from .gitutil import parse_git_diff_header, read_worktree_python
 
 _HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", re.M)
 
 
-def _read_python_source(path: Path) -> str:
-    """Read a .py file for parsing. ``utf-8-sig`` strips a UTF-8 BOM (common on
-    Windows-authored files) that would otherwise make libcst miss the first
-    symbol — and it also reads plain UTF-8 unchanged."""
-    return path.read_text(encoding="utf-8-sig")
-
-
-def _python_source_path(repo: Path, file: str) -> Optional[Path]:
-    """Repo-contained regular Python file, without following external symlinks."""
-    path = repo / file
-    if path.suffix != ".py" or not _within(repo, path):
-        return None
-    try:
-        return path if path.is_file() else None
-    except OSError:
-        return None
-
-
 def _changed_line_ranges(diff: str) -> dict[str, list[tuple[int, int]]]:
     """file -> list of (start, end) ranges of *actually changed* new-side lines.
 
@@ -99,15 +81,28 @@ class _SymbolFinder(cst.CSTVisitor):
             self.found.add(node.name.value)
 
 
-def changed_symbols(diff: str, repo: Path) -> list[dict]:
-    """[{file, symbol}] for each top-level def/class overlapping a diff hunk."""
+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():
-        path = _python_source_path(repo, file)
-        if path is None or not ranges:
+        if not ranges:
+            continue
+        text = read_source(file)
+        if text is None:
             continue
         try:
-            wrapper = MetadataWrapper(cst.parse_module(_read_python_source(path)))
+            wrapper = MetadataWrapper(cst.parse_module(text))
         except (cst.ParserSyntaxError, UnicodeDecodeError):
             continue
         finder = _SymbolFinder(ranges)
@@ -119,11 +114,11 @@ def changed_symbols(diff: str, repo: Path) -> list[dict]:
 
 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."""
-    path = _python_source_path(repo, file)
-    if path is None:
+    text = read_worktree_python(repo, file)
+    if text is None:
         return None
     try:
-        module = cst.parse_module(_read_python_source(path))
+        module = cst.parse_module(text)
     except (cst.ParserSyntaxError, UnicodeDecodeError):
         return None
     for stmt in module.body:
@@ -134,11 +129,11 @@ def read_symbol_source(repo: Path, file: str, symbol: str) -> Optional[str]:
 
 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."""
-    path = _python_source_path(repo, file)
-    if path is None:
+    text = read_worktree_python(repo, file)
+    if text is None:
         return None
     try:
-        wrapper = MetadataWrapper(cst.parse_module(_read_python_source(path)))
+        wrapper = MetadataWrapper(cst.parse_module(text))
     except (cst.ParserSyntaxError, UnicodeDecodeError):
         return None
     finder = _SymbolFinder([(line, line)])