OSAC-4014: Sync fork with upstream, clean up stray dirs, merge ci-select

README.md

@@ -794,6 +794,7 @@ graphify label ./my-project --backend=openai --model gpt-4o   # force a specific
 - [How it works](docs/how-it-works.md) — the extraction pipeline, community detection, confidence scoring, benchmarks
 - [ARCHITECTURE.md](ARCHITECTURE.md) — module breakdown, how to add a language
 - [Optional integrations](docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite
+- [Graph bundle metadata](docs/graph-bundle-metadata.md) — schema for `metadata.json` when a `graphify --update` output is published for other machines/CI to pull
 - [The Memory Layer](https://safishamsi.gumroad.com/l/qetvlo) — the book on the ideas behind graphify, the architecture end to end
 
 ---

docs/graph-bundle-metadata.md

@@ -0,0 +1,57 @@
+# graphify bundle metadata (`metadata.json`)
+
+When a `graphify --update` output is published for other machines/CI jobs to
+pull (rather than generated locally), it ships as one atomic bundle:
+`graph.json` + `GRAPH_REPORT.md` + `manifest.json` + a small `metadata.json`
+describing the bundle itself.
+
+`metadata.json` exists because the bundle has two independent consumers that
+must never drift apart on what fields to expect:
+
+- **Writer**: the CI job that runs `graphify --update` and publishes the
+  bundle (e.g. a scheduled graph-refresh workflow).
+- **Reader**: the fetch script that pulls the bundle down and validates it
+  before swapping it into a local `graphify-out/`, ahead of graphify's own
+  `CLAUDE.md` directive / `PreToolUse` hook consuming it.
+
+Both of those live outside this repo (currently: `osac`), but both are built
+against graphify's own output format, so this fork is the natural single
+source of truth for the contract between them -- one documented schema
+instead of two independently-evolving assumptions.
+
+**Schema**: [`graph-bundle-metadata.schema.json`](./graph-bundle-metadata.schema.json)
+(JSON Schema, draft 2020-12).
+
+## Example
+
+```json
+{
+  "schema_version": 1,
+  "source_sha": "e4bfd2ad1a9393251023a4edef93e93dc798afc7",
+  "graphify_version": "0.9.41",
+  "generated_at": "2026-08-13T02:00:00Z",
+  "bundle": {
+    "graph": "graph.json",
+    "report": "GRAPH_REPORT.md",
+    "manifest": "manifest.json"
+  }
+}
+```
+
+## What each field is for
+
+- `source_sha` / `generated_at`: staleness. A consumer compares `source_sha`
+  against its local `HEAD` (ancestry check, not a race guard -- the bundle's
+  own publish path is already serialized by a CI `concurrency:` group); when
+  that comparison isn't possible, `generated_at` backs a TTL fallback.
+- `graphify_version`: a hard compatibility gate. A version mismatch against
+  the locally-installed `graphify --version` means the fetch script refuses
+  to load the bundle and prints the exact upgrade command, rather than
+  risking a schema-mismatched `graph.json` being consulted silently.
+- `bundle`: where the other three files live inside the archive, so the
+  reader doesn't hardcode filenames independently of what the writer chose.
+
+`manifest.json` rides along for the *writer's* own benefit (restoring
+incremental-extraction continuity across ephemeral CI runners between
+scheduled runs) -- ordinary consumers only need `graph.json` and
+`GRAPH_REPORT.md`.

docs/graph-bundle-metadata.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/eliorerz/graphify/blob/main/docs/graph-bundle-metadata.schema.json",
+  "title": "graphify knowledge-graph bundle metadata",
+  "description": "Schema for metadata.json, the small manifest bundled alongside graph.json/GRAPH_REPORT.md/manifest.json when a graphify --update output is published as a release/OCI artifact. Written by the CI job that runs `graphify --update` and publishes the bundle; read by the fetch script that pulls the bundle down before graphify's CLAUDE.md directive/PreToolUse hook consult it. This is the single canonical definition both sides validate against, so the writer and reader can't drift independently -- see one caller in osac/, e.g. a scheduled graph-refresh workflow, the other in a SessionStart fetch script, both in the same repo.",
+  "type": "object",
+  "required": ["schema_version", "source_sha", "graphify_version", "generated_at", "bundle"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Version of this metadata.json schema itself, not of graphify or the bundle contents. Bump on any breaking change to this file's shape so a reader can refuse an unrecognized version cleanly instead of guessing at missing/renamed fields."
+    },
+    "source_sha": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$",
+      "description": "Full git commit SHA of the source repository HEAD that graphify --update was run against. The staleness check compares this against a consumer's local HEAD (via `git merge-base --is-ancestor`, used purely as a freshness signal, not a publish-time race guard)."
+    },
+    "graphify_version": {
+      "type": "string",
+      "description": "Output of `graphify --version` for the graphify install that generated this bundle (e.g. \"0.9.41\"). The fetch script refuses to load a bundle whose graphify_version doesn't match the locally installed `graphify --version`, printing the exact upgrade command, rather than silently loading a graph shaped by a different schema/format version."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC timestamp of when this bundle was published. Backs the TTL fallback staleness check (e.g. treat the bundle as stale if generated_at is >24h old) for the case where source_sha ancestry comparison isn't possible (e.g. consumer's local HEAD is on an unrelated branch/fork)."
+    },
+    "bundle": {
+      "type": "object",
+      "required": ["graph", "report", "manifest"],
+      "additionalProperties": false,
+      "description": "Paths, relative to the archive root, of the other files published alongside this metadata.json in the same atomic bundle (a single archive, so a consumer either gets the whole matched set or a clean 404/missing-bundle, never a mismatched pair from two different publishes).",
+      "properties": {
+        "graph": {
+          "type": "string",
+          "description": "Path to graph.json -- the queryable knowledge graph itself. What ordinary consumers (graphify's PreToolUse hook, ci-select) actually load."
+        },
+        "report": {
+          "type": "string",
+          "description": "Path to GRAPH_REPORT.md -- the human-readable summary of the graph."
+        },
+        "manifest": {
+          "type": "string",
+          "description": "Path to manifest.json -- graphify's own incremental-extraction state. Only needed by the generation workflow itself to restore continuity before its next `graphify --update` run (see the artifact-re-pull fallback for actions/cache eviction); ordinary consumers querying the graph never need to open it."
+        }
+      }
+    }
+  }
+}

graphify/__main__.py

@@ -623,6 +623,14 @@ def _run_cli() -> None:
         print("  global remove <tag>      remove a repo's nodes from the global graph")
         print("  global list              list repos in the global graph")
         print("  global path              print path to the global graph file")
+        print("  ci-select               graph-informed CI test selection from a diff")
+        print("    --repo <name>           repository name (required)")
+        print("    --diff-cmd <cmd>        shell command to produce a diff (e.g. 'git diff origin/main...HEAD')")
+        print("    --diff <path|->         read diff from file or stdin")
+        print("    --files <f1,f2,...>      comma-separated changed file paths")
+        print("    --graph <path>          path to graph.json (default graphify-out/graph.json)")
+        print("    --test-jobs <path>      path to test-jobs.yaml mapping (auto-detected if omitted)")
+        print("    --depth N               BFS traversal depth (default 3)")
         print("  benchmark [graph.json]  measure token reduction vs naive full-corpus approach")
         print("  export callflow-html    emit Mermaid-based architecture/call-flow HTML")
         print("  hook install            install post-commit/post-checkout git hooks (all platforms)")