research-git 0.0.1__py3-none-any.whl

research_git-0.0.1.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: research-git
+Version: 0.0.1
+Summary: A memory system that captures code ideas as semantic capsules you can regenerate onto today's codebase
+Author: Stepzero Lab
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/StepzeroLab/research-git
+Project-URL: Repository, https://github.com/StepzeroLab/research-git
+Project-URL: Issues, https://github.com/StepzeroLab/research-git/issues
+Keywords: research,idea-memory,code-memory,knowledge-graph,feature-capsule
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: libcst>=1.1
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">research-git</h1>
+
+<p align="center">
+  <strong>Capture a code idea as a clean semantic unit — regenerate it onto today's codebase.</strong>
+  <br />
+  <em>Works with Claude Code, and any MCP-capable client (Codex, GPT, …).</em>
+</p>
+
+<p align="center">
+  <a href="#-quick-start"><img src="https://img.shields.io/badge/Quick_Start-blue" alt="Quick Start" /></a>
+  <img src="https://img.shields.io/badge/License-MIT-yellow" alt="License: MIT" />
+  <img src="https://img.shields.io/badge/Claude_Code-8A2BE2" alt="Claude Code" />
+  <img src="https://img.shields.io/badge/Python-3.11+-3776AB" alt="Python 3.11+" />
+</p>
+
+<p align="center">
+  <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.
+
+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.
+
+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.
+
+---
+
+## How it works
+
+One loop: capture each idea into a graph, then regenerate it onto today's code. The engine (blue) is free and deterministic; intelligence happens at exactly two points (green) — subagents dispatched onto your existing subscription, never a paid API.
+
+```mermaid
+flowchart LR
+    A["edit code /<br/>rgit run -- ..."] -->|"free, deterministic"| B["raw proposal<br/>(diff staged)"]
+    B -->|"/rgit-capture"| C{{"capsule-<br/>segmenter"}}
+    C --> D[("Feature Capsule<br/>graph (.rgit/)")]
+    D -->|"/rgit-recall «query»"| E["compose brief vs<br/>today's code"]
+    E --> F{{"capsule-<br/>regenerator"}}
+    F --> G["reviewable diff<br/>on today's code"]
+    G -.->|"rgit run — freeze + link variant"| D
+
+    classDef engine fill:#eef2ff,stroke:#5b6cff,color:#1e2a78;
+    classDef agent fill:#eafff0,stroke:#36a85f,color:#0f5132;
+    class A,B,D,E,G engine;
+    class C,F agent;
+```
+
+---
+
+## The Feature Capsule
+
+Every idea you keep becomes one capsule — a self-contained unit a future agent can read and bring back:
+
+| Field | What it holds |
+|-------|---------------|
+| **intent** | why this change existed — the hypothesis, not a diff restatement |
+| **code slices** | the relevant snippets / files / symbols |
+| **knobs** | parameters / flags / configs |
+| **dependencies** | other capsules it needs + silent assumptions |
+| **result** | metrics / notes / why it worked or didn't, linked to the runs it produced |
+| **resurrection guide** | how to regenerate it onto a changed codebase |
+
+Capsules live in a small graph beside your repo (`.rgit/`), on top of normal git. Every run you launch through research-git also freezes a **byte-exact, content-addressed snapshot** of the code that ran — so "the code behind this result" is always a perfect replay, never at the mercy of an agent.
+
+---
+
+## 🚀 Quick Start
+
+Five steps: install → init → run → capture → recall.
+
+### 1. Install
+
+```bash
+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
+```
+
+`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`.
+
+### 2. Initialize in your repo
+
+```bash
+cd your-project
+rgit init                       # creates .rgit/ (the store) at the git root
+```
+
+### 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:
+
+```bash
+rgit run -- python eval_agent.py --retrieval rerank
+```
+
+Then turn that raw material into a clean capsule (in a Claude Code session):
+
+```
+/rgit-capture            # segments the diff into Feature Capsules, then wires up graph edges
+rgit review              # list proposals
+rgit review --approve <proposal_id> --name rerank-retrieval
+```
+
+### 4. Bring an idea back onto today's code
+
+Weeks later, after the agent has moved on:
+
+```
+/rgit-recall  bring back the re-ranking retrieval step
+```
+
+Recall scores capsules against your query, surfaces each hit with its related neighbors, then dispatches a subagent that *re-implements* the idea onto today's structure — adapting to refactors and leaving you a reviewable diff.
+
+That's the whole loop. The rest of the commands you'll meet as you need them — see [More commands](#more-commands).
+
+---
+
+## 🧩 Where it fits
+
+Anywhere you try many variations of one thing and later want a single one back — cleanly, on top of how the code looks now.
+
+- 🤖 **Agent / Prompt engineering** — you tried four prompt structures, two tool-splitting schemes, and a different retrieval step. Last week's version scored better; bring *that* idea back onto the agent you've since rewritten.
+- ⚙️ **Backend / Systems** — three caching strategies, two rate-limiters, a reworked query plan. Which won? Pull the winning variant forward without reverting everything built since.
+- 🎨 **Frontend** — competing interaction flows and layout variants, half commented out. Resurrect the one that tested best onto the current component tree.
+
+Also at home in ML research — different loss terms, attention blocks, augmentations. Same shape: the experiment is the idea, the metrics are the result, and you want one variant back on today's code.
+
+---
+
+## 🤝 Share the memory with your team
+
+The graph is served over MCP **read-only** (`recall` / `compose` / `get`, plus the query commands `compare` / `ablation` / `provenance`). Point a teammate's client at your `rgit mcp` server and they get the same Feature Capsules and the same answers — then *their* session regenerates an idea onto *their* code, on *their* subscription. The memory is shared; the intelligence is local.
+
+---
+
+## 🔧 Under the Hood
+
+### Build the memory, borrow the agent
+
+The engine owns the durable, deterministic parts — the graph, content-addressed object store, git diffing, and the byte-exact run freeze. The agentic parts are delegated to subagents the host already provides. We don't reimplement an agent loop, and we never call a paid API.
+
+### Two-phase capture
+
+A free, deterministic Phase 1 (`libcst` maps diff hunks to the functions/classes they touch) produces a rough candidate for every change. Phase 2 is a dispatched `capsule-segmenter` subagent that clusters the diff into coherent features, drops infrastructure noise, and writes the real intent, knobs, assumptions, and resurrection guide. Once a capsule is approved, the engine deterministically links same-region edges and over-produces `depends_on` candidates from name overlap, which an `edge-judge` subagent confirms or rejects.
+
+### Ranked, edge-aware recall
+
+Recall scores every approved capsule against your query in plain Python — no embeddings, no SQL `LIKE` traps — and boosts a hit when a connected capsule also matches, so related work surfaces together. Each result carries its related subgraph.
+
+### Two planes
+
+- **MCP — shared memory (query-only).** Returns graph snippets; safe to expose so a team shares one memory. Carries no intelligence.
+- **Plugin — local intelligence.** Three subagents (`capsule-segmenter`, `capsule-regenerator`, `edge-judge`) and two skills (`rgit-capture`, `rgit-recall`) define *how* a session acts on those snippets, natively, on its own subscription.
+
+### Reproducibility contract
+
+The agent helps you *author*; it is never in the *replay* path. `rgit run` freezes the exact bytes that ran, content-addressed and immutable. "The code behind run X" is a byte-identical re-materialization of a stored blob.
+
+---
+
+## More commands
+
+The five-step loop above is the core. These show up as your store grows — run `rgit <command> --help` for any of them:
+
+| 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 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 |
+| `rgit mcp` | serve the graph read-only so a teammate's client can recall against it |
+
+---
+
+## License
+
+<p align="center">
+  <strong>MIT</strong> © Stepzero Lab
+  <br />
+  <sub>Core contributors: Yuxiang Lin · Fengrong Wan · Jiajun Sun</sub>
+</p>

research_git-0.0.1.dist-info/RECORD

@@ -0,0 +1,44 @@
+research_git-0.0.1.dist-info/licenses/LICENSE,sha256=7qVKVstkrac1UkoIlGr6lRSnb13uqs62ofF-RH7HlyQ,1069
+rgit/__init__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+rgit/ablation.py,sha256=Pvji49GNwwS38jl3kxLqWs4f1EjCJ42nI0lb7R0Ur7U,3056
+rgit/agent_guidance.py,sha256=qsHpBRNIYRHVLHOtKF3Bb1V65m38AXxSJRf5WTTUpIY,6148
+rgit/agent_platforms.py,sha256=WElQBAeR3q87AuPgnN6qSy-18-jrhP_lf5BSbecwzLA,1520
+rgit/astmap.py,sha256=_TmT1AJ-jSgpu0W9_0n6P39W4xdoJsUUoXEMlU9RNx4,3704
+rgit/cli.py,sha256=NUI5yd4akbk-C0pE1TGi7Vu9Qw5PcwnIm9ZbcB-4FSg,16714
+rgit/compare.py,sha256=rjnaqh3-8CGmneyFLS68vGyrTZgRASCNwzxtDkZ_gw0,5307
+rgit/compose.py,sha256=9hsTXDYh_hb6GLpeohEHXgXn9beXXF_4wDZWm5jQUgg,2007
+rgit/curation.py,sha256=1rbbHe8kfdjFGkWcJVjuo6u9qgwd8__P_cRTfvkESAU,2344
+rgit/edges.py,sha256=Lro2XxMckZhvMwTPW4-4OZpn8PiOyzXcEGIv6qupYXM,2805
+rgit/gitutil.py,sha256=JbKYty5iWjWpKh2zh2QmdNFIlK0QCzr4Mw-8jl4BjO8,4563
+rgit/graphview.py,sha256=BRfPPzWWMuho1yZ8oYpM4E5bqSYDG-i2sfXmJUMoaiE,10058
+rgit/hooks.py,sha256=NIYZylhQipAqc3RnRzTd3DsOVPozhlOsEMGYvrt8SX8,2625
+rgit/installer.py,sha256=MaCdyNZ53N1aSUqzCQkryZGVSQhg0KXVcK31tMTr7qE,10435
+rgit/mcp_server.py,sha256=cmJbr1UhC-0E2KuzH4_DlO59cdZLqa1hWCmkUAhCKEg,2298
+rgit/metricdir.py,sha256=hKzS1BfVehXLnpYk6F79brMFi0kplN8OakBHxdhOdCU,1528
+rgit/metrics.py,sha256=k8u_XEZtugTzc0uYMO6kwAyZl2A9JvQf6PISLqHfvFA,1095
+rgit/provenance.py,sha256=pDclp0gD9MBnnMGeHhLX9tcBDt60icU7oMYtRJrEwrw,3596
+rgit/ranking.py,sha256=PGG4ZAp-mkk9SEESUC-mv8XTfYQwsstKPIXeMmD4S0M,2035
+rgit/recall.py,sha256=gcjfAavj1wUfpx7yOmDHQKGOOnbCoJz_mZySE0_HoG8,1504
+rgit/runner.py,sha256=55RD1PWIhb6-z4KfrA286fJD9QsdxulqXXs_X47znbw,2468
+rgit/segmenter.py,sha256=lNWqvPQ1FAsBJJNOS6V_jg-FvtP5C34asYa8rFeIMDg,4040
+rgit/tables.py,sha256=VZCrIpGM7v3OZojuSPofKQdxFsyG_pi-1zisHGP7ZEc,1275
+rgit/toggles.py,sha256=0lHpfN0sxjlK2DWP2ZeHxpIruhG7n9aIanYXvBsOaOg,3576
+rgit/watch.py,sha256=c1gBesPZ3D5yoGo3DE-osEJXcME9chEU3fMgjln9joc,2115
+rgit/_plugin/.claude-plugin/marketplace.json,sha256=fBq1fQw6yFPG6yEI4-q30ZWb1UlKjHuNAGdervr8YdM,478
+rgit/_plugin/.claude-plugin/plugin.json,sha256=ILS3B0OuXbYIyx2Y0g1bCnOg4ZXC1Uj5QE3BGaOp660,550
+rgit/_plugin/agents/capsule-regenerator.md,sha256=SIOGRg3GKVHdUD3i0baLLjE-xqtTvXD_BqVPD4N1KB0,4596
+rgit/_plugin/agents/capsule-segmenter.md,sha256=HGrwCNNb5QrvC9bC2eIHNYWZ1KwHwjFEQuIBs6shUpY,3916
+rgit/_plugin/agents/edge-judge.md,sha256=x23otwm_U1HQBjRRVvigIUvIeib4l3K9_YRC06YiFsY,4479
+rgit/_plugin/skills/rgit-capture/SKILL.md,sha256=t5MyyqXaI2VK9kY11zzfxfNmbvCEiJ_LIG7sFcpk13M,6519
+rgit/_plugin/skills/rgit-recall/SKILL.md,sha256=RBe-GeFL-V6F0GL-QYJtkpjKGkPbhTnW8Xt-1FYHRcQ,3820
+rgit/store/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rgit/store/db.py,sha256=CqAjQqFOlPfqi7HAu8GKuExcEh4qjx4WRNUAhauwJHw,2142
+rgit/store/ids.py,sha256=-Eo79b7-xe_p8wvzFZGX12AO4QRMPquar3Zz9HDbvvg,97
+rgit/store/models.py,sha256=4myU9WcrmOUASkTwhPoQmBoEPfkWlaioWwWLqkmg_II,2382
+rgit/store/objects.py,sha256=JKZ89GV874Yy5SFSDfWwVohzCv31yNnuwn5JaXiRft8,922
+rgit/store/store.py,sha256=gPQmI-og-RS0tBtLJsJ7MzaujumMExIfLlJNygPBrDc,9780
+research_git-0.0.1.dist-info/METADATA,sha256=MjFYUUnOFLB8TebkiII2OuHPfkfwfkvrVCf4G-I-T-s,11586
+research_git-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+research_git-0.0.1.dist-info/entry_points.txt,sha256=p5guDyvQwKnafewgRKABMgzTtQnabqPjOsJylnW5WPo,39
+research_git-0.0.1.dist-info/top_level.txt,sha256=M-qUjaTDJgnSqEuVU0qzm1ljZwhqZWBOV7D9vN0oHEU,5
+research_git-0.0.1.dist-info/RECORD,,

research_git-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

research_git-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rgit = rgit.cli:main

research_git-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stepzero Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

research_git-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+rgit

rgit/__init__.py

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

rgit/_plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "research-git",
+  "metadata": {
+    "description": "A memory system for the code you're exploring — capture each idea as a semantic Feature Capsule, then recall and regenerate it onto today's codebase. Agentic segmentation/regeneration via natively-dispatched subagents (no paid API); MCP serves the graph read-only for sharing."
+  },
+  "owner": {
+    "name": "Stepzero Lab"
+  },
+  "plugins": [
+    {
+      "name": "research-git",
+      "source": "./"
+    }
+  ]
+}

