@rkarim08/sia 1.0.0

package/skills/sia-verify/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sia-verify
+description: Verifies work completeness using SIA's knowledge of area-specific requirements, past verification failures, and known gotchas. Use when about to claim work is done, before committing, or before creating PRs.
+---
+
+## Invariants
+
+> These rules have No exceptions. A "done" claim without evidence is a FAILURE.
+>
+> 1. YOU MUST run a verification command and read its FULL output before claiming
+>    ANY work is done. "I'm confident it works" is NEVER sufficient.
+> 2. If SIA surfaces area-specific verification requirements, you MUST verify
+>    EACH ONE explicitly. Running only `bun run test` is not enough if the area
+>    also requires typecheck, lint, or integration tests.
+> 3. A claim of completion without a corresponding command output in the
+>    conversation is a FAILED verification. There is no such thing as
+>    "obviously correct."
+
+## Red Flags — If You Think Any of These, STOP
+
+| Thought | Why It's Wrong |
+|---------|---------------|
+| "The change is too small to verify" | Small changes cause the largest regressions. Verify. |
+| "I already tested this mentally" | Mental testing catches ~30% of issues. Run the command. |
+| "The CI will catch any problems" | CI runs after you commit. Catch it NOW. |
+| "I ran a similar test earlier" | Earlier tests tested earlier code. This is different code. Run again. |
+| "The tests are flaky, so a failure doesn't mean anything" | Re-run. If it fails twice, investigate. Do NOT claim success on a failing test. |
+| "Just this once, I'll skip the SIA query" | The SIA query is how you discover area-specific requirements you don't know about. Never skip. |
+
+# SIA-Enhanced Verification
+
+Verify work is truly complete — queries SIA for area-specific requirements, past verification failures, and known gotchas before running checks. Evidence before assertions.
+
+## Checklist
+
+```
+- [ ] Step 0: YOU MUST query SIA for area-specific verification requirements and known bugs. Without this, you will miss verification steps.
+- [ ] Steps 1-5: IDENTIFY command → RUN fully → READ full output → VERIFY it confirms claim → ONLY THEN claim done. Skipping ANY step is a failed verification.
+- [ ] Post: Capture any new verification requirements to graph. A verification that discovers new requirements but doesn't capture them leaves the next developer blind.
+```
+
+## Workflow
+
+### Step 0 — SIA Requirements Query (NEW)
+
+Before running verification commands:
+
+```
+sia_search({ query: "verification requirements testing <area>", node_types: ["Convention", "Decision"], limit: 10 })
+sia_search({ query: "bugs failures <area>", node_types: ["Bug"], limit: 5 })
+```
+
+Check if this area has specific verification requirements:
+- "This module requires integration tests, not just unit tests"
+- "Changes to the API need backwards-compatibility verification"
+- "The auth module had a bug with edge case X — verify it's still handled"
+
+### Step 1-5 — Standard Verification Gate (enhanced)
+
+Follow the standard gate function:
+1. **IDENTIFY** what command proves the claim — enhanced by SIA's knowledge of project-specific verification commands
+2. **RUN** the full command
+3. **READ** full output
+4. **VERIFY** output confirms the claim
+5. **ONLY THEN** make the claim
+
+**Enhancement:** If SIA surfaced area-specific requirements in Step 0, verify EACH ONE explicitly. Don't just run `bun run test` — also run any area-specific checks (e.g., `bun run typecheck`, `bun run lint`, integration tests).
+
+### Post-Verification — Capture (NEW)
+
+If verification revealed an issue that was fixed:
+
+```
+sia_note({ kind: "Convention", name: "Verification: <area> requires <specific check>", content: "<what verification is needed and why>" })
+```
+
+This builds up area-specific verification knowledge over time.
+
+## Key Principle
+
+**Different areas need different verification.** SIA learns what each area requires and reminds you before you declare "done."

