degraph 1.0.0__py3-none-any.whl

deg/__init__.py

@@ -0,0 +1,7 @@
+"""DEG: Decision-Evidence Graph — traceable, challengeable decision provenance for AI agents."""
+
+from deg.graph import Graph
+from deg.schemas import Decision, Evidence, State
+
+__version__ = "1.0.0"
+__all__ = ["Graph", "Decision", "Evidence", "State"]

deg/cli.py

@@ -0,0 +1,469 @@
+"""CLI interface for DEG: deg init, decide, evidence, status, challenge, compile."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+import yaml
+
+
+@click.group()
+def main():
+    """DEG: Decision-Evidence Graph — traceable decision provenance for AI agents."""
+    pass
+
+
+@main.command()
+@click.option("--goal", "-g", default="", help="Project goal")
+@click.option("--phase", "-p", default="", help="Current phase")
+def init(goal: str, phase: str):
+    """Initialize DEG structure in current directory."""
+    from deg.graph import Graph
+    g = Graph(Path.cwd())
+    g.init(project_goal=goal, current_phase=phase)
+    click.echo(f"✅ DEG initialized in {Path.cwd()}")
+    click.echo(f"   Created: decisions/ evidence/ .deg/")
+
+
+@main.command()
+@click.argument("title")
+@click.option("--evidence", "-e", multiple=True, help="Evidence IDs that inform this decision")
+@click.option("--revalidation", "-r", default=30, type=int, help="Days before revalidation")
+@click.option("--scope", "-s", default="", help="Scope of this decision")
+@click.option("--context", "-c", default="", help="Context for why this was needed")
+def decide(title: str, evidence: tuple, revalidation: int, scope: str, context: str):
+    """Record a decision with provenance."""
+    from deg.graph import Graph
+    g = Graph()
+    deg_id = g.decide(
+        title=title,
+        evidence=list(evidence) if evidence else None,
+        revalidation_days=revalidation,
+        scope=scope,
+        context=context,
+    )
+    click.echo(f"✅ Decision recorded: {deg_id}")
+    click.echo(f"   Title: {title}")
+    if evidence:
+        click.echo(f"   Evidence: {', '.join(evidence)}")
+
+
+@main.command()
+@click.argument("claim")
+@click.option("--source", "-s", default="", help="Source reference")
+@click.option("--confidence", "-c", default=0.8, type=float, help="Confidence 0-1")
+@click.option("--type", "source_type", default="literature", help="Source type: literature|experiment|observation|derived")
+@click.option("--invalidates", "-i", default=None, help="Evidence ID this supersedes")
+@click.option("--informs", multiple=True, help="Decision IDs this informs")
+def evidence(claim: str, source: str, confidence: float, source_type: str, invalidates: str, informs: tuple):
+    """Record an evidence finding."""
+    from deg.graph import Graph
+    g = Graph()
+    deg_id = g.evidence(
+        claim=claim,
+        source=source,
+        confidence=confidence,
+        source_type=source_type,
+        invalidates=invalidates,
+        informs=list(informs) if informs else None,
+    )
+    click.echo(f"✅ Evidence recorded: {deg_id}")
+    click.echo(f"   Claim: {claim}")
+    if invalidates:
+        click.echo(f"   ⚠️  Invalidates: {invalidates}")
+
+
+@main.command()
+def status():
+    """Show project state, stale alerts, and active decisions."""
+    from deg.graph import Graph
+    g = Graph()
+    s = g.status()
+    click.echo(yaml.dump(s, default_flow_style=False, sort_keys=False))
+
+
+@main.command()
+@click.argument("decision_id")
+def challenge(decision_id: str):
+    """Revalidation assessment for a decision."""
+    from deg.graph import Graph
+    g = Graph()
+    result = g.challenge(decision_id)
+    click.echo(yaml.dump(result, default_flow_style=False, sort_keys=False))
+
+
+@main.command()
+@click.argument("node_id")
+def trace(node_id: str):
+    """Trace provenance chain for a node."""
+    from deg.graph import Graph
+    g = Graph()
+    chain = g.trace(node_id)
+    for item in chain:
+        indent = "  " * item.get("depth", 0)
+        click.echo(f"{indent}{'→ ' if item['depth'] > 0 else ''}{item['id']} [{item.get('type', '')}] {item.get('title', '')}")
+
+
+@main.command(name="impact")
+@click.argument("node_id")
+def impact_cmd(node_id: str):
+    """Show cascade impact if a node changes."""
+    from deg.graph import Graph
+    g = Graph()
+    affected = g.impact(node_id)
+    if affected:
+        click.echo(f"⚠️  {len(affected)} downstream nodes affected:")
+        for nid in affected:
+            click.echo(f"   → {nid}")
+    else:
+        click.echo("✅ No downstream dependencies.")
+
+
+@main.command(name="search")
+@click.argument("query")
+@click.option("-k", default=5, type=int, help="Number of results")
+def search_cmd(query: str, k: int):
+    """Search across decisions and evidence."""
+    from deg.graph import Graph
+    g = Graph()
+    results = g.search(query, k=k)
+    if results:
+        for r in results:
+            click.echo(f"  {r['id']} [{r.get('type', '')}] {r.get('title', '')}")
+    else:
+        click.echo("No results found.")
+
+
+@main.command()
+def compile():
+    """Rebuild .deg/ compiled graph from source markdown."""
+    from deg.graph import Graph
+    g = Graph()
+    result = g.compile()
+    click.echo(f"✅ Compiled: {result['nodes']} nodes, {result['edges']} edges → {result['path']}")
+    if result["errors"]:
+        for e in result["errors"]:
+            click.echo(f"   ⚠️  {e}")
+
+
+@main.command()
+@click.argument("summary")
+@click.option("--next", "next_actions", multiple=True, help="Next actions for the following session")
+@click.option("--agent", default="", help="Agent identifier")
+def close(summary: str, next_actions: tuple, agent: str):
+    """Close session and update STATE.yaml for handoff."""
+    from deg.graph import Graph
+    g = Graph()
+    state = g.close_session(summary, list(next_actions) if next_actions else None, agent)
+    click.echo("✅ Session closed. STATE.yaml updated.")
+    click.echo(f"   Summary: {summary}")
+
+
+@main.command()
+@click.argument("option")
+@click.option("--decision", "-d", required=True, help="Decision ID to add rejection to")
+@click.option("--because", "-b", required=True, help="Why this was rejected")
+@click.option("--reconsider-if", "-r", default=None, help="Condition to reconsider")
+def reject(option: str, decision: str, because: str, reconsider_if: str | None):
+    """Record a rejected alternative for a decision."""
+    from deg.graph import Graph
+    g = Graph()
+    g.reject(option, decision, because, reconsider_if)
+    click.echo(f"✅ Rejected '{option}' for {decision}")
+    if reconsider_if:
+        click.echo(f"   Reconsider if: {reconsider_if}")
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--root", default=None, help="DEG project root")
+def ingest(path: str, root: str | None):
+    """Ingest existing markdown file(s) into DEG (heuristic, no LLM)."""
+    from pathlib import Path as P
+    from deg.ingest import ingest_file, ingest_directory
+    from deg.graph import Graph
+
+    target = P(path)
+    project_root = P(root) if root else None
+
+    if target.is_file():
+        result = ingest_file(target, project_root)
+        click.echo(f"✅ Ingested {result['file']} → D:{result.get('decision_id', '?')} E:{result.get('evidence_id', '?')}")
+    elif target.is_dir():
+        results = ingest_directory(target, project_root)
+        success = [r for r in results if "error" not in r]
+        errors = [r for r in results if "error" in r]
+        click.echo(f"✅ Ingested {len(success)} files from {target}")
+        for e in errors:
+            click.echo(f"   ⚠️  {e['file']}: {e['error']}")
+    else:
+        click.echo(f"❌ {path} is not a file or directory")
+
+
+@main.command()
+@click.option("--global", "global_install", is_flag=True, help="Install globally for all projects")
+def setup(global_install: bool):
+    """Set up DEG as a Claude Code skill in this project.
+
+    Configures: CLAUDE.md instructions, MCP server, hooks for auto-capture.
+    After setup, Claude Code will auto-record decisions during conversations.
+    """
+    from deg.setup import setup_project
+    result = setup_project(global_install=global_install)
+    click.echo(f"✅ DEG skill configured in {result['root']}")
+    for action in result['actions']:
+        click.echo(f"   • {action}")
+    click.echo()
+    click.echo("Next steps:")
+    click.echo("   1. Restart Claude Code in this project")
+    click.echo("   2. Claude will auto-load DEG status at session start")
+    click.echo("   3. Claude will auto-record decisions via MCP tools")
+
+
+@main.command()
+def digest():
+    """Print staleness digest: stale decisions with actionable research suggestions."""
+    from deg.graph import Graph
+    g = Graph()
+    s = g.status()
+    stale_alerts = s.get("stale_alerts", [])
+
+    if not stale_alerts:
+        click.echo("All decisions current. No action needed.")
+        return
+
+    click.echo("## DEG Staleness Digest\n")
+
+    for alert in stale_alerts:
+        node_id = alert.get("id", alert.get("node_id", ""))
+        if not node_id:
+            continue
+
+        # Get full challenge info
+        challenge_info = g.challenge(node_id)
+        if "error" in challenge_info:
+            continue
+
+        title = challenge_info.get("title", "")
+        health = challenge_info.get("health", {})
+        evidence_validity = challenge_info.get("evidence_validity", {})
+        alternatives = challenge_info.get("alternatives", {})
+
+        # Determine staleness description from triggers
+        triggers = alert.get("triggers", [])
+        days_overdue = "?"
+        for trig in triggers:
+            reason = trig.get("reason", "")
+            # Extract days from reason like "40 days since last verification (threshold: 1)"
+            if "days since" in reason:
+                try:
+                    days_overdue = reason.split(" days")[0].strip()
+                except (IndexError, ValueError):
+                    pass
+
+        health_label = health.get("health", "unknown")
+        wlnk = health.get("confidence", "?")
+        weakest_link = health.get("weakest_link")
+
+        click.echo(f"### ⚠️ {node_id}: {title}")
+        click.echo(f"- **Stale since:** {days_overdue} days past revalidation")
+        click.echo(f"- **Health:** {health_label} (WLNK: {wlnk})")
+
+        # Find weakest evidence
+        if weakest_link and weakest_link in evidence_validity:
+            ev_info = evidence_validity[weakest_link]
+            click.echo(f"- **Weakest evidence:** {weakest_link} (confidence: {ev_info.get('confidence', '?')})")
+        elif weakest_link:
+            click.echo(f"- **Weakest evidence:** {weakest_link}")
+
+        # Alternatives
+        if alternatives:
+            click.echo("- **Alternatives to reconsider:**")
+            for opt, info in alternatives.items():
+                reconsider = info.get("reconsider_if", "")
+                if reconsider:
+                    click.echo(f"  - {opt} — reconsider if: {reconsider}")
+                else:
+                    click.echo(f"  - {opt}")
+
+        # Research suggestions
+        cr = g.continue_research(node_id)
+        if cr and "message" not in cr:
+            searches = cr.get("next_searches", cr.get("search_terms", []))
+            if searches:
+                click.echo(f"- **Suggested research:** {', '.join(searches)}")
+        click.echo()
+
+    # Show valid decisions
+    all_decisions = [nid for nid, n in g._nodes.items() if n.get("type") == "decision"]
+    stale_ids = {a.get("id", a.get("node_id", "")) for a in stale_alerts}
+    valid_decisions = [d for d in all_decisions if d not in stale_ids and g._nodes[d].get("status") == "active"]
+
+    if valid_decisions:
+        click.echo("### ✅ No action needed")
+        for d_id in valid_decisions:
+            node = g._nodes[d_id]
+            click.echo(f"- {d_id}: still valid")
+
+
+@main.command()
+@click.option("--last", "last_n", default=10, type=int, help="Number of recent entries to show")
+def timeline(last_n: int):
+    """Print chronological decision history with supporting evidence."""
+    from deg.graph import Graph
+    g = Graph()
+
+    if not g._nodes:
+        click.echo("No nodes found.")
+        return
+
+    # Collect all decisions, sorted by created date descending
+    decisions = []
+    for nid, node in g._nodes.items():
+        if node.get("type") != "decision":
+            continue
+        created = node.get("created", node.get("created_at", ""))
+        decisions.append((str(created), nid, node))
+
+    decisions.sort(key=lambda x: x[0], reverse=True)
+    decisions = decisions[:last_n]
+
+    if not decisions:
+        click.echo("No decisions found.")
+        return
+
+    for created_str, nid, node in decisions:
+        status = node.get("status", "active")
+        title = node.get("title", "")
+        click.echo(f"{created_str}  {nid} [{status}]     {title}")
+
+        # Show supporting evidence
+        for ev_id in node.get("informed_by", []):
+            ev = g._nodes.get(ev_id)
+            if ev:
+                conf = ev.get("confidence", "?")
+                claim = ev.get("claim", "")
+                click.echo(f"             ← {ev_id} ({conf}) {claim}")
+
+
+@main.command()
+@click.option("--root", default=None, help="Project root (default: CWD)")
+def serve(root: str | None):
+    """Start MCP server for AI agent integration."""
+    import asyncio
+    try:
+        from deg.mcp_server import run_server
+        click.echo("🚀 DEG MCP server starting (stdio mode)...")
+        click.echo("   Connect via Claude Code, Cursor, or any MCP client.")
+        asyncio.run(run_server(root))
+    except ImportError:
+        click.echo("❌ MCP not installed. Run: pip install deg[mcp]")
+        raise SystemExit(1)
+
+
+@main.command()
+@click.option("--git", is_flag=True, help="Check git-diff staleness (files referenced by decisions changed)")
+@click.option("--staged", is_flag=True, help="Check staged files only (pre-commit hook compatible)")
+def check(git, staged):
+    """Run constraint checks on the decision graph. Exit code 1 if errors found."""
+    import sys
+    from deg.graph import Graph
+    from deg.constraints import run_all_checks
+    from deg.staleness import check_git_staleness, check_staged_staleness
+
+    g = Graph()
+
+    if not g._nodes:
+        click.echo("No nodes found. Graph is empty — all checks pass.")
+        return
+
+    violations = run_all_checks(g._nodes, g._edges)
+
+    staleness_findings = []
+    if git:
+        staleness_findings.extend(check_git_staleness(g.root, g._nodes))
+    if staged:
+        staleness_findings.extend(check_staged_staleness(g.root, g._nodes))
+
+    # Group violations by severity
+    errors = [v for v in violations if v.severity == "error"]
+    warnings = [v for v in violations if v.severity == "warning"]
+    infos = [v for v in violations if v.severity == "info"]
+
+    has_errors = len(errors) > 0
+
+    if not violations and not staleness_findings:
+        click.echo("All checks pass.")
+        return
+
+    # Print errors first
+    if errors:
+        click.echo(click.style(f"\n{'ERROR'} ({len(errors)}):", fg="red", bold=True))
+        for v in errors:
+            click.echo(click.style(f"  ✗ {v.message}", fg="red"))
+
+    if warnings:
+        click.echo(click.style(f"\n{'WARNING'} ({len(warnings)}):", fg="yellow", bold=True))
+        for v in warnings:
+            click.echo(click.style(f"  ⚠ {v.message}", fg="yellow"))
+
+    if infos:
+        click.echo(click.style(f"\n{'INFO'} ({len(infos)}):", fg="blue"))
+        for v in infos:
+            click.echo(f"  ℹ {v.message}")
+
+    if staleness_findings:
+        click.echo(click.style(f"\n{'STALENESS'} ({len(staleness_findings)}):", fg="magenta", bold=True))
+        for sf in staleness_findings:
+            click.echo(f"  → {sf.get('decision_id', '?')}: {sf.get('reason', '?')} [{', '.join(sf.get('changed_files', []))}]")
+
+    # Summary
+    total = len(violations) + len(staleness_findings)
+    click.echo(f"\n{total} finding(s): {len(errors)} error, {len(warnings)} warning, {len(infos)} info, {len(staleness_findings)} staleness")
+
+    if has_errors:
+        sys.exit(1)
+
+
+@main.command()
+def maintenance():
+    """Run self-maintenance checks: orphans, duplicates, cycles, stale items."""
+    from deg.graph import Graph
+    from deg.maintenance import run_maintenance
+
+    g = Graph()
+
+    if not g._nodes:
+        click.echo("No nodes found. Graph is empty — nothing to maintain.")
+        return
+
+    findings = run_maintenance(g._nodes, g._edges)
+
+    if not findings:
+        click.echo("Graph is healthy. No maintenance issues found.")
+        return
+
+    # Group by category
+    categories = {}
+    for f in findings:
+        cat = f.category if hasattr(f, "category") else "other"
+        categories.setdefault(cat, []).append(f)
+
+    total = len(findings)
+    click.echo(f"Found {total} maintenance issue(s):\n")
+
+    for cat, items in categories.items():
+        click.echo(click.style(f"  {cat.upper()} ({len(items)}):", bold=True))
+        for item in items:
+            msg = item.message if hasattr(item, "message") else str(item)
+            suggestion = item.suggestion if hasattr(item, "suggestion") else ""
+            click.echo(f"    • {msg}")
+            if suggestion:
+                click.echo(click.style(f"      → {suggestion}", fg="cyan"))
+        click.echo()
+
+
+if __name__ == "__main__":
+    main()

deg/compiler.py

@@ -0,0 +1,143 @@
+"""Compile markdown decision/evidence files into the .deg/ sidecar graph."""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from pathlib import Path
+
+import yaml
+
+from deg.schemas import Decision, Evidence
+
+
+def parse_frontmatter(path: Path) -> dict | None:
+    """Extract YAML frontmatter from a markdown file."""
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        return None
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return None
+    try:
+        meta = yaml.safe_load(parts[1])
+    except yaml.YAMLError:
+        return None
+    if not isinstance(meta, dict):
+        return None
+    meta["_body"] = parts[2].strip()
+    meta["_file"] = str(path)
+    return meta
+
+
+def compile_graph(project_root: Path) -> dict:
+    """Parse all markdown files, build graph structures, write .deg/ directory."""
+    decisions_dir = project_root / "decisions"
+    evidence_dir = project_root / "evidence"
+    deg_dir = project_root / ".deg"
+    deg_dir.mkdir(exist_ok=True)
+
+    nodes: dict[str, dict] = {}
+    edges: list[dict] = []
+    successors: dict[str, list[str]] = defaultdict(list)
+    errors: list[str] = []
+
+    # Parse decisions
+    if decisions_dir.exists():
+        for md_file in sorted(decisions_dir.glob("*.md")):
+            meta = parse_frontmatter(md_file)
+            if meta is None:
+                errors.append(f"Cannot parse: {md_file}")
+                continue
+            node_id = meta.get("deg_id", md_file.stem)
+            nodes[node_id] = meta
+
+    # Parse evidence
+    if evidence_dir.exists():
+        for md_file in sorted(evidence_dir.glob("*.md")):
+            meta = parse_frontmatter(md_file)
+            if meta is None:
+                errors.append(f"Cannot parse: {md_file}")
+                continue
+            node_id = meta.get("deg_id", md_file.stem)
+            nodes[node_id] = meta
+
+    # Build edges from relationships
+    for node_id, meta in nodes.items():
+        # informed_by edges (decision → evidence)
+        for target_id in meta.get("informed_by", []):
+            edges.append({"from": node_id, "to": target_id, "type": "informed_by"})
+            successors[target_id].append(node_id)
+
+        # depends_on edges (decision → decision)
+        for target_id in meta.get("depends_on", []):
+            edges.append({"from": node_id, "to": target_id, "type": "depends_on"})
+            successors[target_id].append(node_id)
+
+        # informs edges (evidence → decision)
+        for target_id in meta.get("informs", []):
+            edges.append({"from": node_id, "to": target_id, "type": "informs"})
+            successors[node_id].append(target_id)
+
+    # Auto-populate depended_on_by
+    for node_id, meta in nodes.items():
+        meta["depended_on_by"] = successors.get(node_id, [])
+
+    # Validate: check for dangling references
+    all_ids = set(nodes.keys())
+    for edge in edges:
+        if edge["to"] not in all_ids and "/" not in edge["to"]:
+            errors.append(f"Dangling reference: {edge['from']} → {edge['to']}")
+
+    # Write compiled artifacts
+    nodes_file = deg_dir / "nodes.jsonl"
+    with open(nodes_file, "w") as f:
+        for nid, n in nodes.items():
+            record = {k: v for k, v in n.items() if not k.startswith("_")}
+            record["id"] = nid
+            f.write(json.dumps(record, default=str) + "\n")
+
+    edges_file = deg_dir / "edges.jsonl"
+    with open(edges_file, "w") as f:
+        for e in edges:
+            f.write(json.dumps(e) + "\n")
+
+    graph_file = deg_dir / "graph.json"
+    with open(graph_file, "w") as f:
+        json.dump(dict(successors), f, indent=2)
+
+    return {
+        "nodes": len(nodes),
+        "edges": len(edges),
+        "errors": errors,
+        "path": str(deg_dir),
+    }
+
+
+def load_compiled(project_root: Path) -> tuple[dict, list[dict], dict[str, list[str]]]:
+    """Load the compiled graph from .deg/ directory."""
+    deg_dir = project_root / ".deg"
+
+    nodes = {}
+    nodes_file = deg_dir / "nodes.jsonl"
+    if nodes_file.exists():
+        for line in nodes_file.read_text().splitlines():
+            if line.strip():
+                record = json.loads(line)
+                nodes[record["id"]] = record
+
+    edges = []
+    edges_file = deg_dir / "edges.jsonl"
+    if edges_file.exists():
+        for line in edges_file.read_text().splitlines():
+            if line.strip():
+                edges.append(json.loads(line))
+
+    successors = defaultdict(list)
+    graph_file = deg_dir / "graph.json"
+    if graph_file.exists():
+        raw = json.loads(graph_file.read_text())
+        for k, v in raw.items():
+            successors[k] = v
+
+    return nodes, edges, dict(successors)