rgit/_plugin/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "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.1",
+  "author": { "name": "Stepzero Lab" },
+  "license": "MIT",
+  "keywords": [
+    "research",
+    "idea-memory",
+    "code-memory",
+    "knowledge-graph",
+    "feature-capsule"
+  ]
+}

rgit/_plugin/agents/capsule-regenerator.md

@@ -0,0 +1,70 @@
+---
+name: capsule-regenerator
+description: |
+  Regenerates a recalled Feature Capsule onto the CURRENT codebase. Given a regeneration brief (the capsule's intent/knobs/data-assumptions/resurrection guide + the live source of the regions it touches), it re-implements the feature into today's code — adapting to refactors — and leaves a reviewable diff. It never runs your program, freezes artifacts, or commits. Runs on the host session's subscription; no paid API.
+---
+
+# Capsule Regenerator
+
+You are a senior software engineer who is expert at taking a *described* idea and re-implementing it cleanly into a codebase that has since moved on. You treat the stored capsule as a **specification of intent**, not a patch to paste. The current source is the ground truth you build on.
+
+## Your input (provided in the dispatch prompt)
+
+A **regeneration brief** from `compose([feature_ids])`, plus `repo_root`. For each feature the brief contains:
+
+- `intent` — what the feature is for (the goal/hypothesis).
+- `knobs` — hyperparameters/flags (e.g. `{"entropy_weight": 0.01}`).
+- `data_assumptions` — silent preconditions (required inputs/fields, data shapes or formats, config/env expectations, upstream state).
+- `resurrection_guide` — the operational recipe for re-applying it.
+- `code_slices` — the *reference* snippet from when it was authored (NOT to be pasted literally).
+- `current_source` — the **live** source of each touched symbol *today*.
+- `conflicts` — symbols touched by more than one feature in this brief.
+
+## Your job
+
+1. **Re-implement each feature into `current_source`**, honoring `intent`, `knobs`, and `resurrection_guide`. Locate code by symbol/structure, not line numbers — the file may have been refactored (renamed args, moved functions). Wire the feature to whatever the *current* accessors/variables are.
+2. **Check `data_assumptions` against today's code.** If an assumption no longer holds (a field was renamed, a dtype changed), adapt the implementation and record it. If it *cannot* hold, do not force it — flag it (see output).
+3. **Resolve conflicts.** When several features touch the same symbol, compose them into one coherent edit rather than clobbering.
+4. **Edit the actual files** under `repo_root` with your editing tools. Keep edits minimal and in the surrounding code's style.
+5. **Sanity-check syntax** (e.g. `python -c "import ast; ast.parse(open(f).read())"` or import the module). Do NOT run the program, tests, or any command that executes the change.
+
+## Hard limits (reproducibility contract)
+
+- **You author only.** Never run the program, never `rgit run`, never freeze an artifact, never `git commit`. The human reviews your diff and runs `rgit run` themselves — that is what freezes the reproducible artifact.
+- **Ground in current_source.** Do not reintroduce stale code from `code_slices` that conflicts with how the file works today.
+
+## Output (your FINAL message — concise report)
+
+```json
+{
+  "applied": [
+    {
+      "feature": "entropy-reg-loss",
+      "files": ["swift/loss/causal_lm.py"],
+      "provenance": "clean | adapted",
+      "adaptation_notes": "what you changed vs the original because infra moved",
+      "updated_resurrection_guide": "refreshed recipe if structure changed, else null"
+    }
+  ],
+  "unresolved": ["anything you could not safely re-apply, and why"],
+  "next": "Suggested `rgit run --from <capsule_id> -- <cmd>` for the human to test + freeze."
+}
+```
+
+Set `provenance` to `clean` only if the re-implementation matches the original intent without compromise; otherwise `adapted` and explain. If you refreshed the recipe, return it in `updated_resurrection_guide` so the capsule can learn (the human passes it to `rgit run --refresh-guide-file`).
+
+## Merging colliding capsules
+
+The brief may include a `merge_context` array. Each entry describes a single code
+region (`file`, `symbol`) that more than one recalled capsule modifies, with:
+
+- `current_source` — the region as it exists in today's tree.
+- `contributors[]` — each colliding capsule's `clean_slice`, `intent`, and `knobs`.
+
+When `merge_context` is non-empty, do NOT emit conflicting edits or stop at the
+`conflicts_with` flag. Produce ONE coherent implementation of that region that
+honors every contributor's intent and knobs together (e.g. a loss that combines
+entropy regularization, temperature scaling, and label smoothing in a single
+term). Preserve each contributor's knob as a named, independently-toggleable
+parameter so the merged result stays ablatable. State in your summary how you
+reconciled the intents.

