research-git 0.0.1__py3-none-any.whl

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

@@ -0,0 +1,54 @@
+---
+name: rgit-recall
+description: |
+  Bring a past idea back onto today's codebase. Use when the user wants to "recall", "resurrect", "bring back", or "re-apply" a feature/idea they captured before (e.g. "bring back the re-ranking retrieval step"). Orchestrates: recall the capsule(s) → compose a regeneration brief against current code → dispatch the capsule-regenerator subagent to re-implement it → human review + `rgit run`. No paid API.
+---
+
+# rgit-recall
+
+Drives the **recall → compose → regenerate** half of the research-git loop. The stored capsule is a spec; the regenerator rebuilds it onto *today's* code.
+
+**Prerequisites:** the repo is `rgit init`-ed and the `research-git` MCP server is connected (it exposes `recall` and `compose`).
+
+**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-recall`, so resolve the plugin root once and reference the agent from there:
+
+```bash
+SKILL_REAL=$(realpath ~/.agents/skills/rgit-recall 2>/dev/null || readlink -f ~/.agents/skills/rgit-recall)
+PLUGIN_ROOT=$(dirname "$(dirname "$SKILL_REAL")")    # the bundled _plugin/ directory
+```
+
+The `agents/capsule-regenerator.md` reference below lives at `$PLUGIN_ROOT/agents/capsule-regenerator.md`.
+
+## Process
+
+### 1. Recall the capsule(s)
+
+Take the user's natural-language ask and call the MCP tool **`recall(query)`**. It returns matches, each with its `depends_on` subgraph. Show the user a short list (name + intent) and confirm which feature(s) to bring back. Default to the top match if unambiguous. If nothing matches, tell the user and stop (suggest `list_features` to browse).
+
+### 2. Resolve the full feature set
+
+Include each chosen capsule **plus its `depends_on` dependencies** (a feature often needs its prerequisites). Collect the final list of `feature_id`s.
+
+### 3. Compose the regeneration brief (against current code)
+
+Call the MCP tool **`compose(feature_ids)`**. It returns, per feature: `intent`, `knobs`, `data_assumptions`, `resurrection_guide`, the reference `code_slices`, the **live `current_source`** of each touched symbol, and any `conflicts` (symbols touched by more than one chosen feature).
+
+### 4. Dispatch the capsule-regenerator subagent (on subscription)
+
+Dispatch a subagent using the **`capsule-regenerator`** agent definition (`agents/capsule-regenerator.md`). Pass the full brief verbatim plus `repo_root`. The subagent edits the working tree to re-implement the feature(s) onto today's code, resolves conflicts, sanity-checks syntax, and returns an `applied` report with `provenance` (clean vs adapted) per feature.
+
+### 5. Review + close the loop
+
+Show the user the resulting working-tree diff (`git diff`) and the subagent's provenance/adaptation notes. **Do not commit or freeze for them.** Tell the user to test + freeze it, linking the new run back to the source capsule:
+
+```
+rgit run --from <source_capsule_id> -- <their command>
+```
+
+That records a new `run` node, freezes a byte-exact artifact, links a `produced` edge from the source capsule, and (on approving the resulting proposal) establishes `variant_of` back to the original. If the subagent returned an `updated_resurrection_guide`, write it to a file and pass `--refresh-guide-file <path>` so the source capsule learns.
+
+## Notes
+
+- **Reproducibility stays intact.** The subagent only *authors*; the human runs `rgit run`, which is the only thing that freezes the reproducible artifact. The agent is never in the replay path.
+- **No paid API.** The regenerator is a dispatched subagent on this session's subscription. MCP only served read-only graph snippets (`recall`, `compose`).
+- **Sibling flow:** capture/segmentation is `rgit-capture` + `capsule-segmenter`.

rgit/ablation.py

@@ -0,0 +1,70 @@
+# src/rgit/ablation.py
+from __future__ import annotations
+from itertools import chain, combinations
+
+from .metricdir import best_index
+from .store.store import Store
+
+
+def _powerset(items: list[str]):
+    return chain.from_iterable(combinations(items, r) for r in range(len(items) + 1))
+
+
+def _active_set(store: Store, run_id: str) -> frozenset[str]:
+    """A run's active capsules; fall back to produced capsules when none declared."""
+    active = store.active_features(run_id)
+    if active:
+        return frozenset(active)
+    produced = [r["src"] for r in store.conn.execute(
+        "SELECT src FROM edges WHERE dst=? AND type=?", (run_id, "produced"))]
+    return frozenset(produced)
+
+
+def ablation(store: Store, capsule_ids: list[str], metric: str | None = None) -> dict:
+    """Build a base/+A/+A+B grid over the powerset of `capsule_ids`.
+
+    `capsule_ids` accepts capsule ids or names (resolved to ids). Each subset cell
+    is the latest run whose active set equals that subset *exactly* — a run that
+    also had some capsule active outside the requested sweep is dropped, not
+    folded into a smaller cell, so cells never compare confounded measurements.
+    Returns {"rows": [{subset(names), run, cells{metric: value}}], "winners": {metric: subset}}.
+    """
+    capsule_ids = [store.resolve_feature(t) for t in capsule_ids]   # names -> ids
+    caps = {c.id: c for c in store.list_features()}
+    name = {cid: caps[cid].name for cid in capsule_ids}
+    target = frozenset(capsule_ids)
+
+    # All runs, newest first, bucketed by their EXACT active set (subsets of the
+    # sweep only; a run with an extra active capsule outside `target` is skipped).
+    rows_all = store.conn.execute("SELECT id FROM runs").fetchall()
+    runs = sorted((store.get_run(r["id"]) for r in rows_all),
+                  key=lambda r: r.created_at, reverse=True)
+    latest_for: dict[frozenset, object] = {}
+    for run in runs:
+        aset = _active_set(store, run.id)
+        if not aset <= target:                 # confounded by a feature outside the sweep
+            continue
+        latest_for.setdefault(aset, run)       # newest wins (we iterate desc)
+
+    metric_names: list[str] = []
+    rows = []
+    for subset in _powerset(capsule_ids):
+        run = latest_for.get(frozenset(subset))
+        cells = dict(run.metrics) if (run and run.metrics) else {}
+        for k in cells:
+            if k not in metric_names:
+                metric_names.append(k)
+        rows.append({"subset": tuple(sorted(name[c] for c in subset)),
+                     "run": run.id if run else None, "cells": cells})
+
+    cols = [metric] if metric else metric_names
+    for row in rows:                            # ensure every row has every column
+        for m in cols:
+            row["cells"].setdefault(m, None)
+
+    winners: dict[str, tuple] = {}
+    for m in cols:
+        idx = best_index(store, m, [row["cells"].get(m) for row in rows])
+        if idx is not None:
+            winners[m] = rows[idx]["subset"]
+    return {"rows": rows, "winners": winners}

rgit/agent_guidance.py

@@ -0,0 +1,169 @@
+"""Managed global guidance block for agent clients."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+
+START = "<!-- research-git:start -->"
+END = "<!-- research-git:end -->"
+
+# Modes a user may pin in the managed block; carried across reinstalls so an
+# upgrade does not silently reset a deliberate choice back to `default`.
+KNOWN_MODES = ("default", "manual-only", "custom")
+_MODE_RE = re.compile(r"^Current mode:[ \t]*(.+)$", re.MULTILINE)
+
+
+def render_global_block(mode: str = "default") -> str:
+    if mode not in KNOWN_MODES:
+        mode = "default"
+    return (
+        f"{START}\n"
+        "## research-git\n"
+        "\n"
+        "research-git is installed as a default agent capability.\n"
+        "\n"
+        f"Current mode: {mode}\n"
+        "\n"
+        "Mode options:\n"
+        "- `default`: After code changes, consider capture. Capture meaningful "
+        "research/code ideas; skip mechanical changes.\n"
+        "- `manual-only`: Use research-git only when the user explicitly asks to "
+        "capture, save, recall, resurrect, or bring back an idea.\n"
+        "- `custom`: Inherit `default`, then apply repo-specific rules from this "
+        "repo.\n"
+        "\n"
+        "Priority:\n"
+        "- Session/user instruction overrides repo and global guidance.\n"
+        "- Repo-level research-git preferences override global guidance.\n"
+        "\n"
+        "Repo preference recording:\n"
+        "- If the user clearly asks to remember a stable repo-level research-git "
+        "preference, update this repo's guidance file.\n"
+        "- For unclear preferences, ask first.\n"
+        "- 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"
+        "- 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"
+        "- In final feedback, mention any capsules created, approved, applied, "
+        "or skipped, plus important graph relations.\n"
+        f"{END}\n"
+    )
+
+
+def manual_status(mode: str = "default") -> dict:
+    return {
+        "action": "manual",
+        "block": render_global_block(mode),
+        "instructions": "Add this managed block to your agent's global guidance file.",
+    }
+
+
+def manual_uninstall_status() -> dict:
+    return {
+        "action": "manual",
+        "instructions": (
+            "remove the research-git managed block from your agent's global "
+            "guidance file if you added it manually."
+        ),
+    }
+
+
+def upsert_managed_block(path: Path, *, mode: str | None = None,
+                         dry_run: bool = False) -> dict:
+    # mode=None means "no explicit choice this run": render the default block but
+    # preserve any mode the user previously pinned. An explicit mode overrides.
+    explicit = mode is not None
+    block = render_global_block(mode or "default")
+    exists = path.exists()
+    text = path.read_text(encoding="utf-8") if exists else ""
+    new_text, action = _upsert_text(text, block, exists, carry=not explicit)
+    if dry_run:
+        return {"action": _dry_action(action), "path": str(path), "block": block}
+    if new_text != text:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write(path, new_text)
+    return {"action": action if new_text != text else "unchanged",
+            "path": str(path)}
+
+
+def remove_managed_block(path: Path, *, dry_run: bool = False) -> dict:
+    if not path.exists():
+        return {"action": "absent", "path": str(path)}
+    text = path.read_text(encoding="utf-8")
+    span = _managed_span(text)
+    if span is None:
+        return {"action": "absent", "path": str(path)}
+    start, end = span
+    new_text = text[:start] + text[end:]
+    if dry_run:
+        return {"action": "would_remove", "path": str(path)}
+    _atomic_write(path, new_text)
+    return {"action": "removed", "path": str(path)}
+
+
+def _upsert_text(text: str, block: str, exists: bool,
+                 carry: bool = True) -> tuple[str, str]:
+    span = _managed_span(text)
+    if span is not None:
+        start, end = span
+        if carry:
+            block = _carry_mode(text[start:end], block)
+        new_text = text[:start] + block + text[end:]
+        return new_text, "updated"
+    if not exists or not text:
+        return block, "created"
+    sep = "" if text.endswith("\n") else "\n"
+    return text + sep + "\n" + block, "appended"
+
+
+def _carry_mode(old_block: str, new_block: str) -> str:
+    """Preserve a user-pinned `Current mode:` from the existing block.
+
+    Re-rendering always emits `Current mode: default`. If the user had pinned a
+    different recognized mode, keep it so an upgrade does not reset their choice.
+    """
+    m = _MODE_RE.search(old_block)
+    if not m:
+        return new_block
+    mode = m.group(1).strip()
+    if mode == "default" or mode not in KNOWN_MODES:
+        return new_block
+    return _MODE_RE.sub(f"Current mode: {mode}", new_block, count=1)
+
+
+def _managed_span(text: str) -> tuple[int, int] | None:
+    start = text.find(START)
+    if start < 0:
+        return None
+    end = text.find(END, start)
+    if end < 0:
+        return None
+    after_end = end + len(END)
+    if text[after_end:after_end + 1] == "\n":
+        after_end += 1
+    return start, after_end
+
+
+def _dry_action(action: str) -> str:
+    return {
+        "created": "would_create",
+        "appended": "would_append",
+        "updated": "would_update",
+    }[action]
+
+
+def _atomic_write(path: Path, text: str) -> None:
+    tmp = path.with_name(f".{path.name}.research-git.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    if path.exists():
+        os.chmod(tmp, path.stat().st_mode)
+    tmp.replace(path)

rgit/agent_platforms.py

@@ -0,0 +1,49 @@
+"""Platform facts for installing research-git agent guidance."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def home_dir() -> Path:
+    return Path.home()
+
+
+def _env_dir(var: str) -> Path | None:
+    """Return $var as a Path if it is set and non-empty, else None."""
+    val = os.environ.get(var)
+    return Path(val) if val else None
+
+
+def _config_home() -> Path:
+    """XDG base dir for per-user config, honoring $XDG_CONFIG_HOME."""
+    return _env_dir("XDG_CONFIG_HOME") or home_dir() / ".config"
+
+
+def guidance_target(platform: str) -> dict | None:
+    home = home_dir()
+    if platform == "codex":
+        root = _env_dir("CODEX_HOME") or home / ".codex"
+        return {
+            "path": root / "AGENTS.md",
+            "reload": "Start a new Codex session after install.",
+        }
+    if platform == "claude-code":
+        root = _env_dir("CLAUDE_CONFIG_DIR") or home / ".claude"
+        return {
+            "path": root / "CLAUDE.md",
+            "reload": "Restart Claude Code or run /reload-plugins after install.",
+        }
+    if platform == "gemini":
+        return {
+            "path": home / ".gemini" / "GEMINI.md",
+            "reload": "Start a new Gemini CLI session after install.",
+        }
+    if platform == "opencode":
+        root = _config_home() / "opencode"
+        if root.exists():
+            return {
+                "path": root / "AGENTS.md",
+                "reload": "Start a new opencode session after install.",
+            }
+    return None

rgit/astmap.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Optional
+
+import libcst as cst
+from libcst.metadata import MetadataWrapper, PositionProvider
+
+_HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", re.M)
+_FILE = re.compile(r"^\+\+\+ b/(.+)$", 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 _changed_line_ranges(diff: str) -> dict[str, list[tuple[int, int]]]:
+    """file -> list of (start, end) line ranges touched on the new side."""
+    result: dict[str, list[tuple[int, int]]] = {}
+    current: Optional[str] = None
+    for line in diff.splitlines():
+        m = _FILE.match(line)
+        if m:
+            current = m.group(1)
+            result.setdefault(current, [])
+            continue
+        h = _HUNK.match(line)
+        if h and current:
+            start = int(h.group(1))
+            length = int(h.group(2) or "1")
+            result[current].append((start, start + max(length, 1) - 1))
+    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) -> list[dict]:
+    """[{file, symbol}] for each top-level def/class overlapping a diff hunk."""
+    out: list[dict] = []
+    for file, ranges in _changed_line_ranges(diff).items():
+        path = repo / file
+        if not path.suffix == ".py" or not path.exists() or not ranges:
+            continue
+        try:
+            wrapper = MetadataWrapper(cst.parse_module(_read_python_source(path)))
+        except cst.ParserSyntaxError:
+            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."""
+    path = repo / file
+    if not path.exists():
+        return None
+    try:
+        module = cst.parse_module(_read_python_source(path))
+    except cst.ParserSyntaxError:
+        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."""
+    path = repo / file
+    if path.suffix != ".py" or not path.exists():
+        return None
+    try:
+        wrapper = MetadataWrapper(cst.parse_module(_read_python_source(path)))
+    except cst.ParserSyntaxError:
+        return None
+    finder = _SymbolFinder([(line, line)])
+    wrapper.visit(finder)
+    found = sorted(finder.found)
+    return found[0] if found else None