@try-works/dsh-recursive-mode 0.1.3 → 0.1.4

package/references/scripts/recursive-training-mcp.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""
+Optional MCP (Model Context Protocol) server for repository experiences.
+
+Provides a get_repo_experiences tool that any MCP-compatible client can call
+to dynamically retrieve ReasoningBank-structured experiences relevant to the
+current task, file paths, and task type.
+
+Usage:
+    python recursive-training-mcp.py --repo-root /path/to/repo
+
+Compatible clients: Claude Desktop, Cline, Cursor (with MCP), Continue.dev.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+class ReasoningBankReader:
+    """Reads ReasoningBank-structured memory from the memory plane."""
+
+    DOMAINS_DIR = ".recursive/memory/domains"
+    TRAINING_DIR = ".recursive/memory/training"
+
+    def __init__(self, repo_root: str):
+        self.root = Path(repo_root)
+        self.domains_dir = self.root / self.DOMAINS_DIR
+        self.training_dir = self.root / self.TRAINING_DIR
+
+    def _parse_items_from_file(self, filepath: Path) -> List[dict]:
+        if not filepath.exists():
+            return []
+        content = filepath.read_text(encoding="utf-8")
+        if "Status: CURRENT" not in content and "Status: SUSPECT" not in content:
+            return []
+
+        items = []
+        pattern = re.compile(
+            r'### (RB-\d+):\s*(.+?)\n\n'
+            r'\*\*Description:\*\*\s*(.+?)\n\n'
+            r'\*\*Content:\*\*\s*(.+?)(?=\n\n```|\n### |\Z)',
+            re.DOTALL
+        )
+        for m in pattern.finditer(content):
+            items.append({
+                "rb_id": m.group(1),
+                "title": m.group(2).strip(),
+                "description": m.group(3).strip(),
+                "content": m.group(4).strip(),
+            })
+
+        # Enrich with schema metadata
+        schema_pattern = re.compile(
+            r'```yaml\n'
+            r'rb_id: "(RB-\d+)"\n'
+            r'title: "([^"]+)"\n'
+            r'description: "([^"]+)"\n'
+            r'task_type: "([^"]*)"\n'
+            r'subsystem: "([^"]*)"\n'
+            r'source_runs: (.+?)\n'
+            r'applies_to: (.+?)\n'
+            r'success_rate: ([\d.]+)\n'
+            r'status: (\w+)\n'
+            r'created_at: "([^"]+)"\n'
+            r'```',
+            re.DOTALL
+        )
+        for m in schema_pattern.finditer(content):
+            rb_id = m.group(1)
+            for item in items:
+                if item["rb_id"] == rb_id:
+                    item["task_type"] = m.group(4)
+                    item["subsystem"] = m.group(5)
+                    item["success_rate"] = float(m.group(8))
+                    item["status"] = m.group(9)
+                    item["created_at"] = m.group(10)
+                    # Parse JSON arrays
+                    try:
+                        sr = m.group(6)
+                        item["source_runs"] = json.loads(sr) if sr.strip() else []
+                    except Exception:
+                        item["source_runs"] = []
+                    try:
+                        at = m.group(7)
+                        item["applies_to"] = json.loads(at) if at.strip() else []
+                    except Exception:
+                        item["applies_to"] = []
+                    break
+        return items
+
+    def load_all_items(self) -> List[dict]:
+        items = []
+        for d in (self.domains_dir, self.training_dir):
+            if not d.exists():
+                continue
+            for f in sorted(d.glob("*.md")):
+                items.extend(self._parse_items_from_file(f))
+        return [item for item in items if item.get("status") != "deprecated"]
+
+    def get_relevant(self, task_type: str = "", file_paths: List[str] = None, subsystem: str = "") -> List[dict]:
+        """Score and filter items by relevance. Returns sorted list with scores."""
+        all_items = self.load_all_items()
+        file_paths = file_paths or []
+        scored = []
+
+        for item in all_items:
+            score = 0
+            applies_to = item.get("applies_to", [])
+            item_task = item.get("task_type", "")
+            item_subsystem = item.get("subsystem", "")
+
+            # Task type match (strong signal)
+            if task_type and item_task and task_type.lower() in item_task.lower():
+                score += 5
+
+            # Subsystem match (strong signal)
+            if subsystem and item_subsystem and subsystem.lower() in item_subsystem.lower():
+                score += 4
+
+            # File path overlap (medium signal)
+            for f in file_paths:
+                parts = f.split("/")
+                for part in parts:
+                    if len(part) > 2:
+                        for tag in applies_to:
+                            if part.lower() in tag.lower():
+                                score += 2
+                                break
+
+            # Content overlap (weak signal)
+            for f in file_paths:
+                content = f"{item.get('title', '')} {item.get('description', '')} {item.get('content', '')}"
+                if f.lower() in content.lower():
+                    score += 1
+
+            # Success rate bonus
+            sr = item.get("success_rate", 0)
+            if isinstance(sr, (int, float)) and sr > 0.8:
+                score += 1
+
+            if score > 0:
+                item["_relevance_score"] = score
+                scored.append(item)
+
+        scored.sort(key=lambda x: x["_relevance_score"], reverse=True)
+        return scored
+
+
+def main():
+    parser = argparse.ArgumentParser(description="MCP server for repo experiences")
+    parser.add_argument("--repo-root", type=str, required=True)
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    rb = ReasoningBankReader(repo_root)
+
+    print("MCP server (ReasoningBank) starting...", file=sys.stderr)
+    print(f"Repo root: {repo_root}", file=sys.stderr)
+
+    while True:
+        try:
+            line = input()
+            msg = json.loads(line)
+            method = msg.get("method", "")
+            msg_id = msg.get("id")
+
+            if method == "initialize":
+                print(json.dumps({
+                    "jsonrpc": "2.0", "id": msg_id,
+                    "result": {
+                        "protocolVersion": "2024-11-05",
+                        "capabilities": {"tools": {}},
+                        "serverInfo": {"name": "recursive-training-mcp", "version": "2.0.0"},
+                    },
+                }), flush=True)
+
+            elif method == "tools/list":
+                print(json.dumps({
+                    "jsonrpc": "2.0", "id": msg_id,
+                    "result": {
+                        "tools": [
+                            {
+                                "name": "get_repo_experiences",
+                                "description": "Get ReasoningBank-structured experiences for the current repository",
+                                "inputSchema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "task_type": {
+                                            "type": "string",
+                                            "description": "Type of task (e.g., commit-remediation, add-api-endpoint)",
+                                        },
+                                        "file_paths": {
+                                            "type": "array",
+                                            "items": {"type": "string"},
+                                            "description": "List of file paths being modified",
+                                        },
+                                        "subsystem": {
+                                            "type": "string",
+                                            "description": "Target subsystem (e.g., packages/artifacts)",
+                                        },
+                                    },
+                                },
+                            }
+                        ]
+                    },
+                }), flush=True)
+
+            elif method == "tools/call":
+                params = msg.get("params", {})
+                tool_name = params.get("name", "")
+                arguments = params.get("arguments", {})
+
+                if tool_name == "get_repo_experiences":
+                    task_type = arguments.get("task_type", "")
+                    file_paths = arguments.get("file_paths", [])
+                    subsystem = arguments.get("subsystem", "")
+                    items = rb.get_relevant(task_type, file_paths, subsystem)
+
+                    if items:
+                        lines = ["# Repository Experiential Knowledge (ReasoningBank)\n"]
+                        for item in items[:20]:  # top 20
+                            rb_id = item["rb_id"]
+                            title = item["title"]
+                            desc = item["description"]
+                            content = item["content"]
+                            score = item.get("_relevance_score", 0)
+                            sr = item.get("success_rate")
+                            sr_str = f" [success: {sr:.0%}]" if isinstance(sr, float) else ""
+                            applies = ", ".join(item.get("applies_to", []))
+                            lines.append(
+                                f"## [{rb_id}] {title}{sr_str} (score: {score})\n"
+                                f"{desc}\n\n{content}\n"
+                                f"*Applies to: {applies}*\n"
+                            )
+                        result_text = "\n".join(lines)
+                    else:
+                        result_text = "No relevant experiences found for this task and file set."
+
+                    print(json.dumps({
+                        "jsonrpc": "2.0", "id": msg_id,
+                        "result": {"content": [{"type": "text", "text": result_text}]},
+                    }), flush=True)
+
+                else:
+                    print(json.dumps({
+                        "jsonrpc": "2.0", "id": msg_id,
+                        "error": {"code": -32601, "message": f"Unknown tool: {tool_name}"},
+                    }), flush=True)
+
+        except EOFError:
+            break
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/references/scripts/recursive-training-phase8-trigger.ps1