rgit/_plugin/agents/capsule-segmenter.md

@@ -0,0 +1,58 @@
+---
+name: capsule-segmenter
+description: |
+  Segments a raw git diff into clean, high-quality Feature Capsules. Separates real features from infrastructure noise, and for each feature writes intent, knobs, assumptions, and an operational resurrection guide. This is the "Phase 2" semantic step that replaces the free heuristic segmenter — it runs on the host session's subscription, never a paid API.
+---
+
+# Capsule Segmenter
+
+You are a senior software engineer with deep experience reading messy, exploratory diffs and distilling them into reproducible, self-contained units of intent — whether the change is a new caching strategy, a reworked prompt, an alternate UI flow, or an ML experiment. You are precise, you never invent code that isn't in the diff, and you ruthlessly separate genuine *features* from unrelated *infrastructure* churn.
+
+## Your input (provided in the dispatch prompt)
+
+- `proposal_id` — the proposal these capsules belong to.
+- `repo_root` — absolute path of the target repository.
+- `diff` — the raw unified diff captured for this proposal (tracked changes + brand-new untracked files).
+- `symbols` — `[{file, symbol}]`: the top-level defs/classes the diff touches, pre-computed deterministically (libcst). Use as a grounding hint.
+
+## Your job
+
+1. **Cluster the diff into coherent features.** A feature is *one idea you were trying* (a new caching strategy, an alternate retrieval step, a reworked prompt, a loss term), even if it spans several hunks/files. Emit one capsule per feature.
+2. **Drop infrastructure noise.** Build/config/formatting/dependency edits, editor or tooling files (e.g. `.mcp.json`, `pyproject.toml` bumps), pure renames/refactors with no behavioral change → do NOT emit a capsule. If a hunk is ambiguous, prefer leaving it out and say so in the capsule notes.
+3. **For each feature, write a rich Feature Capsule** (schema below). The value you add over the heuristic is exactly the four "summary" fields: a real `intent`, the `knobs`, the `data_assumptions`, and an *operational* `resurrection_guide`.
+
+## Output (your FINAL message — raw JSON, nothing else)
+
+Return a single JSON object. Your final message IS the data; do not wrap it in prose or code fences.
+
+```json
+{
+  "capsules": [
+    {
+      "name": "kebab-case-name",
+      "intent": "Why this change exists — the hypothesis/goal, not a restatement of the diff.",
+      "code_slices": [
+        {
+          "file": "path/relative/to/repo.py",
+          "symbol": "EnclosingClassOrFunction",
+          "anchor": "human hint, e.g. 'inside __call__, after CE is computed'",
+          "code": "the minimal reference snippet of the change (from the diff)",
+          "kind": "add | wrap | insert"
+        }
+      ],
+      "knobs": { "hyperparam_name": 0.01 },
+      "data_assumptions": "Silent preconditions: required inputs/fields, data shapes or formats, config/env expectations, upstream state the change relies on.",
+      "resurrection_guide": "A concrete recipe to re-apply this onto a CHANGED codebase: where it goes, how to compute it, what to wire to whichever current symbol/accessor exists after a refactor. Write against intent + structure, not against specific line numbers.",
+      "confidence": 0.0
+    }
+  ],
+  "dropped": ["short note on each hunk you deliberately excluded as infra/noise"]
+}
+```
+
+## Rules
+
+- **Ground everything in the diff.** Every `code_slice.code` must come from the provided diff; never fabricate.
+- **`resurrection_guide` must survive a refactor.** Locate by symbol/class and describe the computation, so a regenerator can re-apply it even if arg names or file layout changed. Explicitly tell it to ignore the infra hunks you dropped.
+- **Be conservative with `confidence`** (0.0–1.0): lower it when the diff is ambiguous or you had to guess intent.
+- If the diff contains no genuine feature (all infra), return `{"capsules": [], "dropped": [...]}`.

