@flydocs/cli 0.5.0-beta.0

package/template/.claude/skills/flydocs-context-graph/scripts/graph_build.py

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""Rebuild the context graph from project sources.
+
+Scans skills (SKILL.md frontmatter) and ADRs (decisions/*.md cross-references)
+to produce flydocs/context/graph.json. Preserves manually-added nodes and edges.
+
+Usage:
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_build.py [--root PATH]
+"""
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from graph_utils import (
+    find_project_root,
+    load_graph,
+    save_graph,
+    output_json,
+    fail,
+    parse_frontmatter,
+)
+
+
+# --- Skill scanning ---
+
+
+def scan_skills(root):
+    """Scan .claude/skills/*/SKILL.md and return skill nodes + edges."""
+    skills_dir = root / ".claude" / "skills"
+    nodes = {}
+    edges = []
+
+    if not skills_dir.is_dir():
+        return nodes, edges
+
+    for skill_dir in sorted(skills_dir.iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+
+        text = skill_md.read_text(encoding="utf-8")
+        fm = parse_frontmatter(text)
+        if not fm or "name" not in fm:
+            continue
+
+        name = fm["name"]
+        node_id = f"skill:{name}"
+
+        node = {
+            "type": "skill",
+            "label": name,
+            "path": str(skill_md.relative_to(root)),
+        }
+
+        # Classify tier based on directory name
+        dir_name = skill_dir.name
+        if dir_name.startswith("flydocs-"):
+            if dir_name in ("flydocs-local", "flydocs-cloud"):
+                node["tier"] = "mechanism"
+            elif dir_name in ("flydocs-figma", "flydocs-estimates"):
+                node["tier"] = "premium"
+            else:
+                node["tier"] = "core"
+        else:
+            node["tier"] = "behavioral"
+
+        nodes[node_id] = node
+
+        # Extract PRECEDES edges from loads_after frontmatter
+        loads_after = fm.get("loads_after")
+        if loads_after:
+            if isinstance(loads_after, str):
+                loads_after = [loads_after]
+            for dep in loads_after:
+                dep = dep.strip()
+                if dep:
+                    # dep PRECEDES this skill (dep should load before this one)
+                    edges.append({
+                        "from": f"skill:{dep}",
+                        "to": node_id,
+                        "rel": "PRECEDES",
+                        "weight": 0.7,
+                    })
+
+    return nodes, edges
+
+
+# --- ADR scanning ---
+
+
+def scan_adrs(root):
+    """Scan flydocs/knowledge/decisions/*.md and return decision nodes + edges."""
+    decisions_dir = root / "flydocs" / "knowledge" / "decisions"
+    nodes = {}
+    edges = []
+
+    if not decisions_dir.is_dir():
+        return nodes, edges
+
+    for adr_file in sorted(decisions_dir.glob("*.md")):
+        # Extract ADR number from filename (e.g., 001 from 001-skills-architecture.md)
+        num_match = re.match(r"^(\d+)-", adr_file.name)
+        if not num_match:
+            continue
+
+        number = num_match.group(1)
+        node_id = f"decision:{number}"
+
+        text = adr_file.read_text(encoding="utf-8")
+
+        # Extract title from first heading
+        title_match = re.search(r"^#\s+(?:ADR-\d+:\s*)?(.+)$", text, re.MULTILINE)
+        title = title_match.group(1).strip() if title_match else adr_file.stem
+
+        # Extract status
+        status_match = re.search(r"\*\*Status\*\*:\s*(.+?)(?:\n|$)", text)
+        status = status_match.group(1).strip() if status_match else "unknown"
+
+        nodes[node_id] = {
+            "type": "decision",
+            "label": title,
+            "path": str(adr_file.relative_to(root)),
+            "status": status,
+        }
+
+        # Extract cross-references to other ADRs
+        # Look for ADR-NNN patterns in relationship sections
+        rel_edges = extract_adr_relationships(node_id, text)
+        edges.extend(rel_edges)
+
+    return nodes, edges
+
+
+def extract_adr_relationships(from_id, text):
+    """Extract edges from ADR cross-reference sections.
+
+    Looks for sections like "## Relationship to Other ADRs" and parses
+    ADR-NNN references with their relationship descriptions.
+    """
+    edges = []
+
+    # Find relationship sections — various headings used
+    rel_section = None
+    for pattern in [
+        r"##\s+Relationship to Other ADRs\s*\n(.*?)(?=\n##\s|\n---|\Z)",
+        r"##\s+Alignment with.*?\n(.*?)(?=\n##\s|\n---|\Z)",
+    ]:
+        match = re.search(pattern, text, re.DOTALL)
+        if match:
+            rel_section = match.group(1)
+            break
+
+    if not rel_section:
+        return edges
+
+    # Parse each ADR reference in the section
+    # Pattern: **ADR-NNN (Title)**: description -or- - ADR-NNN: description
+    for ref_match in re.finditer(r"ADR-(\d+)", rel_section):
+        target_num = ref_match.group(1).zfill(3)
+        target_id = f"decision:{target_num}"
+
+        if target_id == from_id:
+            continue
+
+        # Determine relationship type from surrounding text
+        # Get the sentence/bullet containing this reference
+        start = max(0, ref_match.start() - 10)
+        end = min(len(rel_section), ref_match.end() + 300)
+        context = rel_section[start:end].lower()
+
+        rel_type = classify_relationship(context)
+
+        edges.append({
+            "from": from_id,
+            "to": target_id,
+            "rel": rel_type,
+            "weight": 0.8,
+        })
+
+    return edges
+
+
+def classify_relationship(context):
+    """Classify the relationship type from surrounding text."""
+    if any(w in context for w in ["extends", "refines", "builds on", "extension"]):
+        return "EXTENDS"
+    if any(w in context for w in ["implements", "realizes", "application of"]):
+        return "IMPLEMENTS"
+    if any(w in context for w in ["supersedes", "replaces", "replaced by"]):
+        return "SUPERSEDES"
+    if any(w in context for w in ["delegates", "hands off"]):
+        return "DELEGATES_TO"
+    if any(w in context for w in ["precedes", "before", "prerequisite"]):
+        return "PRECEDES"
+    if any(w in context for w in ["modifies", "changes", "affects"]):
+        return "MODIFIES"
+    return "RELATES_TO"
+
+
+# --- Graph merge ---
+
+
+def merge_graph(existing, new_nodes, new_edges):
+    """Merge scanned nodes/edges into existing graph, preserving manual entries."""
+    graph = {
+        "version": 1,
+        "updated": "",
+        "nodes": {},
+        "edges": [],
+    }
+
+    # Preserve manual nodes from existing graph
+    for node_id, node in existing.get("nodes", {}).items():
+        if node.get("manual"):
+            graph["nodes"][node_id] = node
+
+    # Add scanned nodes (overwrite non-manual)
+    for node_id, node in new_nodes.items():
+        graph["nodes"][node_id] = node
+
+    # Preserve manual edges from existing graph
+    for edge in existing.get("edges", []):
+        if edge.get("manual"):
+            graph["edges"].append(edge)
+
+    # Add scanned edges (deduplicate)
+    existing_edge_keys = {
+        (e["from"], e["to"], e["rel"]) for e in graph["edges"]
+    }
+    for edge in new_edges:
+        key = (edge["from"], edge["to"], edge["rel"])
+        if key not in existing_edge_keys:
+            graph["edges"].append(edge)
+            existing_edge_keys.add(key)
+
+    return graph
+
+
+# --- Main ---
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Rebuild context graph from project sources"
+    )
+    parser.add_argument(
+        "--root", type=str, default=None,
+        help="Project root (default: auto-detect from .flydocs/)"
+    )
+    args = parser.parse_args()
+
+    root = Path(args.root) if args.root else find_project_root()
+    if not root:
+        fail("Could not find project root (no .flydocs/ directory found)")
+
+    # Load existing graph to preserve manual entries
+    existing = load_graph(root)
+
+    # Scan sources
+    skill_nodes, skill_edges = scan_skills(root)
+    adr_nodes, adr_edges = scan_adrs(root)
+
+    # Merge all scanned nodes and edges
+    all_nodes = {}
+    all_nodes.update(skill_nodes)
+    all_nodes.update(adr_nodes)
+
+    all_edges = []
+    all_edges.extend(skill_edges)
+    all_edges.extend(adr_edges)
+
+    # Merge with existing graph (preserving manual entries)
+    graph = merge_graph(existing, all_nodes, all_edges)
+
+    # Save
+    save_graph(root, graph)
+
+    # Report
+    output_json({
+        "success": True,
+        "path": str(graph_path_for_report(root)),
+        "nodes": len(graph["nodes"]),
+        "edges": len(graph["edges"]),
+        "skills": len(skill_nodes),
+        "decisions": len(adr_nodes),
+    })
+
+
+def graph_path_for_report(root):
+    """Return the relative graph path for reporting."""
+    return os.path.join("flydocs", "context", "graph.json")
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/flydocs-context-graph/scripts/graph_context.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""Assemble compressed graph context for the prime hook.
+
+Given an active issue and/or git branch, traverses the graph and returns
+a compact context block suitable for injection into the prompt-submit hook.
+Stays within a ~200-400 token budget.
+
+Usage:
+    python3 .claude/skills/flydocs-context-graph/scripts/graph_context.py \
+        [--issue FLY-56] [--branch feature/context-graph] [--root PATH]
+
+Output: Plain text context block (not JSON) for direct injection into hook output.
+Returns empty string if graph doesn't exist or no relevant context found.
+"""
+
+import argparse
+import sys
+from datetime import date, timedelta
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from graph_utils import find_project_root, load_graph
+
+
+# Maximum lines in the context block to stay within token budget
+MAX_CONTEXT_LINES = 12
+
+# Session staleness policy
+SESSION_RETENTION_DAYS = 30
+SESSION_FRESH_DAYS = 7  # Full weight within this window
+
+
+def find_issue_node(graph, issue_ref):
+    """Find a graph node matching an issue reference (e.g., FLY-56)."""
+    if not issue_ref:
+        return None
+
+    # Try exact match first
+    node_id = f"issue:{issue_ref}"
+    if node_id in graph.get("nodes", {}):
+        return node_id
+
+    # Try case-insensitive search
+    for nid in graph.get("nodes", {}):
+        if nid.lower() == node_id.lower():
+            return nid
+
+    return None
+
+
+def find_branch_nodes(graph, branch):
+    """Infer relevant nodes from a git branch name.
+
+    Branch names often contain issue refs (feature/FLY-56-context-graph)
+    or skill/module names (feature/context-graph).
+    """
+    if not branch:
+        return []
+
+    nodes = graph.get("nodes", {})
+    matches = []
+
+    # Extract issue reference from branch (e.g., FLY-56)
+    import re
+    issue_match = re.search(r"([A-Z]+-\d+)", branch, re.IGNORECASE)
+    if issue_match:
+        issue_id = find_issue_node(graph, issue_match.group(1))
+        if issue_id:
+            matches.append(issue_id)
+
+    # Match skill or module names in branch
+    branch_lower = branch.lower().replace("/", "-").replace("_", "-")
+    for node_id, node in nodes.items():
+        if node["type"] in ("skill", "module"):
+            name = node_id.split(":", 1)[-1].lower()
+            if name in branch_lower and len(name) > 3:
+                matches.append(node_id)
+
+    return matches
+
+
+def find_recent_sessions(graph, issue_nodes, today=None):
+    """Find session nodes relevant to the current work.
+
+    Returns sessions connected to active issues, or recent sessions if no
+    issue match. Applies staleness weighting — older sessions get lower weight.
+    """
+    if today is None:
+        today = date.today()
+
+    nodes = graph.get("nodes", {})
+    edges = graph.get("edges", [])
+    cutoff = today - timedelta(days=SESSION_RETENTION_DAYS)
+
+    # Find all session nodes within retention window
+    sessions = []
+    for node_id, node in nodes.items():
+        if node.get("type") != "session":
+            continue
+
+        session_date_str = node.get("date", "")
+        if not session_date_str:
+            continue
+
+        try:
+            session_date = date.fromisoformat(session_date_str)
+        except ValueError:
+            continue
+
+        if session_date < cutoff:
+            continue
+
+        # Calculate staleness weight
+        age_days = (today - session_date).days
+        if age_days <= SESSION_FRESH_DAYS:
+            weight = 1.0
+        else:
+            # Linear decay from 1.0 to 0.1 over the retention period
+            weight = max(0.1, 1.0 - (age_days / SESSION_RETENTION_DAYS) * 0.9)
+
+        sessions.append((node_id, node, session_date, weight))
+
+    if not sessions:
+        return []
+
+    # Check which sessions are connected to active issues
+    issue_set = set(issue_nodes)
+    connected = []
+    unconnected = []
+
+    for session_id, node, session_date, weight in sessions:
+        # Check if this session has WORKED_ON edges to any active issue
+        has_issue_link = False
+        for edge in edges:
+            if (edge["from"] == session_id
+                    and edge["rel"] == "WORKED_ON"
+                    and edge["to"] in issue_set):
+                has_issue_link = True
+                break
+
+        if has_issue_link:
+            connected.append((session_id, node, weight))
+        else:
+            unconnected.append((session_id, node, weight))
+
+    # Prefer connected sessions, fall back to most recent
+    if connected:
+        connected.sort(key=lambda x: x[2], reverse=True)
+        return connected[:3]
+
+    # No connected sessions — return most recent ones
+    unconnected.sort(key=lambda x: x[0], reverse=True)  # Sort by ID (date-based)
+    return unconnected[:2]
+
+
+def get_related_context(graph, start_nodes, max_depth=2):
+    """BFS traverse from start nodes and collect related context.
+
+    Returns a deduplicated list of (node_id, node, rel, depth) tuples.
+    """
+    nodes = graph.get("nodes", {})
+    edges = graph.get("edges", [])
+
+    # Build adjacency (both directions for full context)
+    forward = {}
+    reverse = {}
+    for edge in edges:
+        src, dst = edge["from"], edge["to"]
+        rel = edge["rel"]
+        weight = edge.get("weight", 1.0)
+
+        if src not in forward:
+            forward[src] = []
+        forward[src].append((dst, rel, weight))
+
+        if dst not in reverse:
+            reverse[dst] = []
+        reverse[dst].append((src, rel, weight))
+
+    visited = set(start_nodes)
+    results = []
+
+    # BFS from each start node
+    from collections import deque
+    queue = deque()
+
+    for start in start_nodes:
+        # Forward edges
+        for neighbor, rel, weight in forward.get(start, []):
+            if neighbor not in visited:
+                queue.append((neighbor, 1, rel, "forward"))
+                visited.add(neighbor)
+        # Reverse edges
+        for neighbor, rel, weight in reverse.get(start, []):
+            if neighbor not in visited:
+                queue.append((neighbor, 1, rel, "reverse"))
+                visited.add(neighbor)
+
+    while queue:
+        node_id, depth, rel, direction = queue.popleft()
+        node = nodes.get(node_id, {})
+        results.append((node_id, node, rel, depth))
+
+        if depth < max_depth:
+            adj = forward if direction == "forward" else reverse
+            for neighbor, next_rel, weight in adj.get(node_id, []):
+                if neighbor not in visited:
+                    queue.append((neighbor, depth + 1, next_rel, direction))
+                    visited.add(neighbor)
+
+    return results
+
+
+def format_context_block(graph, start_nodes, related):
+    """Format a compressed context block within the token budget."""
+    nodes = graph.get("nodes", {})
+    lines = []
+
+    # Temporal anchor
+    lines.append(f"Today is {date.today().strftime('%B %d, %Y')}")
+
+    if not related:
+        return "\n".join(lines)
+
+    # Group by type, prioritize decisions and skills
+    decisions = []
+    skills = []
+    sessions = []
+    other = []
+
+    for node_id, node, rel, depth in related:
+        node_type = node.get("type", "unknown")
+        if node_type == "decision":
+            decisions.append((node_id, node, rel))
+        elif node_type == "skill":
+            skills.append((node_id, node, rel))
+        elif node_type == "session":
+            sessions.append((node_id, node, rel))
+        else:
+            other.append((node_id, node, rel))
+
+    # Decisions — most valuable context
+    if decisions:
+        lines.append("Related decisions:")
+        for node_id, node, rel in decisions[:4]:
+            num = node_id.split(":")[-1]
+            label = node.get("label", node_id)
+            lines.append(f"  ADR-{num}: {label} ({rel})")
+
+    # Skills
+    if skills:
+        skill_names = [n.get("label", nid) for nid, n, r in skills[:3]]
+        lines.append(f"Related skills: {', '.join(skill_names)}")
+
+    # Sessions — prior work context
+    if sessions:
+        for node_id, node, rel in sessions[:2]:
+            label = node.get("label", "")
+            session_date = node.get("date", "")
+            if label:
+                lines.append(f"Prior session ({session_date}): {label}")
+
+    # Truncate to budget
+    if len(lines) > MAX_CONTEXT_LINES:
+        lines = lines[:MAX_CONTEXT_LINES]
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Assemble graph context for prime hook"
+    )
+    parser.add_argument(
+        "--issue", type=str, default=None,
+        help="Active issue reference (e.g., FLY-56)"
+    )
+    parser.add_argument(
+        "--branch", type=str, default=None,
+        help="Current git branch name"
+    )
+    parser.add_argument(
+        "--root", type=str, default=None,
+        help="Project root (default: auto-detect)"
+    )
+    args = parser.parse_args()
+
+    root = Path(args.root) if args.root else find_project_root()
+    if not root:
+        # Graceful fallback — no output
+        sys.exit(0)
+
+    # Load graph — graceful fallback if missing
+    graph = load_graph(root)
+    if not graph.get("nodes"):
+        # Empty or missing graph — just output temporal anchor
+        print(f"Today is {date.today().strftime('%B %d, %Y')}")
+        sys.exit(0)
+
+    # Find starting nodes
+    start_nodes = []
+
+    issue_node = find_issue_node(graph, args.issue)
+    if issue_node:
+        start_nodes.append(issue_node)
+
+    branch_nodes = find_branch_nodes(graph, args.branch)
+    start_nodes.extend(n for n in branch_nodes if n not in start_nodes)
+
+    # If no specific entry points, just output temporal anchor
+    if not start_nodes:
+        print(f"Today is {date.today().strftime('%B %d, %Y')}")
+        sys.exit(0)
+
+    # Traverse and assemble context
+    related = get_related_context(graph, start_nodes, max_depth=2)
+
+    # Find recent sessions (connected to active issues or just recent)
+    issue_start_nodes = [n for n in start_nodes if n.startswith("issue:")]
+    recent_sessions = find_recent_sessions(graph, issue_start_nodes)
+
+    # Add sessions to related if not already present
+    seen = {r[0] for r in related}
+    for session_id, node, weight in recent_sessions:
+        if session_id not in seen:
+            related.append((session_id, node, "WORKED_ON", 1))
+            seen.add(session_id)
+
+    context = format_context_block(graph, start_nodes, related)
+
+    if context:
+        print(context)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()