perf(skill): build the graph once across Steps 4-5

.dockerignore

@@ -0,0 +1,25 @@
+.git
+.github
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+dist
+build
+*.egg-info
+graphify-out
+graphify-benchmark
+graphify_eval
+graphify_test
+worked
+llm-stack-corpus
+llm-stack-demo
+product-site
+ebook
+tests
+docs
+*.md
+!README.md

.gitattributes

@@ -0,0 +1,6 @@
+# Tell GitHub Linguist to ignore generated/example HTML files when calculating
+# the repo's primary language. Without this, large graph.html artifacts in
+# worked/ dominate the byte count and the repo shows as HTML instead of Python.
+worked/**/*.html linguist-vendored=true
+graphify-out/**/*.html linguist-vendored=true
+*.html linguist-detectable=false

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: safishamsi

.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: ["v1", "v2", "v3", "v4", "v5", "v6", "v7", "v8", "main"]
+  pull_request:
+    branches: ["v1", "v2", "v3", "v4", "v5", "v6", "v7", "v8", "main"]
+  workflow_dispatch:
+
+jobs:
+  skillgen-check:
+    # Fast lint-style guard: the skill files under graphify/ are generated from
+    # the fragments in tools/skillgen/. This fails if someone hand-edited a
+    # generated file or forgot to re-run the generator and bless expected/, and it
+    # runs the build-time validators that guard per-host coverage, the file_type
+    # enum, the monolith round-trips, and the always-on round-trips.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # The audit-coverage, monolith-roundtrip, and always-on-roundtrip
+          # validators read blobs from origin/v8. A shallow checkout omits that
+          # ref, so fetch the full history here and the validators run for real
+          # (rather than skipping). The other jobs stay shallow.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+
+      # --frozen keeps uv from re-resolving and rewriting uv.lock as a side
+      # effect of `uv run`; the lock is committed and must not churn in CI.
+      - name: Check generated skill artifacts are up to date
+        run: uv run --frozen python -m tools.skillgen --check
+
+      - name: Audit per-host v8 coverage
+        run: uv run --frozen python -m tools.skillgen --audit-coverage
+
+      - name: Check the file_type enum is a singleton
+        run: uv run --frozen python -m tools.skillgen --schema-singleton
+
+      - name: Round-trip the monoliths against v8
+        run: uv run --frozen python -m tools.skillgen --monolith-roundtrip
+
+      - name: Round-trip the always-on blocks against v8
+        run: uv run --frozen python -m tools.skillgen --always-on-roundtrip
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # test_skillgen.py reads pre-split skill bodies from the immutable
+          # baseline commit via `git show`; a shallow checkout omits that history
+          # and the baseline tests fail. Full history mirrors the skillgen-check job.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # --frozen installs straight from the committed uv.lock without re-resolving
+      # or rewriting it, so CI never churns the lock.
+      - name: Install dependencies
+        run: uv sync --all-extras --frozen
+
+      - name: Run tests
+        run: uv run --frozen pytest tests/ -q --tb=short
+
+      - name: Verify install works end-to-end
+        run: |
+          uv run --frozen graphify --help
+          uv run --frozen graphify install

.github/workflows/release-graph.yml

@@ -0,0 +1,64 @@
+name: Release graph asset
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-graph:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # needed to upload release assets
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Install graphify
+        run: uv sync --frozen
+
+      - name: Build graph of graphify source (AST-only, no API cost)
+        # graphify/skills/ contains 126+ .md files that trigger the LLM pass.
+        # Temporarily ignore all .md files so extraction stays pure AST (no API key needed).
+        run: |
+          echo "*.md" >> .graphifyignore
+          echo "*.txt" >> .graphifyignore
+          uv run --frozen graphify extract graphify/ --out .
+          git checkout .graphifyignore 2>/dev/null || rm -f .graphifyignore
+
+      - name: Cluster, label communities and generate GRAPH_REPORT.md
+        # cluster-only writes GRAPH_REPORT.md and names communities (no LLM needed
+        # for basic numeric labels; --no-label skips LLM labeling entirely).
+        run: uv run --frozen graphify cluster-only . --no-label
+
+      - name: Generate HTML viewer
+        run: uv run --frozen graphify export html --graph graphify-out/graph.json
+
+      - name: Bundle release asset
+        run: |
+          mkdir -p dist-graph
+          cp graphify-out/graph.json dist-graph/
+          cp graphify-out/graph.html dist-graph/
+          [ -f graphify-out/GRAPH_REPORT.md ] && cp graphify-out/GRAPH_REPORT.md dist-graph/ || true
+          tar -czf graphify-self-graph.tar.gz -C dist-graph .
+          echo "Asset contents:"
+          tar -tzf graphify-self-graph.tar.gz
+
+      - name: Upload to GitHub release
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@v2
+        with:
+          files: graphify-self-graph.tar.gz
+
+      - name: Upload as workflow artifact (for workflow_dispatch runs)
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/upload-artifact@v4
+        with:
+          name: graphify-self-graph
+          path: graphify-self-graph.tar.gz
+          retention-days: 7

.gitignore

@@ -13,3 +13,27 @@ build/
 *.so
 *.egg
 .graphify/