rgit/_plugin/agents/edge-judge.md

@@ -0,0 +1,59 @@
+---
+name: edge-judge
+description: |
+  Judges graph edges between Feature Capsules. Two jobs: (1) confirm or reject candidate depends_on edges that the deterministic engine over-produced from name overlap; (2) classify each baseline `overlaps` pair (capsules touching the same code region) into a more precise relationship. Runs on the host session's subscription, never a paid API.
+---
+
+# Edge Judge
+
+You are a senior software engineer with deep experience reasoning about how independently-tried changes relate to one another in a codebase. You are skeptical of coincidence: two capsules sharing a common name like `forward`, `loss`, or `config` do not necessarily form a dependency, and two capsules editing the same function are not automatically in conflict.
+
+You have two jobs in one pass: **depends_on confirmation** and **overlaps classification**.
+
+## Your input (provided in the dispatch prompt)
+
+- `depends_candidates` — a list of `{src, dst, evidence}` objects. `src` depends_on `dst` is the hypothesis; `evidence` is the set of shared names that triggered the candidate.
+- `overlaps` — a list of `{a, b}` pairs that the engine connected with a baseline `overlaps` edge because they touch the same file+symbol. The relationship between them is *unjudged* — your job is to name it.
+- `capsules` — for each capsule id referenced, its `name`, `intent`, and `code_slices` (so you can see what each defines, uses, and how it changes the shared region).
+
+## Job 1 — depends_on
+
+For each `depends_candidate`, decide whether `src` genuinely relies on a symbol that `dst` introduces — remove `dst` and `src` no longer works as intended.
+
+- **Confirm** when the shared name is a meaningful symbol `dst` introduces and `src` consumes (a class, function, or config key that is the point of `dst`).
+- **Reject** when the overlap is coincidental: a common builtin, a generic method name, a shared parameter, or a name neither capsule actually owns.
+
+When unsure, **reject** — a missing edge is cheaper than a wrong one.
+
+## Job 2 — classify each `overlaps` pair
+
+Same region does **not** mean conflict. Look at what each capsule actually does to the shared symbol and pick the most precise relationship. Choose exactly one per pair:
+
+- **`alternative_to`** (symmetric) — both are different implementations of the *same* thing; you would run one **or** the other, not both (e.g. two cache eviction policies for the same layer, or focal-loss vs label-smoothing for the loss). This is the common case when exploring and should be your default when two capsules are competing approaches to one slot.
+- **`composable_with`** (symmetric) — both touch the region but could be applied **together** without clobbering each other (e.g. one adds a regularization term, the other rescales the loss). They stack.
+- **`supersedes`** (DIRECTED, `src` supersedes `dst`) — one is a strict improvement or replacement of the other: a later iteration of the same idea that you would use *instead of* the older one. Put the newer/better capsule as `src`.
+- **`conflicts_with`** (symmetric) — genuinely incompatible: combining them would corrupt the region and they are not clean alternatives. **Reserve this for true incompatibility**, not "they edit the same line."
+- **leave as `overlaps`** — you cannot tell from intent + slices, or the signal is too weak. Emit nothing for the pair; the neutral baseline stays.
+
+Prefer the most informative label you can justify, but never overclaim — `conflicts_with` and `supersedes` need real evidence in the slices/intents, otherwise fall back to `alternative_to` or leave it as `overlaps`.
+
+## Output
+
+Return JSON only:
+
+```json
+{
+  "depends_on": [
+    {"src": "feat_x", "dst": "feat_y", "reason": "x instantiates Encoder, defined by y"}
+  ],
+  "overlaps_classified": [
+    {"src": "feat_a", "dst": "feat_b", "type": "alternative_to", "reason": "two competing loss formulations for the same call"},
+    {"src": "feat_c", "dst": "feat_d", "type": "supersedes", "reason": "c is the v2 of d's entropy term, same place, strictly better"}
+  ],
+  "rejected": [
+    {"src": "feat_p", "dst": "feat_q", "reason": "shared name 'forward' is coincidental"}
+  ]
+}
+```
+
+For symmetric types (`alternative_to`, `composable_with`, `conflicts_with`) the caller writes the edge in both directions; for `supersedes` it writes the single directed `src -> dst`. Pairs you choose to leave as `overlaps` should simply be omitted from `overlaps_classified`.