package/skills/sia-visualize/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sia-visualize
+description: Generates an interactive HTML visualization of the SIA knowledge graph. Use when the user wants a static visualization file, for sharing graph views, or embedding in documentation.
+---
+
+# SIA Visualize
+
+Generate a D3.js force-directed graph visualization of the knowledge graph.
+
+## Steps
+
+1. Run the graph visualization command:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/graph.ts
+```
+
+2. This generates an HTML file at `sia-graph.html` in the project root.
+
+3. Open the file in your browser to explore the graph interactively.
+
+## Notes
+
+- The visualization shows entities as nodes and edges as connections
+- Node size reflects importance (PageRank)
+- Node color reflects type (CodeSymbol, Decision, Convention, etc.)
+- Hover over nodes to see details
+- The graph is a snapshot — it does not update in real time

package/skills/sia-visualize-live/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: sia-visualize-live
+description: Launches an interactive browser-based knowledge graph visualizer for exploring entities, dependencies, and communities. Use when the user wants to visually explore the graph or understand module relationships.
+---
+
+# SIA Live Visualizer
+
+Launch an interactive knowledge graph visualization in your browser.
+
+## Usage
+
+**Graph explorer** (default):
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts visualize-live
+```
+
+**Temporal timeline:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts visualize-live --view timeline
+```
+
+**Dependency map:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts visualize-live --view deps
+```
+
+**Community clusters:**
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts visualize-live --view communities
+```
+
+## Starting the Visualizer
+
+```bash
+skills/sia-visualize-live/scripts/start-visualizer.sh --project-dir /path/to/project
+```
+
+Open the URL shown in the output. The graph loads automatically.
+
+## Stopping
+
+```bash
+skills/sia-visualize-live/scripts/stop-visualizer.sh $SCREEN_DIR
+```
+
+## Views
+
+| View | What It Shows |
+|---|---|
+| `graph` | Interactive force-directed graph — click nodes to expand, filter by type/tier |
+| `timeline` | Temporal history — when decisions were made, bugs found, entities invalidated |
+| `deps` | File dependency map — imports, calls, depends_on edges between modules |
+| `communities` | Community clusters — Leiden-detected module groups with summaries |
+
+Open the URL shown in your terminal. The visualization updates live as you push new views.

package/skills/sia-visualize-live/scripts/graph-template.html

@@ -0,0 +1,389 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>SIA Knowledge Graph</title>
+  <script src="https://d3js.org/d3.v7.min.js"></script>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body { height: 100%; overflow: hidden; }
+
+    :root {
+      --bg-primary: #f5f5f7;
+      --bg-secondary: #ffffff;
+      --bg-tertiary: #e5e5e7;
+      --border: #d1d1d6;
+      --text-primary: #1d1d1f;
+      --text-secondary: #86868b;
+      --accent: #0071e3;
+      --node-decision: #0a84ff;
+      --node-convention: #30d158;
+      --node-bug: #ff453a;
+      --node-solution: #ffd60a;
+      --node-file: #bf5af2;
+      --node-default: #86868b;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg-primary: #1d1d1f;
+        --bg-secondary: #2d2d2f;
+        --bg-tertiary: #3d3d3f;
+        --border: #424245;
+        --text-primary: #f5f5f7;
+        --text-secondary: #86868b;
+        --accent: #0a84ff;
+      }
+    }
+
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
+      background: var(--bg-primary);
+      color: var(--text-primary);
+      display: flex;
+      flex-direction: column;
+    }
+
+    .header {
+      background: var(--bg-secondary);
+      padding: 0.5rem 1.5rem;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      border-bottom: 1px solid var(--border);
+      flex-shrink: 0;
+      z-index: 10;
+    }
+    .header h1 { font-size: 0.85rem; font-weight: 500; color: var(--text-secondary); }
+    .header .status { font-size: 0.7rem; color: #34c759; display: flex; align-items: center; gap: 0.4rem; }
+    .header .status::before { content: ''; width: 6px; height: 6px; background: #34c759; border-radius: 50%; }
+
+    .toolbar {
+      background: var(--bg-secondary);
+      padding: 0.4rem 1.5rem;
+      display: flex;
+      gap: 0.75rem;
+      align-items: center;
+      border-bottom: 1px solid var(--border);
+      flex-shrink: 0;
+    }
+    .toolbar input {
+      background: var(--bg-primary);
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      padding: 0.35rem 0.75rem;
+      color: var(--text-primary);
+      font-size: 0.8rem;
+      width: 250px;
+    }
+    .toolbar button {
+      background: var(--bg-tertiary);
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      padding: 0.35rem 0.75rem;
+      color: var(--text-primary);
+      font-size: 0.75rem;
+      cursor: pointer;
+    }
+    .toolbar button:hover { border-color: var(--accent); }
+    .toolbar button.active { background: var(--accent); color: white; border-color: var(--accent); }
+
+    .content { display: flex; flex: 1; overflow: hidden; }
+
+    #graph-container { flex: 1; position: relative; }
+    #graph-container svg { width: 100%; height: 100%; }
+
+    #sidebar {
+      width: 300px;
+      background: var(--bg-secondary);
+      border-left: 1px solid var(--border);
+      padding: 1rem;
+      overflow-y: auto;
+      flex-shrink: 0;
+      display: none;
+    }
+    #sidebar.visible { display: block; }
+    #sidebar h3 { font-size: 0.9rem; margin-bottom: 0.5rem; }
+    #sidebar .field { margin-bottom: 0.75rem; }
+    #sidebar .field-label { font-size: 0.7rem; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.05em; }
+    #sidebar .field-value { font-size: 0.85rem; margin-top: 0.15rem; word-break: break-word; }
+    #sidebar .trust-tier { display: inline-block; padding: 0.1rem 0.4rem; border-radius: 4px; font-size: 0.7rem; font-weight: 600; }
+    #sidebar .tier-1 { background: #30d158; color: #000; }
+    #sidebar .tier-2 { background: #0a84ff; color: #fff; }
+    #sidebar .tier-3 { background: #ffd60a; color: #000; }
+    #sidebar .tier-4 { background: #86868b; color: #fff; }
+
+    #legend {
+      position: absolute;
+      bottom: 1rem;
+      left: 1rem;
+      background: var(--bg-secondary);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 0.75rem;
+      font-size: 0.75rem;
+      z-index: 5;
+    }
+    #legend .legend-item { display: flex; align-items: center; gap: 0.5rem; margin-bottom: 0.25rem; }
+    #legend .legend-dot { width: 10px; height: 10px; border-radius: 50%; }
+
+    .node-label { font-size: 10px; fill: var(--text-secondary); pointer-events: none; }
+    .edge-label { font-size: 8px; fill: var(--text-secondary); pointer-events: none; }
+    .link { stroke: var(--border); stroke-opacity: 0.6; }
+    .link:hover { stroke-opacity: 1; stroke-width: 2px; }
+    .node { cursor: pointer; }
+    .node:hover circle { stroke-width: 3px; }
+    .node.highlighted circle { stroke: var(--accent); stroke-width: 3px; }
+    .node.dimmed { opacity: 0.2; }
+    .link.dimmed { opacity: 0.05; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>SIA Knowledge Graph Explorer</h1>
+    <div class="status">Connected</div>
+  </div>
+
+  <div class="toolbar">
+    <input type="text" id="search" placeholder="Search entities..." />
+    <button data-filter="all" class="active">All</button>
+    <button data-filter="Decision">Decisions</button>
+    <button data-filter="Convention">Conventions</button>
+    <button data-filter="Bug">Bugs</button>
+    <button data-filter="Solution">Solutions</button>
+    <button data-filter="File">Files</button>
+  </div>
+
+  <div class="content">
+    <div id="graph-container">
+      <div id="legend">
+        <div class="legend-item"><div class="legend-dot" style="background: var(--node-decision)"></div> Decision</div>
+        <div class="legend-item"><div class="legend-dot" style="background: var(--node-convention)"></div> Convention</div>
+        <div class="legend-item"><div class="legend-dot" style="background: var(--node-bug)"></div> Bug</div>
+        <div class="legend-item"><div class="legend-dot" style="background: var(--node-solution)"></div> Solution</div>
+        <div class="legend-item"><div class="legend-dot" style="background: var(--node-file)"></div> File</div>
+        <div class="legend-item"><div class="legend-dot" style="background: var(--node-default)"></div> Other</div>
+      </div>
+    </div>
+    <div id="sidebar">
+      <h3 id="sidebar-title">Select an entity</h3>
+      <div id="sidebar-content"></div>
+    </div>
+  </div>
+
+  <script>
+    const graphData = /* GRAPH_DATA */;
+
+    const typeColors = {
+      Decision: getComputedStyle(document.documentElement).getPropertyValue('--node-decision').trim(),
+      Convention: getComputedStyle(document.documentElement).getPropertyValue('--node-convention').trim(),
+      Bug: getComputedStyle(document.documentElement).getPropertyValue('--node-bug').trim(),
+      Solution: getComputedStyle(document.documentElement).getPropertyValue('--node-solution').trim(),
+      File: getComputedStyle(document.documentElement).getPropertyValue('--node-file').trim(),
+    };
+    const defaultColor = getComputedStyle(document.documentElement).getPropertyValue('--node-default').trim();
+
+    function nodeColor(d) { return typeColors[d.type] || defaultColor; }
+    function nodeRadius(d) { return d.type === 'File' ? 6 : 8; }
+
+    const container = document.getElementById('graph-container');
+    const width = container.clientWidth;
+    const height = container.clientHeight;
+
+    const svg = d3.select('#graph-container')
+      .append('svg')
+      .attr('viewBox', [0, 0, width, height]);
+
+    const g = svg.append('g');
+
+    // Zoom/pan
+    const zoom = d3.zoom()
+      .scaleExtent([0.1, 10])
+      .on('zoom', (event) => g.attr('transform', event.transform));
+    svg.call(zoom);
+
+    // Build simulation
+    const nodes = (graphData.nodes || []).map(d => ({ ...d }));
+    const links = (graphData.edges || graphData.links || []).map(d => ({
+      ...d,
+      source: d.source_id || d.source,
+      target: d.target_id || d.target,
+    }));
+
+    const simulation = d3.forceSimulation(nodes)
+      .force('link', d3.forceLink(links).id(d => d.id).distance(80))
+      .force('charge', d3.forceManyBody().strength(-200))
+      .force('center', d3.forceCenter(width / 2, height / 2))
+      .force('collision', d3.forceCollide().radius(d => nodeRadius(d) + 4));
+
+    // Edges
+    const link = g.append('g')
+      .selectAll('line')
+      .data(links)
+      .join('line')
+      .attr('class', 'link')
+      .attr('stroke-width', 1);
+
+    const edgeLabels = g.append('g')
+      .selectAll('text')
+      .data(links)
+      .join('text')
+      .attr('class', 'edge-label')
+      .attr('text-anchor', 'middle')
+      .text(d => d.edge_type || d.type || '');
+
+    // Nodes
+    const node = g.append('g')
+      .selectAll('g')
+      .data(nodes)
+      .join('g')
+      .attr('class', 'node')
+      .call(d3.drag()
+        .on('start', dragstarted)
+        .on('drag', dragged)
+        .on('end', dragended));
+
+    node.append('circle')
+      .attr('r', d => nodeRadius(d))
+      .attr('fill', d => nodeColor(d))
+      .attr('stroke', d => d3.color(nodeColor(d)).darker(0.5))
+      .attr('stroke-width', 1.5);
+
+    node.append('text')
+      .attr('class', 'node-label')
+      .attr('dx', d => nodeRadius(d) + 4)
+      .attr('dy', '0.35em')
+      .text(d => d.name || d.label || d.id);
+
+    // Click to show details in sidebar
+    node.on('click', (event, d) => {
+      event.stopPropagation();
+      showSidebar(d);
+    });
+
+    svg.on('click', () => hideSidebar());
+
+    simulation.on('tick', () => {
+      link
+        .attr('x1', d => d.source.x)
+        .attr('y1', d => d.source.y)
+        .attr('x2', d => d.target.x)
+        .attr('y2', d => d.target.y);
+
+      edgeLabels
+        .attr('x', d => (d.source.x + d.target.x) / 2)
+        .attr('y', d => (d.source.y + d.target.y) / 2);
+
+      node.attr('transform', d => `translate(${d.x},${d.y})`);
+    });
+
+    // Drag behavior
+    function dragstarted(event, d) {
+      if (!event.active) simulation.alphaTarget(0.3).restart();
+      d.fx = d.x; d.fy = d.y;
+    }
+    function dragged(event, d) { d.fx = event.x; d.fy = event.y; }
+    function dragended(event, d) {
+      if (!event.active) simulation.alphaTarget(0);
+      d.fx = null; d.fy = null;
+    }
+
+    // Search — highlights matching nodes
+    document.getElementById('search').addEventListener('input', (e) => {
+      const query = e.target.value.toLowerCase();
+      if (!query) {
+        node.classed('highlighted', false).classed('dimmed', false);
+        link.classed('dimmed', false);
+        return;
+      }
+      const matchIds = new Set();
+      nodes.forEach(n => {
+        if ((n.name || n.label || n.id).toLowerCase().includes(query)) matchIds.add(n.id);
+      });
+      node.classed('highlighted', d => matchIds.has(d.id));
+      node.classed('dimmed', d => !matchIds.has(d.id));
+      link.classed('dimmed', d => !matchIds.has(d.source.id) && !matchIds.has(d.target.id));
+    });
+
+    // Filter buttons — show/dim by entity type
+    document.querySelectorAll('.toolbar button').forEach(btn => {
+      btn.addEventListener('click', () => {
+        document.querySelectorAll('.toolbar button').forEach(b => b.classList.remove('active'));
+        btn.classList.add('active');
+        const filter = btn.dataset.filter;
+        if (filter === 'all') {
+          node.classed('dimmed', false);
+          link.classed('dimmed', false);
+        } else {
+          node.classed('dimmed', d => d.type !== filter);
+          link.classed('dimmed', d => d.source.type !== filter && d.target.type !== filter);
+        }
+      });
+    });
+
+    // Sidebar — shows entity details using safe DOM methods
+    function showSidebar(d) {
+      const sidebar = document.getElementById('sidebar');
+      sidebar.classList.add('visible');
+      document.getElementById('sidebar-title').textContent = d.name || d.label || d.id;
+
+      const contentEl = document.getElementById('sidebar-content');
+      contentEl.textContent = ''; // Clear previous content safely
+
+      const fields = [
+        { label: 'Type', value: d.type },
+        { label: 'ID', value: d.id },
+        { label: 'Content', value: d.content },
+        { label: 'Trust Tier', value: d.trust_tier ? 'Tier ' + d.trust_tier : null },
+        { label: 'Valid From', value: d.t_valid_from },
+        { label: 'Valid Until', value: d.t_valid_until || 'current' },
+        { label: 'File Path', value: d.file_path },
+        { label: 'Community', value: d.community_id != null ? 'Community ' + d.community_id : null },
+      ].filter(f => f.value != null);
+
+      fields.forEach(f => {
+        const fieldDiv = document.createElement('div');
+        fieldDiv.className = 'field';
+
+        const labelDiv = document.createElement('div');
+        labelDiv.className = 'field-label';
+        labelDiv.textContent = f.label;
+
+        const valueDiv = document.createElement('div');
+        valueDiv.className = 'field-value';
+
+        if (f.label === 'Trust Tier' && d.trust_tier) {
+          const span = document.createElement('span');
+          span.className = 'trust-tier tier-' + d.trust_tier;
+          span.textContent = f.value;
+          valueDiv.appendChild(span);
+        } else {
+          valueDiv.textContent = f.value;
+        }
+
+        fieldDiv.appendChild(labelDiv);
+        fieldDiv.appendChild(valueDiv);
+        contentEl.appendChild(fieldDiv);
+      });
+    }
+
+    function hideSidebar() {
+      document.getElementById('sidebar').classList.remove('visible');
+    }
+
+    // WebSocket live reload
+    (function connectWS() {
+      const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const ws = new WebSocket(proto + '//' + location.host);
+      ws.onmessage = (evt) => {
+        try {
+          const msg = JSON.parse(evt.data);
+          if (msg.type === 'reload') location.reload();
+        } catch (e) { /* ignore parse errors */ }
+      };
+      ws.onclose = () => setTimeout(connectWS, 2000);
+      ws.onerror = () => ws.close();
+    })();
+  </script>
+</body>
+</html>