@@ -0,0 +1,55 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Post-Phase 8 training trigger for recursive-mode.
+
+.DESCRIPTION
+    Thin wrapper around recursive-training-phase8-trigger.py.
+    Extraction transport is owned by recursive-training-extract.py, not this wrapper.
+
+.PARAMETER RepoRoot
+    Path to the git repository root.
+
+.PARAMETER RunId
+    The run that just completed Phase 8.
+
+.PARAMETER Auto
+    Skip user confirmation and run training immediately.
+
+.PARAMETER GrpoArgs
+    Extra arguments passed through to recursive-training-grpo.py
+    (for example: '--winner-only-threshold 3').
+
+.EXAMPLE
+    .\recursive-training-phase8-trigger.ps1 -RepoRoot . -RunId phase25 -Auto
+#>
+param(
+    [Parameter(Mandatory)]
+    [string]$RepoRoot,
+
+    [Parameter(Mandatory)]
+    [string]$RunId,
+
+    [switch]$Auto,
+
+    [string]$GrpoArgs = ""
+)
+
+$python = Get-Command python -ErrorAction SilentlyContinue
+if (-not $python) {
+    $python = Get-Command python3 -ErrorAction SilentlyContinue
+}
+if (-not $python) {
+    Write-Error "Python is required but not found."
+    exit 1
+}
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$pyScript = Join-Path $scriptDir "recursive-training-phase8-trigger.py"
+
+$argsList = @("--repo-root", $RepoRoot, "--run-id", $RunId)
+if ($Auto) { $argsList += "--auto" }
+if ($GrpoArgs) { $argsList += @("--grpo-args", $GrpoArgs) }
+
+& $python.Source $pyScript @argsList
+exit $LASTEXITCODE