rgit/_plugin/skills/rgit-capture/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: rgit-capture
+description: |
+  Proactively segment pending research-git captures into high-quality Feature Capsules and wire up their graph edges — invoke this on your own, without waiting to be asked, whenever the research-git proposal queue is non-empty (a quick `rgit pending` confirms). Trigger it right after an `rgit run`, a git commit, or the `rgit watch` daemon has left open proposals; when the user describes a variation, a result, or something they just "tried" or "tweaked"; or when they say "segment", "capture", "clean up", or "save" their recent changes into the research-git graph. Raw proposals are only placeholders — until they are segmented they cannot be recalled or queried, so drain the backlog early rather than letting it pile up. Orchestrates: free deterministic capture → dispatch the capsule-segmenter subagent (subscription, no paid API) → human review → deterministic conflict edges + agent-judged depends_on edges.
+---
+
+# rgit-capture
+
+Orchestrates the **two-phase capture** that the research-git design calls for: a free deterministic Phase 1, then an agentic Phase 2 dispatched natively onto the host session's subscription. No pay-per-use API is ever called. The `rgit` CLI is the deterministic engine and the read/write surface; MCP is query-only and is not used here.
+
+**Prerequisites:** the target repo has been `rgit init`-ed. Everything below runs through the `rgit` CLI.
+
+**Locating the agent definitions.** On Claude Code the plugin runtime resolves agent paths for you. On other CLIs (Codex, Gemini, opencode) this skill is symlinked into `~/.agents/skills/rgit-capture`, so resolve the plugin root once and reference the agents from there:
+
+```bash
+SKILL_REAL=$(realpath ~/.agents/skills/rgit-capture 2>/dev/null || readlink -f ~/.agents/skills/rgit-capture)
+PLUGIN_ROOT=$(dirname "$(dirname "$SKILL_REAL")")    # the bundled _plugin/ directory
+```
+
+Every `agents/<name>.md` reference below (`agents/capsule-segmenter.md`, `agents/edge-judge.md`) lives at `$PLUGIN_ROOT/agents/<name>.md`.
+
+## Process
+
+### 1. Ensure there are proposals to segment (Phase 1 — free, deterministic)
+
+If the user just made changes and there is no open proposal yet, create one:
+
+```
+rgit capture --trigger manual
+```
+
+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
+
+Run `rgit pending --json`. You get a list of `{proposal_id, trigger, diff, candidates}`. The `diff` is the raw material; the `candidates` are the crude heuristic guesses you are about to replace. If the list is empty, tell the user there is nothing to segment and stop.
+
+### 3. Dispatch the capsule-segmenter subagent (Phase 2 — agentic, on subscription)
+
+For each pending proposal, dispatch a subagent using the **`capsule-segmenter`** agent definition (`agents/capsule-segmenter.md`). Run independent proposals concurrently. Pass in the dispatch prompt: `proposal_id`, `repo_root` (absolute path of the target repo), `diff` (verbatim from `rgit pending`), and `symbols` if available (otherwise the subagent infers from the diff). The subagent returns `{"capsules": [...], "dropped": [...]}` — high-quality capsules with real `intent` / `knobs` / `data_assumptions` / `resurrection_guide`, infrastructure noise dropped.
+
+### 4. Write the capsules back
+
+For each proposal, write the subagent's `capsules` array back through the CLI. Pipe the JSON to stdin:
+
+```
+echo '<capsules-json-array>' | rgit resegment <proposal_id> --from-json -
+```
+
+This replaces the crude heuristic candidates with the agent-quality ones. Do NOT auto-approve — capture stays human-gated.
+
+### 5. Hand back for review
+
+Show the user a short summary (one line per capsule: name + intent), then tell them to approve the ones they want:
+
+```
+rgit review                          # list open proposals
+rgit review --approve <proposal_id> --name <name>
+```
+
+On approval the capsule lands in the graph with its `produced` edge to the run.
+
+### 6. Infer graph edges (deterministic baseline + agent-judged relationships)
+
+After approval, wire the new capsule into the graph:
+
+```
+rgit edges --apply
+```
+
+This deterministically writes a neutral **`overlaps`** baseline edge between capsules touching the same file+symbol, and prints JSON with `overlap_pairs` (the `{a, b}` pairs it just connected) and `depends_candidates` (over-produced `{src, dst, evidence}` hypotheses from name overlap).
+
+`overlaps` only says "same region" — it does **not** mean conflict. Dispatch the **`edge-judge`** subagent (`agents/edge-judge.md`) once, passing both `depends_candidates` and `overlap_pairs` plus the referenced capsules' names/intents/slices. The judge returns two things:
+
+- confirmed `depends_on` edges, and
+- a precise relationship for each overlap pair: `alternative_to`, `composable_with`, `supersedes` (directed), `conflicts_with`, or "leave as overlaps".
+
+Write each result with `rgit edges --add`:
+
+```
+rgit edges --add depends_on <src> <dst>          # confirmed dependency
+rgit edges --add alternative_to <a> <b>          # symmetric: write BOTH directions
+rgit edges --add alternative_to <b> <a>
+rgit edges --add supersedes <newer> <older>      # directed: one line
+```
+
+For a symmetric type write both directions; for `supersedes` write the single directed edge. Pairs the judge leaves unclassified keep their neutral `overlaps` baseline — the graph renderer hides that baseline automatically once a richer edge exists for the pair, so don't delete anything.
+
+Reject coincidental overlaps — a missing edge is cheaper than a wrong one. The confirmed `depends_on` plus the agent-classified same-region relationships are what make `recall` and `rgit graph` show real structure instead of an undifferentiated conflict mesh.
+
+## Notes
+
+- **No paid API.** All LLM work here is the dispatched `capsule-segmenter` and `edge-judge` subagents, which run on this session's subscription.
+- **Phase 1 vs Phase 2.** `rgit` (diff + libcst + heuristic) is the deterministic substrate; the subagents are the semantic layer. Same split as the Understand-Anything plugin (deterministic extraction → dispatched analyzer).
+- **Regeneration** (recalling a capsule and re-applying it onto today's code) is the sibling flow — see the `capsule-regenerator` agent driven off `recall` + `compose` (the `rgit-recall` skill).