dotscope 1.2.1__tar.gz → 1.2.2__tar.gz

{dotscope-1.2.1 → dotscope-1.2.2}/.github/workflows/python-publish.yml

@@ -49,7 +49,7 @@ jobs:
     # Dedicated environments with protections for publishing are strongly recommended.
     # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
     environment:
-      name: pypi
+      name: dotscope environment
       # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
       # url: https://pypi.org/p/YOURPROJECT
       #

dotscope-1.2.2/CLAUDE.md

@@ -0,0 +1,10 @@
+# CLAUDE.md
+
+This repo uses dotscope. Before touching code:
+
+1. `codebase_search("your task description")` — not manual file reads
+2. `dotscope_check` before every commit
+3. If check returns HOLDs, fix them before committing
+
+dotscope provides: dependency graph, implicit contracts, conventions,
+and file locks. Use its tools instead of guessing.

{dotscope-1.2.1 → dotscope-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotscope
-Version: 1.2.1
+Version: 1.2.2
 Summary: Agents see files. You see architecture. dotscope gives agents the architecture.
 Author: Supremum
 License-Expression: MIT

{dotscope-1.2.1/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/__init__.py

@@ -1,3 +1,3 @@
 """dotscope — Directory-scoped context boundaries for AI coding agents."""
 
-__version__ = "0.1.0"
+__version__ = "1.2.2"

{dotscope-1.2.1/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/cli.py

@@ -354,12 +354,18 @@ def _cmd_init(args):
     except Exception as e:
         print(f"dotscope: MCP config failed: {e}", file=sys.stderr)
 
-    # 4. Write AGENT_INSTRUCTIONS.md
+    # 4. Write AGENT_INSTRUCTIONS.md + CLAUDE.md
     try:
         _write_agent_instructions(root, quiet)
     except Exception as e:
         if not quiet:
             print(f"dotscope: agent instructions failed: {e}", file=sys.stderr)
+    try:
+        from .storage.claude_hooks import write_claude_md
+        write_claude_md(root)
+    except Exception as e:
+        if not quiet:
+            print(f"dotscope: CLAUDE.md failed: {e}", file=sys.stderr)
 
     # 5. Backtest as counterfactual demo
     if not quiet:

{dotscope-1.2.1 → dotscope-1.2.2}/dotscope/formatter.py

@@ -57,7 +57,7 @@ def _format_plain(resolved: ResolvedScope, root: Optional[str], show_tokens: boo
 
 
 def _format_json(resolved: ResolvedScope, root: Optional[str]) -> str:
-    """JSON format: full object."""
+    """JSON format: full object with all compiled retrieval fields."""
     data = {
         "files": [make_relative(f, root) for f in resolved.files],
         "context": resolved.context,
@@ -69,6 +69,18 @@ def _format_json(resolved: ResolvedScope, root: Optional[str]) -> str:
     if resolved.excluded_files:
         data["excluded_count"] = len(resolved.excluded_files)
 
+    # Compiled retrieval fields (populated by codebase_search)
+    if resolved.flattened_abstractions:
+        data["flattened_abstractions"] = resolved.flattened_abstractions
+    if resolved.constraints:
+        data["constraints"] = resolved.constraints
+    if resolved.routing:
+        data["routing"] = resolved.routing
+    if resolved.action_hints:
+        data["action_hints"] = resolved.action_hints
+    if resolved.retrieval_metadata:
+        data["retrieval_metadata"] = resolved.retrieval_metadata
+
     return json.dumps(data, indent=2)
 
 

{dotscope-1.2.1 → dotscope-1.2.2}/dotscope/mcp_server.py

@@ -1256,7 +1256,20 @@ def main():
             task_type=task_type,
             no_observe=no_observe or False,
         )
-        return format_resolved(resolved, fmt="json", root=root)
+        result = json.loads(format_resolved(resolved, fmt="json", root=root))
+
+        # Add next_steps based on what was found
+        next_steps = []
+        if resolved.constraints:
+            next_steps.append("Run dotscope_check before committing.")
+            if any(c.get("severity") == "GUARD" for c in resolved.constraints):
+                next_steps.append("GUARD-level constraints found. These will block your commit.")
+        if result.get("retrieval_metadata", {}).get("index_freshness") == "stale":
+            next_steps.append("Index is stale. Run dotscope ingest to refresh.")
+        if next_steps:
+            result["next_steps"] = next_steps
+
+        return json.dumps(result, indent=2)
 
     # -------------------------------------------------------------------
     # Swarm Lock MCP tools
@@ -1453,5 +1466,112 @@ def _route_by_imports(planned_imports: list, root: str) -> Optional[dict]:
     }
 
 
+    # -------------------------------------------------------------------
+    # Swarm helpers
+    # -------------------------------------------------------------------
+
+    def _find_root():
+        from .discovery import find_repo_root
+        return find_repo_root() or "."
+
+    def _get_graph(root):
+        from .passes.graph_builder import build_graph
+        return build_graph(root)
+
+    def _load_index(root):
+        from .discovery import load_index
+        return load_index(root)
+
+    def _load_invariants(root):
+        inv_path = os.path.join(root, ".dotscope", "invariants.json")
+        if os.path.isfile(inv_path):
+            try:
+                with open(inv_path, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except Exception:
+                pass
+        return {}
+
+    # -------------------------------------------------------------------
+    # Swarm Intelligence MCP tools
+    # -------------------------------------------------------------------
+
+    @mcp.tool()
+    def partition_search_space(
+        intent: str,
+        n_partitions: int = 3,
+    ) -> dict:
+        """Divide an exploratory task into non-overlapping starting points.
+
+        Uses semantic search to find relevant files, then graph analysis
+        to cleave them into decoupled partitions. Scouts assigned to
+        different partitions are guaranteed to start in structurally
+        independent domains.
+
+        Args:
+            intent: Natural language description of what to investigate
+            n_partitions: Number of parallel scouts to support (2-10)
+
+        May return fewer partitions than requested if search results
+        are highly localized. Check len(partitions), not n_partitions.
+        """
+        from .swarm.partition import partition_search_space as _partition
+        root = _root or _find_root()
+        graph = _get_graph(root)
+        index = _load_index(root)
+        invariants = _load_invariants(root)
+        return _partition(intent, n_partitions, root, graph, index, invariants)
+
+    @mcp.tool()
+    def resolve_trace(
+        entry_file: str,
+        max_depth: int = 3,
+        focus: str = "",
+    ) -> dict:
+        """Resolve context along a specific execution path.
+
+        Follows imports from entry_file up to max_depth. Returns unified
+        context covering all scopes crossed, deduplicated, with only the
+        constraints relevant to files in the trace.
+
+        Args:
+            entry_file: Starting point for the trace
+            max_depth: How many import levels to follow (default 3, max 10)
+            focus: Optional keyword to filter context relevance
+                   (e.g., "memory" to prioritize memory-related context)
+        """
+        from .swarm.trace import resolve_trace as _trace
+        root = _root or _find_root()
+        graph = _get_graph(root)
+        index = _load_index(root)
+        invariants = _load_invariants(root)
+        return _trace(
+            entry_file, max_depth, focus or None,
+            root, graph, index, invariants,
+        )
+
+    @mcp.tool()
+    def merge_scout_findings(
+        scout_reports: list,
+    ) -> dict:
+        """Cross-reference scout findings against codebase physics.
+
+        Takes raw scout reports (flagged files + notes) and returns
+        structurally validated connections, convergence points,
+        and a unified blast radius.
+
+        Each scout report should contain:
+          scout_id: int
+          flagged_files: List[str]
+          notes: str (natural language findings)
+          confidence: float (0-1, scout's self-assessed confidence)
+        """
+        from .swarm.merge import merge_scout_findings as _merge
+        root = _root or _find_root()
+        graph = _get_graph(root)
+        invariants = _load_invariants(root)
+        return _merge(scout_reports, root, graph, invariants)
+
+
 if __name__ == "__main__":
     main()

{dotscope-1.2.1 → dotscope-1.2.2}/dotscope/models/core.py

@@ -94,6 +94,10 @@ class ResolvedScope:
     # Compiled Retrieval extensions (populated by codebase_search only)
     flattened_abstractions: Dict[str, dict] = field(default_factory=dict)
     retrieval_metadata: Optional[dict] = None
+    # Structured constraints (contracts, anti-patterns, conventions, intents)
+    constraints: List[dict] = field(default_factory=list)
+    # Routing guidance (convention blueprints, voice rules)
+    routing: List[dict] = field(default_factory=list)
     # Action hints: imperative directives derived from constraints and locks
     action_hints: List[str] = field(default_factory=list)
 

{dotscope-1.2.1 → dotscope-1.2.2}/dotscope/search/synthesizer.py

@@ -131,23 +131,31 @@ def synthesize_search(
                 "scope_crossing": ab.scope_crossing,
             }
 
-    # Build constraints
-    constraints_text = ""
+    # Build constraints (keep structured for JSON response)
+    structured_constraints = []
     try:
         from ..passes.sentinel.constraints import build_constraints
-        constraints = build_constraints(root, unique_files, query)
-        if constraints:
+        raw_constraints = build_constraints(root, unique_files, query)
+        if raw_constraints:
+            structured_constraints = raw_constraints
             constraint_lines = []
-            for c in constraints:
+            for c in raw_constraints:
                 msg = c.get("message", "")
                 if msg:
                     constraint_lines.append(f"- {msg}")
             constraints_text = "\n".join(constraint_lines)
+            if constraints_text:
+                context_parts.append(f"\n## Constraints\n{constraints_text}")
     except Exception:
         pass
 
-    if constraints_text:
-        context_parts.append(f"\n## Constraints\n{constraints_text}")
+    # Build routing guidance
+    structured_routing = []
+    try:
+        from ..passes.sentinel.constraints import build_routing_guidance
+        structured_routing = build_routing_guidance(root, unique_files, query) or []
+    except Exception:
+        pass
 
     # Budget allocation: inside-out truncation
     from ..tokens import estimate_tokens
@@ -166,6 +174,8 @@ def synthesize_search(
         context="\n\n".join(context_parts) if context_parts else "",
         token_estimate=used,
         truncated=len(budget_files) < len(unique_files),
+        constraints=structured_constraints,
+        routing=structured_routing,
         flattened_abstractions=flat_abstractions,
         retrieval_metadata={
             "query": query,

{dotscope-1.2.1/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/storage/claude_hooks.py

@@ -117,3 +117,50 @@ def install_claude_hook(repo_root: str) -> str:
         f.write("\n")
 
     return f"Claude Code hook installed: {script_path}"
+
+
+_CLAUDE_MD_CONTENT = """\
+# CLAUDE.md
+
+This repo uses dotscope. Before touching code:
+
+1. `codebase_search("your task description")` — not manual file reads
+2. `dotscope_check` before every commit
+3. If check returns HOLDs, fix them before committing
+
+dotscope provides: dependency graph, implicit contracts, conventions,
+and file locks. Use its tools instead of guessing.
+"""
+
+_CLAUDE_MD_SECTION = """
+## dotscope
+
+This repo uses dotscope. Before touching code:
+
+1. `codebase_search("your task description")` — not manual file reads
+2. `dotscope_check` before every commit
+3. If check returns HOLDs, fix them before committing
+"""
+
+
+def write_claude_md(repo_root: str) -> str:
+    """Write CLAUDE.md for automatic agent briefing.
+
+    If CLAUDE.md doesn't exist, creates it with dotscope instructions.
+    If it exists but has no dotscope section, appends one.
+    If it already has a dotscope section, does nothing.
+    """
+    claude_md_path = os.path.join(repo_root, "CLAUDE.md")
+
+    if not os.path.exists(claude_md_path):
+        with open(claude_md_path, "w", encoding="utf-8") as f:
+            f.write(_CLAUDE_MD_CONTENT)
+        return f"Created {claude_md_path}"
+
+    existing = open(claude_md_path, "r", encoding="utf-8").read()
+    if "dotscope" in existing.lower() and "codebase_search" in existing:
+        return "CLAUDE.md already has dotscope instructions"
+
+    with open(claude_md_path, "a", encoding="utf-8") as f:
+        f.write(_CLAUDE_MD_SECTION)
+    return f"Appended dotscope section to {claude_md_path}"

dotscope-1.2.2/dotscope/swarm/__init__.py

@@ -0,0 +1,13 @@
+"""Swarm-ready primitives for parallel agent coordination.
+
+Three read-only tools that make dotscope the sensory layer for agent swarms:
+  partition_search_space — divide work into non-overlapping starting points
+  resolve_trace — follow an execution path with focused context
+  merge_scout_findings — cross-reference parallel findings against codebase structure
+"""
+
+from .partition import partition_search_space
+from .trace import resolve_trace
+from .merge import merge_scout_findings
+
+__all__ = ["partition_search_space", "resolve_trace", "merge_scout_findings"]

dotscope-1.2.2/dotscope/swarm/merge.py

@@ -0,0 +1,161 @@
+"""Cross-reference scout findings against codebase structure."""
+
+from collections import defaultdict
+from typing import Dict, List, Set
+
+
+def merge_scout_findings(
+    scout_reports: List[dict],
+    repo_root: str,
+    graph,
+    invariants: dict,
+) -> dict:
+    """Merge parallel scout findings using codebase structure.
+
+    Deterministic structural analysis: convergence detection, hidden
+    connection discovery via NPMI, blast radius expansion, and
+    scout agreement tiers. No LLM calls.
+    """
+    # Collect all flagged files with attribution
+    file_scouts: Dict[str, List[int]] = defaultdict(list)
+    all_files: Set[str] = set()
+
+    for report in scout_reports:
+        scout_id = report.get("scout_id", 0)
+        for filepath in report.get("flagged_files", []):
+            file_scouts[filepath].append(scout_id)
+            all_files.add(filepath)
+
+    n_scouts = len(scout_reports)
+
+    # 1. Convergence points: files flagged by 2+ scouts
+    convergence_points = []
+    for filepath, scouts in file_scouts.items():
+        if len(scouts) >= 2:
+            convergence_points.append({
+                "file": filepath,
+                "flagged_by": sorted(scouts),
+                "significance": (
+                    f"{len(scouts)} independent traces converged on this file"
+                ),
+            })
+
+    convergence_points.sort(key=lambda c: -len(c["flagged_by"]))
+
+    # 2. Hidden connections: files from different scouts that have
+    #    structural relationships (contracts, dependencies)
+    hidden_connections = []
+    scout_file_groups: Dict[int, Set[str]] = defaultdict(set)
+    for report in scout_reports:
+        scout_id = report.get("scout_id", 0)
+        for filepath in report.get("flagged_files", []):
+            scout_file_groups[scout_id].add(filepath)
+
+    # Check NPMI contracts between scout groups
+    contracts = invariants.get("contracts", [])
+    seen_connections = set()
+    for contract in contracts:
+        trigger = contract.get("trigger_file", "")
+        coupled = contract.get("coupled_file", "")
+        confidence = contract.get("confidence", 0)
+
+        if confidence < 0.5:
+            continue
+
+        trigger_scouts = set(file_scouts.get(trigger, []))
+        coupled_scouts = set(file_scouts.get(coupled, []))
+
+        if (trigger in all_files and coupled in all_files
+                and trigger_scouts != coupled_scouts
+                and not trigger_scouts & coupled_scouts):
+            key = tuple(sorted([trigger, coupled]))
+            if key not in seen_connections:
+                seen_connections.add(key)
+                hidden_connections.append({
+                    "file_a": trigger,
+                    "file_b": coupled,
+                    "relation": "implicit_contract",
+                    "confidence": confidence,
+                    "note": (
+                        f"Co-change rate {confidence:.0%}"
+                        f" -- flagged by different scouts"
+                    ),
+                })
+
+    # Check graph edges between scout groups
+    graph_files = graph.files if hasattr(graph, 'files') else {}
+    for file_a in all_files:
+        node = graph_files.get(file_a)
+        if not node:
+            continue
+        imports = getattr(node, 'imports', []) or []
+        for dep in imports:
+            if dep in all_files:
+                scouts_a = set(file_scouts.get(file_a, []))
+                scouts_b = set(file_scouts.get(dep, []))
+                if scouts_a and scouts_b and not scouts_a & scouts_b:
+                    key = tuple(sorted([file_a, dep]))
+                    if key not in seen_connections:
+                        seen_connections.add(key)
+                        hidden_connections.append({
+                            "file_a": file_a,
+                            "file_b": dep,
+                            "relation": "direct_dependency",
+                            "confidence": 1.0,
+                            "note": f"{file_a} imports {dep}",
+                        })
+
+    # 3. Blast radius: expand via NPMI to find strongly coupled files
+    proposed_blast_radius = set(all_files)
+    npmi_index = invariants.get("npmi_index", {})
+    for filepath in list(all_files):
+        coupled_files = npmi_index.get(filepath, {})
+        for partner, score in coupled_files.items():
+            if score >= 0.8 and partner not in all_files:
+                proposed_blast_radius.add(partner)
+
+    # 4. Confidence tiers
+    blast_by_confidence: Dict[str, List[str]] = {
+        "high": [], "medium": [], "low": [],
+    }
+    for filepath in proposed_blast_radius:
+        scouts = file_scouts.get(filepath, [])
+        if len(scouts) >= 2:
+            blast_by_confidence["high"].append(filepath)
+        elif len(scouts) == 1:
+            scout_confidence = next(
+                (r.get("confidence", 0.5)
+                 for r in scout_reports
+                 if r.get("scout_id") in scouts),
+                0.5,
+            )
+            if scout_confidence >= 0.7:
+                blast_by_confidence["medium"].append(filepath)
+            else:
+                blast_by_confidence["low"].append(filepath)
+        else:
+            # NPMI-expanded files (not flagged by any scout)
+            blast_by_confidence["low"].append(filepath)
+
+    for tier in blast_by_confidence.values():
+        tier.sort()
+
+    # 5. Scout agreement
+    unanimous = sorted(f for f, s in file_scouts.items() if len(s) == n_scouts and n_scouts > 1)
+    majority = sorted(
+        f for f, s in file_scouts.items()
+        if n_scouts > 1 and len(s) > n_scouts / 2 and len(s) < n_scouts
+    )
+    single = sorted(f for f, s in file_scouts.items() if len(s) == 1)
+
+    return {
+        "convergence_points": convergence_points,
+        "hidden_connections": hidden_connections,
+        "proposed_blast_radius": sorted(proposed_blast_radius),
+        "blast_radius_by_confidence": blast_by_confidence,
+        "scout_agreement": {
+            "unanimous": unanimous,
+            "majority": majority,
+            "single": single,
+        },
+    }