package/references/scripts/recursive-training-phase8-trigger.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Post-Phase 8 training trigger for recursive-mode.
+
+Run this immediately after Phase 8 (08-memory-impact.md) is locked.
+Thin wrapper: checks preconditions, then delegates to recursive-training-grpo.py.
+
+Usage (after Phase 8 lock):
+    python .recursive/scripts/recursive-training-phase8-trigger.py \
+        --repo-root . \
+        --run-id phase25-organizations-teams-rbac \
+        [--auto] \
+        [--grpo-args "--winner-only-threshold 3"]
+
+Arguments:
+    --repo-root: Path to git repository root
+    --run-id: The run that just completed Phase 8
+    --auto: Skip the "Train now?" prompt and run immediately
+    --grpo-args: Extra arguments passed through to recursive-training-grpo.py
+
+Exit codes:
+    0: OK (training wrote memory items)
+    1: Error (missing scripts, bridge failure, etc.)
+    2: User declined (or --auto not set and user not prompted) / extractor unavailable
+    3: Training ran but wrote zero items (insufficient groups / empty extraction)
+"""
+
+import argparse
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+
+def count_completed_runs(runs_dir: Path) -> int:
+    """Count runs with a locked 08-memory-impact.md artifact."""
+    if not runs_dir.exists():
+        return 0
+    count = 0
+    for run_dir in runs_dir.iterdir():
+        if run_dir.is_dir():
+            phase8 = run_dir / "08-memory-impact.md"
+            if phase8.exists():
+                text = phase8.read_text(encoding="utf-8")
+                if "LockedAt" in text or "Status: LOCKED" in text:
+                    count += 1
+    return count
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Post-Phase 8 training trigger for recursive-mode"
+    )
+    parser.add_argument("--repo-root", type=str, required=True)
+    parser.add_argument("--run-id", type=str, required=True)
+    parser.add_argument("--auto", action="store_true",
+                        help="Run training immediately without prompting")
+    parser.add_argument("--grpo-args", type=str, default="",
+                        help='Extra args for recursive-training-grpo.py, e.g. "--winner-only-threshold 3"')
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    scripts_dir = repo_root / ".recursive" / "scripts"
+    runs_dir = repo_root / ".recursive" / "run"
+    grpo_script = scripts_dir / "recursive-training-grpo.py"
+
+    # --- Check scripts exist ---
+    if not grpo_script.exists():
+        print("ERROR: recursive-training-grpo.py not found.")
+        print("Run: python <SKILL_DIR>/scripts/install-recursive-mode.py --repo-root .")
+        return 1
+
+    # --- Check enough runs ---
+    completed = count_completed_runs(runs_dir)
+    if completed < 2:
+        print(f"Only {completed} completed run(s). Need 2+ for training.")
+        print("Training skipped. Complete more runs and try again.")
+        return 3
+
+    # --- Prompt or auto-run ---
+    if not args.auto:
+        print(f"Run '{args.run_id}' completed Phase 8.")
+        print(f"{completed} completed runs available.")
+        print("")
+        print("To extract learnings, run:")
+        print(f"  python .recursive/scripts/recursive-training-grpo.py \\")
+        print(f"    --repo-root . --incremental --run-id {args.run_id}")
+        if args.grpo_args:
+            print(f"    {args.grpo_args}")
+        print("")
+        print("Or re-run this script with --auto to skip confirmation.")
+        return 2
+
+    # --- Run training ---
+    print(f"Auto-triggering training for {args.run_id} ({completed} runs)...")
+
+    def run_grpo(extra: list[str]) -> subprocess.CompletedProcess:
+        cmd = [sys.executable, str(grpo_script), "--repo-root", str(repo_root), *extra]
+        if args.grpo_args:
+            cmd.extend(shlex.split(args.grpo_args))
+        return subprocess.run(cmd)
+
+    result = run_grpo(["--incremental", "--run-id", args.run_id])
+    if result.returncode == 3:
+        print(
+            "Incremental subsystem group wrote 0 items; "
+            "falling back to full Phase-8-locked training..."
+        )
+        result = run_grpo([])
+
+    if result.returncode == 0:
+        print("Training extraction updated the memory plane.")
+        print(
+            "Future runs should read .recursive/memory/MEMORY.md and use "
+            "recursive-training-loader.py when experiential memory is relevant."
+        )
+        print("Done.")
+        return 0
+
+    if result.returncode == 2:
+        print("ERROR: Training extractor is unavailable. Memory plane was not updated.")
+        print(
+            "Wire RECURSIVE_TRAINING_EXTRACTOR_CMD, provide a response file, "
+            "or run agent-operated extraction."
+        )
+        return 2
+
+    if result.returncode == 3:
+        print("Training ran but extracted 0 items. Memory plane was not updated.")
+        return 3
+
+    print("ERROR: Training extraction failed.")
+    return result.returncode or 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/references/scripts/recursive-training-sync.ps1

@@ -0,0 +1,29 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    Sync .recursive/memory/ to tool instruction files (PowerShell wrapper).
+
+.DESCRIPTION
+    Thin wrapper that calls recursive-training-sync.py with the same arguments.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$RepoRoot
+)
+
+$python = Get-Command python -ErrorAction SilentlyContinue
+if (-not $python) {
+    $python = Get-Command python3 -ErrorAction SilentlyContinue
+}
+
+if (-not $python) {
+    Write-Error "Python is required but not found. Please install Python 3.10+."
+    exit 1
+}
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$pyScript = Join-Path $scriptDir "recursive-training-sync.py"
+
+& $python.Source $pyScript @("--repo-root", $RepoRoot)

package/references/scripts/recursive-training-sync.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Read-only startup guidance for recursive-mode experiential memory.
+
+Reads ReasoningBank-structured memory from .recursive/memory/domains/
+and .recursive/memory/training/, then prints what an agent should read or load
+at the start of a run.
+
+Usage:
+    python recursive-training-sync.py --repo-root .
+"""
+
+import argparse
+import re
+from pathlib import Path
+from typing import Dict, List
+
+
+class ReasoningBankReader:
+    """Reads ReasoningBank-structured memory from the memory plane."""
+
+    MEMORY_ROOT = ".recursive/memory"
+    DOMAINS_DIR = ".recursive/memory/domains"
+    TRAINING_DIR = ".recursive/memory/training"
+
+    def __init__(self, repo_root: str):
+        self.root = Path(repo_root)
+        self.memory_root = self.root / self.MEMORY_ROOT
+        self.domains_dir = self.root / self.DOMAINS_DIR
+        self.training_dir = self.root / self.TRAINING_DIR
+
+    def _parse_items_from_file(self, filepath: Path) -> List[dict]:
+        """Parse ReasoningBank items from a memory markdown file."""
+        if not filepath.exists():
+            return []
+        content = filepath.read_text(encoding="utf-8")
+        if "Status: CURRENT" not in content:
+            return []
+
+        items = []
+        # Match ReasoningBank item blocks
+        pattern = re.compile(
+            r'### (RB-\d+):\s*(.+?)\n\n'
+            r'\*\*Description:\*\*\s*(.+?)\n\n'
+            r'\*\*Content:\*\*\s*(.+?)(?=\n\n```|\n### |\Z)',
+            re.DOTALL
+        )
+        for m in pattern.finditer(content):
+            items.append({
+                "rb_id": m.group(1),
+                "title": m.group(2).strip(),
+                "description": m.group(3).strip(),
+                "content": m.group(4).strip(),
+            })
+
+        # Also parse YAML schema blocks for metadata
+        schema_pattern = re.compile(
+            r'```yaml\n'
+            r'rb_id: "(RB-\d+)"\n'
+            r'title: "([^"]+)"\n'
+            r'description: "([^"]+)"\n'
+            r'task_type: "([^"]*)"\n'
+            r'subsystem: "([^"]*)"\n'
+            r'source_runs: (.+?)\n'
+            r'applies_to: (.+?)\n'
+            r'success_rate: ([\d.]+)\n'
+            r'status: (\w+)\n'
+            r'created_at: "([^"]+)"\n'
+            r'```',
+            re.DOTALL
+        )
+        for m in schema_pattern.finditer(content):
+            rb_id = m.group(1)
+            for item in items:
+                if item["rb_id"] == rb_id:
+                    item["task_type"] = m.group(4)
+                    item["subsystem"] = m.group(5)
+                    item["success_rate"] = float(m.group(8))
+                    item["status"] = m.group(9)
+                    item["created_at"] = m.group(10)
+                    break
+
+        return items
+
+    def load_all_items(self) -> List[dict]:
+        """Load all ReasoningBank items from domain + training memory."""
+        items = []
+        for d in (self.domains_dir, self.training_dir):
+            if not d.exists():
+                continue
+            for f in sorted(d.glob("*.md")):
+                items.extend(self._parse_items_from_file(f))
+        return items
+
+    def list_training_docs(self) -> Dict[str, dict]:
+        """List all training memory docs with metadata."""
+        docs = {}
+        for d in (self.domains_dir, self.training_dir):
+            if not d.exists():
+                continue
+            for f in sorted(d.glob("*.md")):
+                content = f.read_text(encoding="utf-8")
+                if "Status: CURRENT" not in content:
+                    continue
+                # Count items
+                item_count = len(re.findall(r'### RB-\d+:', content))
+                # Extract scope from frontmatter if present
+                scope_match = re.search(r'Scope:\s*(.+)', content)
+                scope = scope_match.group(1).strip() if scope_match else f.name.replace('.md', '')
+                docs[f.name] = {
+                    "path": str(f.relative_to(self.memory_root)).replace('\\', '/'),
+                    "type": "domain" if "domains" in str(f) else "training",
+                    "scope": scope,
+                    "items": item_count,
+                }
+        return docs
+
+
+class ExperienceSync:
+    def __init__(self, repo_root: str):
+        self.repo_root = Path(repo_root)
+        self.rb_reader = ReasoningBankReader(repo_root)
+
+    def build_startup_guidance(self) -> str:
+        """Render non-mutating startup guidance for agents."""
+        docs = self.rb_reader.list_training_docs()
+        lines = ["## Recursive Training Startup Guidance\n"]
+        lines.append(
+            "At the start of a run, read `/.recursive/memory/MEMORY.md` first.\n"
+        )
+        lines.append(
+            "If the task may benefit from prior experiential memory, run the loader with the current task context:\n\n"
+            "```bash\n"
+            "python .recursive/scripts/recursive-training-loader.py --repo-root . \\\n"
+            "  --query \"your task description\" \\\n"
+            "  --files \"path/to/file1.ts,path/to/file2.ts\"\n"
+            "```\n"
+        )
+        lines.append("The loader resolves relevant memory docs from the memory plane and returns the most applicable learnings.\n")
+
+        if not docs:
+            lines.append("No current domain or training memory docs were found under `/.recursive/memory/`.\n")
+            return "\n".join(lines)
+
+        # Group by type
+        domains = {k: v for k, v in docs.items() if v["type"] == "domain"}
+        training = {k: v for k, v in docs.items() if v["type"] == "training"}
+
+        if domains:
+            lines.append("### Domain Memory (subsystem-specific)\n")
+            lines.append("| Doc | Scope | Items | Description |")
+            lines.append("|-----|-------|-------|-------------|")
+            for name, info in sorted(domains.items()):
+                lines.append(f"| `{info['path']}` | {info['scope']} | {info['items']} items | subsystem-specific learnings |")
+            lines.append("")
+
+        if training:
+            lines.append("### Training Memory (task-type patterns)\n")
+            lines.append("| Doc | Scope | Items | Description |")
+            lines.append("|-----|-------|-------|-------------|")
+            for name, info in sorted(training.items()):
+                lines.append(f"| `{info['path']}` | {info['scope']} | {info['items']} items | cross-subsystem task patterns |")
+            lines.append("")
+
+        lines.append("---\n")
+        lines.append("This output is advisory only. The canonical memory remains under `/.recursive/memory/`.\n")
+        return "\n".join(lines)
+
+    def sync_all(self):
+        print(self.build_startup_guidance().strip())
+
+def main():
+    parser = argparse.ArgumentParser(description="Print startup guidance for recursive-mode experiential memory")
+    parser.add_argument("--repo-root", type=str, required=True, help="Path to git repository root")
+    args = parser.parse_args()
+
+    sync = ExperienceSync(args.repo_root)
+    print("Training sync is read-only. Startup guidance:")
+    sync.sync_all()
+
+
+if __name__ == "__main__":
+    main()