skeletongraph 0.1.0__py3-none-any.whl

skeletongraph/__init__.py

@@ -0,0 +1,35 @@
+"""
+SkeletonGraph — Token-minimal, constraint-preserving context assembly for AI coding agents.
+
+Quick start:
+    from skeletongraph import SGEngine
+    from pathlib import Path
+
+    engine = SGEngine(Path("."))
+    result = engine.query("fix validate_token")
+    print(result.context_text)
+
+Features:
+    - 5-layer attention-aware SLM-orchestrated context assembly
+    - Elastic token budget with progressive compression
+    - Session memory for cross-turn context deduplication
+    - Per-directory constraint scoping
+    - 10-language support via Tree-sitter
+    - MCP server with 11 tools for IDE integration
+    - PR blast-radius analysis with risk scoring
+"""
+
+__version__ = "0.1.0"
+
+from .build import build_index, update_index
+from .engine import SGEngine
+from .config import SGConfig, load_config
+
+__all__ = [
+    "build_index",
+    "update_index",
+    "SGEngine",
+    "SGConfig",
+    "load_config",
+    "__version__",
+]

skeletongraph/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m skeletongraph`."""
+
+from .cli.main import app
+
+if __name__ == "__main__":
+    app()

skeletongraph/assembly/constraint_store.py

@@ -0,0 +1,301 @@
+"""
+Constraint store: hierarchical scoping + IDE rule aggregation + propose/confirm.
+
+Sources (three paths per the plan):
+  1. sg init --constraints "..." (init-arg)
+  2. IDE rule files aggregated at index time → constraints.md
+  3. Model-driven proposals via sg_constraint(action="propose")
+
+Constraints are stored in .skeletongraph/constraints.md with structured markers
+so SG can manage individual items (confirm/remove) while keeping the file
+human-readable and editable.
+
+Never strictly enforced — Zone 1 visibility is the mechanism.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+import time
+from pathlib import Path, PurePosixPath
+from typing import Dict, List, Optional
+
+
+# ── Constraint dataclass ─────────────────────────────────────────────────
+
+
+@dataclass
+class Constraint:
+    """Single constraint entry."""
+    id: str
+    text: str
+    provenance: str        # e.g. "CLAUDE.md", "init-arg", "model-proposed"
+    confirmed: bool = True
+
+    def to_block(self) -> str:
+        confirmed_str = "true" if self.confirmed else "false"
+        return (
+            f"<!-- sg:constraint id={self.id} confirmed={confirmed_str}"
+            f" provenance={self.provenance} -->\n"
+            f"{self.text.strip()}\n"
+            f"<!-- /sg:constraint -->"
+        )
+
+
+# ── ConstraintStore ──────────────────────────────────────────────────────
+
+
+class ConstraintStore:
+    """Hierarchical constraint manager with IDE rule aggregation.
+
+    Load once at build time, query per-file at assembly time.
+    The existing load()/get_constraints_for_file()/get_all_constraints() interface
+    is preserved for storage/local.py compatibility.
+    """
+
+    def __init__(self) -> None:
+        self._global_constraints: str = ""
+        self._scoped_constraints: Dict[str, str] = {}   # dir_path → raw text
+        self._items: List[Constraint] = []              # structured items
+
+    # ── Load / Save ──────────────────────────────────────────────────────
+
+    def load(self, project_root: Path) -> None:
+        """Scan project for constraint files and load them.
+
+        Looks for:
+          - {project_root}/.skeletongraph/constraints.md (global)
+          - {project_root}/<any_dir>/.skeletongraph/constraints.md (scoped)
+        """
+        global_file = project_root / ".skeletongraph" / "constraints.md"
+        if global_file.exists():
+            raw = global_file.read_text(encoding="utf-8", errors="replace").strip()
+            self._items = _parse_items(raw)
+            self._global_constraints = raw
+
+        for constraints_file in project_root.rglob(".skeletongraph/constraints.md"):
+            if constraints_file == global_file:
+                continue
+            sg_dir = constraints_file.parent
+            scope_dir = sg_dir.parent
+            rel_scope = scope_dir.relative_to(project_root).as_posix()
+            self._scoped_constraints[rel_scope] = constraints_file.read_text(
+                encoding="utf-8", errors="replace"
+            ).strip()
+
+    def save_global(self, project_root: Path) -> None:
+        """Persist global constraints to disk."""
+        sg_dir = project_root / ".skeletongraph"
+        sg_dir.mkdir(parents=True, exist_ok=True)
+        target = sg_dir / "constraints.md"
+        # Rebuild from structured items + any free-form preamble
+        blocks = [item.to_block() for item in self._items]
+        target.write_text("\n\n".join(blocks) + "\n", encoding="utf-8")
+        self._global_constraints = target.read_text(encoding="utf-8")
+
+    # ── Query interface (used by assembly) ───────────────────────────────
+
+    def get_constraints_for_file(self, file_path: str) -> str:
+        """Get merged constraints for a specific file (global + scoped)."""
+        parts = []
+
+        confirmed_text = self._confirmed_text()
+        if confirmed_text:
+            parts.append(confirmed_text)
+
+        file_dir = str(PurePosixPath(file_path).parent)
+        for scope_dir, constraints in sorted(self._scoped_constraints.items()):
+            if file_dir == scope_dir or file_dir.startswith(scope_dir + "/"):
+                parts.append(f"# [{scope_dir}/ scope]\n{constraints}")
+
+        return "\n\n".join(parts)
+
+    def get_all_constraints(self) -> str:
+        """Get confirmed global constraints. Used when file scope is unknown."""
+        return self._confirmed_text() or self._global_constraints
+
+    def get_all_for_overview(self) -> str:
+        """Human-readable list for sg_overview Zone 1, includes proposed."""
+        if not self._items:
+            return self._global_constraints
+        lines = []
+        for item in self._items:
+            prefix = "✓" if item.confirmed else "?"
+            lines.append(f"[{prefix}] ({item.provenance}) {item.text.strip()}")
+        return "\n".join(lines)
+
+    @property
+    def has_constraints(self) -> bool:
+        return bool(self._global_constraints) or bool(self._scoped_constraints)
+
+    @property
+    def scope_count(self) -> int:
+        return len(self._scoped_constraints)
+
+    # ── CRUD ─────────────────────────────────────────────────────────────
+
+    def add_constraint(
+        self,
+        text: str,
+        provenance: str = "manual",
+        confirmed: bool = True,
+    ) -> Constraint:
+        """Add a confirmed constraint (from init-arg or manual CLI)."""
+        cid = _make_id(text)
+        c = Constraint(id=cid, text=text.strip(), provenance=provenance, confirmed=confirmed)
+        self._items.append(c)
+        return c
+
+    def propose_constraint(self, text: str, source: str = "model-proposed") -> Constraint:
+        """Add an unconfirmed proposal (from sg_constraint action=propose)."""
+        return self.add_constraint(text, provenance=source, confirmed=False)
+
+    def confirm_constraint(
+        self,
+        constraint_id: str,
+        project_root: Optional[Path] = None,
+    ) -> bool:
+        """Mark a proposed constraint as confirmed. Returns True if found.
+
+        If project_root is given, also promotes to decisions.md.
+        """
+        for item in self._items:
+            if item.id == constraint_id or item.id.startswith(constraint_id):
+                item.confirmed = True
+                if project_root is not None:
+                    _promote_to_decisions(item, project_root)
+                return True
+        return False
+
+    def remove_constraint(self, constraint_id: str) -> bool:
+        """Remove a constraint by id. Returns True if found."""
+        before = len(self._items)
+        self._items = [
+            c for c in self._items
+            if not (c.id == constraint_id or c.id.startswith(constraint_id))
+        ]
+        return len(self._items) < before
+
+    def list_constraints(self, include_proposed: bool = True) -> List[Constraint]:
+        """Return all constraints, optionally filtering out proposals."""
+        if include_proposed:
+            return list(self._items)
+        return [c for c in self._items if c.confirmed]
+
+    # ── IDE rule aggregation ──────────────────────────────────────────────
+
+    def aggregate_from_ide_rules(self, project_root: Path) -> int:
+        """Scan IDE rule files and import their content as confirmed constraints.
+
+        Files checked (in order):
+          CLAUDE.md, AGENTS.md, .github/copilot-instructions.md,
+          .windsurfrules, .roorules, .rules,
+          .cursor/rules/*.mdc  (all matched)
+
+        Returns number of new constraints added.
+        """
+        sources: List[tuple[str, Path]] = [
+            ("CLAUDE.md", project_root / "CLAUDE.md"),
+            ("AGENTS.md", project_root / "AGENTS.md"),
+            ("copilot-instructions.md", project_root / ".github" / "copilot-instructions.md"),
+            (".windsurfrules", project_root / ".windsurfrules"),
+            (".roorules", project_root / ".roorules"),
+            (".rules", project_root / ".rules"),
+        ]
+
+        # .cursor/rules/*.mdc — all files
+        cursor_rules_dir = project_root / ".cursor" / "rules"
+        if cursor_rules_dir.exists():
+            for mdc in sorted(cursor_rules_dir.glob("*.mdc")):
+                sources.append((f".cursor/rules/{mdc.name}", mdc))
+
+        added = 0
+        existing_texts = {c.text.strip() for c in self._items}
+
+        for provenance, path in sources:
+            if not path.exists():
+                continue
+            text = path.read_text(encoding="utf-8", errors="replace").strip()
+            if not text:
+                continue
+            # Deduplicate — skip if same text already stored
+            if text in existing_texts:
+                continue
+            c = Constraint(
+                id=_make_id(text),
+                text=text,
+                provenance=provenance,
+                confirmed=True,
+            )
+            self._items.append(c)
+            existing_texts.add(text)
+            added += 1
+
+        return added
+
+    # ── Legacy helpers ────────────────────────────────────────────────────
+
+    def set_global(self, text: str) -> None:
+        """Set global constraints programmatically (for API/test use)."""
+        self._global_constraints = text.strip()
+        # Also parse items from provided text
+        self._items = _parse_items(text)
+
+    # ── Internal ──────────────────────────────────────────────────────────
+
+    def _confirmed_text(self) -> str:
+        confirmed = [c.text.strip() for c in self._items if c.confirmed]
+        return "\n\n".join(confirmed)
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────
+
+
+def _make_id(text: str) -> str:
+    """Stable 8-char id from text hash."""
+    return hashlib.sha1(text.strip().encode()).hexdigest()[:8]
+
+
+_BLOCK_RE = re.compile(
+    r"<!-- sg:constraint\s+id=(\S+)\s+confirmed=(\S+)\s+provenance=(\S+)\s*-->\n(.*?)\n<!-- /sg:constraint -->",
+    re.DOTALL,
+)
+
+
+def _promote_to_decisions(item: Constraint, project_root: Path) -> None:
+    """Append a confirmed constraint to decisions.md as a persistent decision record."""
+    sg_dir = project_root / ".skeletongraph"
+    sg_dir.mkdir(parents=True, exist_ok=True)
+    decisions_path = sg_dir / "decisions.md"
+
+    date_str = time.strftime("%Y-%m-%d")
+    entry = (
+        f"\n## [{item.id}] {date_str}  —  {item.provenance}\n\n"
+        f"{item.text.strip()}\n"
+    )
+
+    if decisions_path.exists():
+        existing = decisions_path.read_text(encoding="utf-8", errors="replace")
+        # Skip if already promoted
+        if item.id in existing:
+            return
+        decisions_path.write_text(existing.rstrip() + "\n" + entry, encoding="utf-8")
+    else:
+        header = "# Decisions\n\nPromoted constraints and architectural decisions.\n"
+        decisions_path.write_text(header + entry, encoding="utf-8")
+
+
+def _parse_items(raw: str) -> List[Constraint]:
+    """Parse structured constraint blocks from constraints.md text."""
+    items = []
+    for m in _BLOCK_RE.finditer(raw):
+        cid, confirmed_str, provenance, text = m.groups()
+        items.append(Constraint(
+            id=cid,
+            text=text.strip(),
+            provenance=provenance,
+            confirmed=(confirmed_str.lower() == "true"),
+        ))
+    return items

skeletongraph/assembly/context_routing.py

@@ -0,0 +1,173 @@
+"""Smart context routing — pick which MD files / sections to include per prompt.
+
+The full context is expensive: constraints + architecture + project + session digest
++ top functions adds 1k–3k tokens to every prompt. Most prompts don't need all of it.
+
+This module classifies the prompt by keyword family and returns ONLY the sections
+that actually help for that kind of task.
+
+Always-on:
+  • constraints (compact)        — Zone 1, never skip
+  • session digest (5 turns)     — short, useful for continuity
+
+Conditional:
+  • architecture.md              — for design/refactor/migrate/explain queries
+  • project.md                   — for "what is this codebase" queries
+  • decisions.md                 — for "why did we..." queries
+
+This is heuristic — no LLM call — so it's cheap to run on every hook invocation.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+# Keyword families. Order matters — first match wins for the primary mode.
+_KEYWORD_FAMILIES: List[Tuple[str, List[str]]] = [
+    (
+        "architecture",
+        [
+            "architecture", "architect", "design", "structure", "organize",
+            "refactor", "restructure", "migrate", "module", "layer", "pattern",
+            "dependency", "coupling", "abstraction",
+        ],
+    ),
+    (
+        "explain",
+        [
+            "what is", "what does", "explain", "describe", "overview",
+            "how does this", "walk me through", "tell me about",
+        ],
+    ),
+    (
+        "decision",
+        [
+            "why did", "why do we", "why are we", "rationale", "history of",
+            "decision", "tradeoff", "trade-off",
+        ],
+    ),
+    (
+        "debug",
+        [
+            "fix", "bug", "broken", "error", "fail", "crash", "exception",
+            "traceback", "regression", "wrong", "not working",
+        ],
+    ),
+    (
+        "test",
+        [
+            "test", "coverage", "spec", "pytest", "unittest", "mock", "fixture",
+        ],
+    ),
+    (
+        "review",
+        [
+            "review", "audit", "check", "validate", "inspect", "lint",
+            "security", "vulnerability",
+        ],
+    ),
+]
+
+# Section name → (filename, max_chars)
+_SECTION_FILES: Dict[str, Tuple[str, int]] = {
+    "architecture": ("architecture.md", 3200),   # ~800 tokens
+    "project":      ("project.md", 1600),        # ~400 tokens
+    "decisions":    ("decisions.md", 2400),      # ~600 tokens
+}
+
+
+def classify_prompt(prompt: str) -> str:
+    """Return the primary keyword family for a prompt.
+
+    Returns 'general' if no family matches.
+    """
+    p = (prompt or "").lower()
+    if not p.strip():
+        return "general"
+    for family, keywords in _KEYWORD_FAMILIES:
+        for kw in keywords:
+            # Word-boundary for single words; phrase match for multi-word
+            if " " in kw:
+                if kw in p:
+                    return family
+            else:
+                if re.search(rf"\b{re.escape(kw)}\b", p):
+                    return family
+    return "general"
+
+
+def route_context_sections(
+    prompt: str,
+    sg_dir: Path,
+) -> Dict[str, str]:
+    """Pick which optional MD sections to include, based on prompt classification.
+
+    Returns:
+        Dict mapping section_name → trimmed content. May be empty for general queries.
+        Caller is responsible for actually injecting these sections into the
+        prompt/overview output.
+
+    Always-on sections (constraints, session digest, top functions) are NOT
+    handled here — they're always included by the hook/tool caller.
+    """
+    sections: Dict[str, str] = {}
+    family = classify_prompt(prompt)
+
+    if family == "architecture":
+        _add_section(sections, "architecture", sg_dir)
+
+    elif family == "explain":
+        # "what is this codebase" — include project + architecture (short)
+        _add_section(sections, "project", sg_dir)
+        _add_section(sections, "architecture", sg_dir, char_override=1600)
+
+    elif family == "decision":
+        _add_section(sections, "decisions", sg_dir)
+
+    # debug / test / review / general: no extra MD — constraints + session +
+    # top functions are usually enough. The caller adds those unconditionally.
+
+    return sections
+
+
+def _add_section(
+    sections: Dict[str, str],
+    key: str,
+    sg_dir: Path,
+    char_override: int = 0,
+) -> None:
+    """Read the MD file for `key`, trim, store under sections[key]."""
+    if key not in _SECTION_FILES:
+        return
+    filename, default_chars = _SECTION_FILES[key]
+    cap = char_override or default_chars
+    path = sg_dir / filename
+    if not path.exists():
+        return
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace").strip()
+        if not text:
+            return
+        if len(text) > cap:
+            text = text[:cap].rstrip() + "\n... (truncated)"
+        sections[key] = text
+    except Exception:
+        pass
+
+
+def format_routed_sections(sections: Dict[str, str]) -> str:
+    """Render routed sections as markdown blocks. Returns '' if empty."""
+    if not sections:
+        return ""
+    parts = []
+    titles = {
+        "architecture": "## Architecture",
+        "project":      "## Project",
+        "decisions":    "## Decisions",
+    }
+    for key, text in sections.items():
+        title = titles.get(key, f"## {key.title()}")
+        parts.append(f"{title}\n{text}")
+    return "\n\n".join(parts)

skeletongraph/assembly/modifier.py

@@ -0,0 +1,130 @@
+"""
+Mode modifiers: reasoning instructions injected into assembled context.
+
+7 modifiers total:
+  - 6 instruction-level (text appended near top of context)
+  - 1 API-level (EXTENDED_THINKING — flag only, not text)
+
+Modifiers shape HOW the LLM reasons, not WHAT it sees.
+Selected automatically by classifier.py. Max 2 instruction-level per query.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+# ── Modifier Templates ──────────────────────────────────────────────────
+# Each is ~60-100 tokens. Placed at position 3 in assembly
+# (after task + constraints, before session/architecture/code).
+
+MODIFIER_TEMPLATES: Dict[str, str] = {
+    "BRAINSTORM": (
+        "## Reasoning Mode: Brainstorm\n"
+        "Before recommending an approach:\n"
+        "1. Generate at least 3 distinct approaches, including at least one you'd normally dismiss\n"
+        "2. For each: state the core tradeoff, not just pros/cons\n"
+        "3. Flag which approach fits best given the constraints above and WHY\n"
+        "4. Only then give a recommendation\n"
+        "\n"
+        "Do not recommend the first approach you think of. The right answer for this\n"
+        "project may not be the obvious one."
+    ),
+
+    "BLAST_FIRST": (
+        "## Reasoning Mode: Blast-First\n"
+        "Before making any changes:\n"
+        "1. List every caller, consumer, and dependent of the code being refactored\n"
+        "2. For each: state whether the change will break it, may break it, or is safe\n"
+        "3. Identify the highest-risk change (most callers, least test coverage)\n"
+        "4. Start with the highest-risk change and confirm approach before proceeding\n"
+        "\n"
+        "Do not write code until the blast radius analysis is complete."
+    ),
+
+    "VERIFY_ASSUMPTIONS": (
+        "## Reasoning Mode: Verify Assumptions\n"
+        "Before diagnosing:\n"
+        "1. List at least 3 possible causes, ordered by likelihood given recent changes\n"
+        "2. For each cause: what evidence would confirm or rule it out?\n"
+        "3. Check the evidence available in the context above\n"
+        "4. Only after ruling out alternatives: state your diagnosis\n"
+        "\n"
+        "The most obvious cause is often not the actual cause in debugging.\n"
+        "Favor hypotheses that explain the symptoms given RECENT CHANGES (see session memory)."
+    ),
+
+    "STEP_COMMIT": (
+        "## Reasoning Mode: Step-Commit\n"
+        "This is a multi-step implementation. Use this process:\n"
+        "1. State the implementation plan (files to create/modify, order of changes)\n"
+        "2. Wait for confirmation before writing code (just state the plan first)\n"
+        "3. Implement one logical unit at a time\n"
+        "4. After each unit: state what's complete, what's next, what could break\n"
+        "\n"
+        "Do not attempt to implement everything in one response.\n"
+        "A correct partial implementation is better than a broken complete one."
+    ),
+
+    "MINIMAL": (
+        "## Reasoning Mode: Minimal Change\n"
+        "Make the smallest correct change that achieves the goal.\n"
+        "Do not refactor surrounding code unless it's required for correctness.\n"
+        "Do not improve unrelated things you notice.\n"
+        "If you see something that should be fixed but is out of scope, note it briefly — don't fix it."
+    ),
+
+    "THINK_ALOUD": (
+        "## Reasoning Mode: Think Aloud\n"
+        "For this task, show your reasoning before your answer:\n"
+        "- What are you uncertain about?\n"
+        "- What assumptions are you making?\n"
+        "- What would change your answer if it turned out to be wrong?\n"
+        "\n"
+        "Keep reasoning concise. The goal is to surface hidden assumptions,\n"
+        "not to write an essay. Then give your answer."
+    ),
+}
+
+# EXTENDED_THINKING is NOT a template — it's an API-level flag.
+# The assembler sets metadata.extended_thinking = True.
+# The caller (MCP server, hook, CLI) uses the flag if the model supports it.
+# Trigger: PLANNING or DEBUG_INVESTIGATE + cross_file > 3 or dep_depth > 3.
+# Only works for: Claude Code API-direct, sg-agent, sg prompt → Claude.ai.
+# Does NOT work for: Cursor, Copilot, Antigravity (they control the API call).
+
+
+def render_modifiers(modifier_names: List[str]) -> str:
+    """Render selected modifiers into a single text block for context injection.
+
+    Args:
+        modifier_names: List of modifier names (e.g., ["BRAINSTORM", "THINK_ALOUD"])
+
+    Returns:
+        Combined modifier text, or empty string if no modifiers.
+        EXTENDED_THINKING is silently skipped (it's API-level, not text).
+    """
+    parts = []
+    for name in modifier_names:
+        if name == "EXTENDED_THINKING":
+            continue  # API-level, not rendered as text
+        template = MODIFIER_TEMPLATES.get(name)
+        if template:
+            parts.append(template)
+
+    if not parts:
+        return ""
+
+    return "\n\n".join(parts)
+
+
+def estimate_modifier_tokens(modifier_names: List[str]) -> int:
+    """Estimate token count for selected modifiers.
+
+    Rough estimate: ~4 chars per token for English instruction text.
+    """
+    text = render_modifiers(modifier_names)
+    if not text:
+        return 0
+    # ~4 chars per token is a conservative estimate for English instructions
+    return len(text) // 4