Improve dev workflow, lint baseline, refactor CLI, and gate CI

.github/workflows/ci.yml

@@ -46,6 +46,34 @@ jobs:
       - name: Round-trip the always-on blocks against v8
         run: uv run --frozen python -m tools.skillgen --always-on-roundtrip
 
+  lint:
+    # Static-analysis gate. Runs in parallel with skillgen-check / test so
+    # a future ruff regression fails the PR quickly without waiting for
+    # the longer test job to finish.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: uv pip install --system ruff
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: bandit (advisory)
+        # TODO(Phase 8 follow-up): bandit currently reports 5 Medium
+        # confidence issues in graphify/ (3× B104 hardcoded_bind_all_interfaces
+        # in serve.py / mcp_ingest.py, 2× B314 xml.etree.ElementTree.fromstring
+        # in docx_to_markdown / xlsx_extract_structure). Once those are
+        # fixed or triaged with ``# nosec`` annotations, drop the ``|| true``
+        # below so bandit becomes a blocking gate.
+        run: bandit -c pyproject.toml -r graphify || true
+
   test:
     runs-on: ubuntu-latest
     strategy:
@@ -73,7 +101,31 @@ jobs:
       - name: Run tests
         run: uv run --frozen pytest tests/ -q --tb=short
 
+      - name: Build package
+        # Guards against packaging regressions (e.g. broken MANIFEST.in,
+        # missing data files, setuptools deprecation warnings becoming
+        # errors). Fast — wheel build is in the seconds range.
+        run: uv run --frozen python -m build
+
       - name: Verify install works end-to-end
         run: |
           uv run --frozen graphify --help
           uv run --frozen graphify install
+
+      - name: Smoke-test detect
+        # The core file-classification / .graphifyignore pipeline is
+        # non-mutating and is exercised by every real `graphify update`
+        # run, so a regression here breaks every user. We invoke it
+        # directly via the Python API (there is no `graphify detect`
+        # subcommand) and assert the result classifies at least one
+        # code file — i.e. the scan actually found something.
+        run: |
+          uv run --frozen python -c "
+          from pathlib import Path
+          from graphify.detect import detect
+          r = detect(Path('.'))
+          assert r['total_files'] > 0, 'detect found no files'
+          assert 'code' in r['files'], 'no code files detected'
+          assert r['files']['code'], 'code file list is empty'
+          print(f'detect OK: {r[\"total_files\"]} files, {r[\"total_words\"]} words')
+          "

.gitignore

@@ -18,6 +18,7 @@ graphify-out/
 .graphify_python
 .claude/
 skills/
+.hermes/
 # 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.
@@ -28,6 +29,7 @@ skills/
 !tools/skillgen/fragments/core/
 !tools/skillgen/fragments/core/**
 docs/superpowers/
+docs/translations/
 .vscode/
 .kilo
 openspec/

CLAUDE.md

@@ -0,0 +1,9 @@
+## 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
+- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
+- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

README.md

@@ -674,6 +674,17 @@ uv run pytest tests/test_extract.py -q # one module
 uv run pytest tests/ -q -k "python"    # filter by name
 ```
 
+### Lint and packaging
+
+The same gates CI runs are available locally:
+
+```bash
+uv run ruff check .                    # matches the CI `lint` job
+uv run python -m build                 # matches the CI `Build package` step
+```
+
+Run both before opening a PR — they're fast (lint in <1s, build in a few seconds) and catch the most common breakage modes without waiting on the CI round-trip.
+
 > macOS note: the test suite includes both `sample.f90` and `sample.F90` fixtures. These collide on case-insensitive HFS+ / APFS file systems. Run on Linux or in a Docker container if you need to test both Fortran variants simultaneously.
 
 ### Git workflow