+graphify-out/
+.graphify_*.json
+.graphify_python
+.claude/
+skills/
+# The packaged skill bundles under graphify/skills/ are generated, committed
+# artifacts (rendered by tools/skillgen). Keep them tracked even though the
+# broad skills/ rule above ignores install-target skill dirs elsewhere.
+!graphify/skills/
+!graphify/skills/**
+# The skillgen core fragments are the human-edited source of the lean SKILL.md.
+# A global "core" ignore (for core dumps) would otherwise drop them.
+!tools/skillgen/fragments/core/
+!tools/skillgen/fragments/core/**
+docs/superpowers/
+.vscode/
+.kilo
+openspec/
+# Local benchmark scripts — never commit
+scripts/run_k2_*.py
+scripts/llm.py
+scripts/benchmark_kimi*.json
+scripts/benchmark_kimi*.py
+paper/

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+# Run with: uv run pre-commit install   (pre-commit is already a dev dependency)
+# One-off across the tree: uv run pre-commit run --all-files
+#
+# The skillgen hook is the local anti-drift guard. The skill files under
+# graphify/ are generated from the fragments in tools/skillgen/; a hand-edit to
+# a generated file fails this check the same way CI does. Run
+# `python -m tools.skillgen` then `--bless` to regenerate after a fragment edit.
+repos:
+  - repo: local
+    hooks:
+      - id: skillgen-check
+        name: skillgen --check (generated skill artifacts are up to date)
+        entry: python -m tools.skillgen --check
+        language: system
+        pass_filenames: false
+        always_run: true
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+      - id: ruff
+        args: ["--config", "pyproject.toml"]

AGENTS.md

@@ -0,0 +1,8 @@
+## graphify
+
+This project has a graphify knowledge graph at graphify-out/.
+
+Rules:
+- Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
+- If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
+- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Architecture
+
+graphify is a Claude Code skill backed by a Python library. The skill orchestrates the library; the library can be used standalone.
+
+## Pipeline
+
+```
+detect()  →  extract()  →  build_graph()  →  cluster()  →  analyze()  →  report()  →  export()
+```
+
+Each stage is a single function in its own module. They communicate through plain Python dicts and NetworkX graphs - no shared state, no side effects outside `graphify-out/`.
+
+## Module responsibilities
+
+| Module | Function | Input → Output |
+|--------|----------|----------------|
+| `detect.py` | `collect_files(root)` | directory → `[Path]` filtered list |
+| `extract.py` | `extract(path)` | file path → `{nodes, edges}` dict |
+| `build.py` | `build_graph(extractions)` | list of extraction dicts → `nx.Graph` |
+| `cluster.py` | `cluster(G)` | graph → graph with `community` attr on each node |
+| `analyze.py` | `analyze(G)` | graph → analysis dict (god nodes, surprises, questions) |
+| `report.py` | `render_report(G, analysis)` | graph + analysis → GRAPH_REPORT.md string |
+| `export.py` | `export(G, out_dir, ...)` | graph → Obsidian vault, graph.json, graph.html, graph.svg |
+| `callflow_html.py` | `write_callflow_html(...)` | graphify-out files → Mermaid architecture/call-flow HTML |
+| `ingest.py` | `ingest(url, ...)` | URL → file saved to corpus dir |
+| `cache.py` | `check_semantic_cache / save_semantic_cache` | files → (cached, uncached) split |
+| `security.py` | validation helpers | URL / path / label → validated or raises |
+| `validate.py` | `validate_extraction(data)` | extraction dict → raises on schema errors |
+| `serve.py` | `start_server(graph_path)` | graph file path → MCP stdio server |
+| `watch.py` | `watch(root, flag_path)` | directory → writes flag file on change |
+| `benchmark.py` | `run_benchmark(graph_path)` | graph file → corpus vs subgraph token comparison |
+
+## Extraction output schema
+
+Every extractor returns:
+
+```json
+{
+  "nodes": [
+    {"id": "unique_string", "label": "human name", "source_file": "path", "source_location": "L42"}
+  ],
+  "edges": [
+    {"source": "id_a", "target": "id_b", "relation": "calls|imports|uses|...", "confidence": "EXTRACTED|INFERRED|AMBIGUOUS"}
+  ]
+}
+```
+
+`validate.py` enforces this schema before `build_graph()` consumes it.
+
+## Confidence labels
+
+| Label | Meaning |
+|-------|---------|
+| `EXTRACTED` | Relationship is explicitly stated in the source (e.g., an import statement, a direct call) |
+| `INFERRED` | Relationship is a reasonable deduction (e.g., call-graph second pass, co-occurrence in context) |
+| `AMBIGUOUS` | Relationship is uncertain; flagged for human review in GRAPH_REPORT.md |
+
+## Adding a new language extractor
+
+1. Add a `extract_<lang>(path: Path) -> dict` function in `extract.py` following the existing pattern (tree-sitter parse → walk nodes → collect `nodes` and `edges` → call-graph second pass for INFERRED `calls` edges).
+2. Register the file suffix in `extract()` dispatch and `collect_files()`.
+3. Add the suffix to `CODE_EXTENSIONS` in `detect.py` and `_WATCHED_EXTENSIONS` in `watch.py`.
+4. Add the tree-sitter package to `pyproject.toml` dependencies.
+5. Add a fixture file to `tests/fixtures/` and tests to `tests/test_languages.py`.
+
+## Security
+
+All external input passes through `graphify/security.py` before use:
+
+- URLs → `validate_url()` (http/https only) + `_NoFileRedirectHandler` (blocks file:// redirects)
+- Fetched content → `safe_fetch()` / `safe_fetch_text()` (size cap, timeout)
+- Graph file paths → `validate_graph_path()` (must resolve inside `graphify-out/`)
+- Node labels → `sanitize_label()` (strips control chars, caps 256 chars, HTML-escapes)
+
+See `SECURITY.md` for the full threat model.
+
+## Testing
+
+One test file per module under `tests/`. Run with:
+
+```bash
+pytest tests/ -q
+```
+
+All tests are pure unit tests - no network calls, no file system side effects outside `tmp_path`.