[MINOR] chore: merge develop to main

.agent/project.md

@@ -6,13 +6,6 @@ Supervaizer is the open-source controller library and FastAPI server that AI age
 
 This repo is public and packaged for external users, so API compatibility, typed payloads, generated documentation, and clear tests matter more than local convenience.
 
-## Local Glossary / Terminology
-
-- **Controller**: The Supervaizer FastAPI service embedded with or run alongside an AI agent.
-- **Studio**: The Supervaize SaaS platform that receives registration/events and operates mapped agents.
-- **Mapped agent**: An agent capability exposed through Supervaizer for Studio control.
-- **Registration payload**: The `server.register` payload consumed by Studio.
-
 ## Data Sensitivity Notes
 
 - Do not log or commit API keys, server secrets, workspace tokens, or customer data.

.claude/skills/gitnexus/gitnexus-cli/SKILL.md

@@ -24,6 +24,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | `--force`      | Force full re-index even if up to date                           |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
 | `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
+| `--pdg` | Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF). |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
 

.claude/skills/gitnexus/gitnexus-debugging/SKILL.md

@@ -16,10 +16,10 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 ## Workflow
 
 ```
-1. query({query: "<error or symptom>"})            → Find related execution flows
+1. query({search_query: "<error or symptom>"})            → Find related execution flows
 2. context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({query: "MATCH path..."})                 → Custom traces if needed
+4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
 ```
 
 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@@ -45,13 +45,14 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
 | Recent regression    | `detect_changes` to see what your changes affect           |
+| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
 
 ## Tools
 
 **query** — find code related to error:
 
 ```
-query({query: "payment validation error"})
+query({search_query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
@@ -72,10 +73,21 @@ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "valid
 RETURN [n IN nodes(path) | n.name] AS chain
 ```
 
+**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
+
+```
+trace({ from: "processCheckout", to: "fetchRates" })
+→ status: ok, hopCount: 3
+→ hops: processCheckout → validatePayment → verifyCard → fetchRates
+→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
+```
+
+When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
+
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```
-1. query({query: "payment error handling"})
+1. query({search_query: "payment error handling"})
    → Processes: CheckoutFlow, ErrorHandling
    → Symbols: validatePayment, handlePaymentError
 

.claude/skills/gitnexus/gitnexus-exploring/SKILL.md

@@ -18,7 +18,7 @@ description: "Use when the user asks how code works, wants to understand archite
 ```
 1. READ gitnexus://repos                          → Discover indexed repos
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({query: "<what you want to understand>"})  → Find related execution flows
+3. query({search_query: "<what you want to understand>"})  → Find related execution flows
 4. context({name: "<symbol>"})            → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
@@ -50,7 +50,7 @@ description: "Use when the user asks how code works, wants to understand archite
 **query** — find execution flows related to a concept:
 
 ```
-query({query: "payment processing"})
+query({search_query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
@@ -68,7 +68,7 @@ context({name: "validateUser"})
 
 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. query({query: "payment processing"})
+2. query({search_query: "payment processing"})
    → CheckoutFlow: processPayment → validateCard → chargeStripe
    → RefundFlow: initiateRefund → calculateRefund → processRefund
 3. context({name: "processPayment"})

.claude/skills/gitnexus/gitnexus-guide/SKILL.md

@@ -35,9 +35,19 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `query`          | Process-grouped code intelligence — execution flows related to a concept |
 | `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
 | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `trace`          | Shortest path between two symbols — "how does A reach B?" in one call     |
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `explain`        | Persisted taint findings — source→sink data flows (needs `analyze --pdg`) |
+| `pdg_query`      | Control/data dependence — what gates X (CDG) / where Y flows (REACHING_DEF); needs `analyze --pdg` |
+| `check`          | Check graph invariants such as circular imports                          |
+| `route_map`      | API route map — which components/hooks fetch which endpoints, and the handler files that serve them |
+| `shape_check`    | Response-shape drift — keys each route returns vs keys its consumers access (flags MISMATCH) |
+| `api_impact`     | Pre-change report for an API route — consumers, middleware, shape mismatches, risk level |
+| `tool_map`       | MCP/RPC tool definitions and the files that handle them                  |
+| `group_list`     | List configured multi-repo groups, or one group's config                 |
+| `group_sync`     | Rebuild a group's Contract Registry (cross-repo HTTP contract links); run after `group.yaml` changes or member re-index |
 | `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                    |
 
 ### Paginating `list_repos`
@@ -71,6 +81,37 @@ list_repos { offset: 400 }  → repos 401–437,                 hasMore false
 
 Notes: `offset` ≥ `total` returns an empty page (with `total` still reported). Out-of-range or malformed `limit`/`offset` (non-integer, `limit` outside `[1, 200]`, `offset < 0`) are rejected with a clear error — `limit` above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.
 
+### Taint findings (`explain`)
+
+`explain` returns taint findings recorded by `gitnexus analyze --pdg` — intra-procedural `TAINTED` edges plus cross-function `TAINT_PATH` hops where the interprocedural taint phase found a function-level source→sink chain. Each finding includes a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.
+
+- `explain {}` — enumerate all findings for the repo (bounded by `limit`, deterministic order)
+- `explain { target: "src/vuln.ts" }` — findings in a file (suffix path match accepted)
+- `explain { target: "runUserCommand" }` — findings in a function (resolved like `context`; ambiguous names return ranked candidates)
+
+A repo indexed without `--pdg` returns a clear "no taint layer" note. Caveats: closure/callback, property/field, and implicit flows are not modeled, and interprocedural findings are function-level `TAINT_PATH` hops rather than statement-level path proof, so the absence of a finding is **not** proof of safety. `SANITIZES` (sanitizer-kill) edges are queryable via `cypher`.
+
+### Control & data dependence (`pdg_query`)
+
+`pdg_query` reads the control/data-dependence layers `gitnexus analyze --pdg` records (CDG + REACHING_DEF, basic-block granular) — the control/data analog of `explain`. It is **always anchored** (a `target` file path or symbol, resolved like `context`) and has two modes:
+
+- `pdg_query { mode: "controls", target: "..." }` — CDG: "under what condition does X run?". Each edge is a controlling predicate block → dependent block with the branch sense (`'T'`/`'F'`) in `reason`; an edge into an early `return`/`throw` is flagged `guard: true` (guard-clause discovery — the sense depends on the predicate, so don't filter guards by a fixed label).
+- `pdg_query { mode: "flows", target: "...", variable?: "..." }` — REACHING_DEF def→use edges within the function; pass `variable` to trace one binding.
+
+A repo indexed without `--pdg` returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra-procedural only — cross-function flow is taint's domain (`explain`). The raw CDG/REACHING_DEF edges are also queryable via `cypher`. See the `gitnexus-pdg-query` skill for the full query surface.
+
+### Shortest path between two symbols (`trace`)
+
+`trace` answers "how does A reach B?" in one call — the shortest directed path over `CALLS` (plus `HAS_METHOD`, so a class-rooted trace descends into its methods) instead of chaining 3–8 `context`/`impact` hops by hand.
+
+- `trace { from: "validateUser", to: "executeQuery" }` — shortest path between two symbols.
+- Disambiguate common names with `from_uid`/`to_uid` (zero-ambiguity) or `from_file`/`to_file`; an ambiguous name returns ranked candidates.
+- `maxDepth` (default 10, max 30) bounds the search; `includeTests` (default false) lets the traversal pass through test-file symbols.
+
+Returns ordered `hops` (each `{ name, filePath, startLine }`) and an aligned `edges[]` of `{ relType, confidence }`, so call hops and containment (`HAS_METHOD`) hops stay distinguishable. When no path exists it reports the **furthest** reachable node (where the chain breaks) and sets `truncated: true` if a traversal cap was hit first. Every result carries a `status`: `ok` / `no_path` / `ambiguous` / `not_found` / `error`.
+
+Cross-repo (experimental): pass `repo: "@groupName"` to trace across a group's member repos — the path may cross **one** `ContractLink` boundary (reported as a `CONTRACT_LINK` hop with the bridged contract in `crossings[]`). Omit `to` entirely to follow `from`'s outgoing HTTP call to whatever provider endpoint it lands on. Groups are configured via `group_list` / `group_sync`.
+
 ## Resources Reference
 
 Lightweight reads (~100-500 tokens) for navigation:
@@ -86,8 +127,10 @@ Lightweight reads (~100-500 tokens) for navigation:
 
 ## Graph Schema
 
-**Nodes:** File, Function, Class, Interface, Method, Community, Process
-**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+**Nodes:** File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process, Route, Tool, plus language-specific types (Struct, Enum, Trait, Impl, Namespace, Module, …) and BasicBlock (`--pdg` indexes only). The full node list lives in `gitnexus://repo/{name}/schema`.
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, CONTAINS, MEMBER_OF, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF, WRAPS, QUERIES, INJECTS, plus `--pdg`-only types (CFG, REACHING_DEF, TAINTED, SANITIZES, TAINT_PATH, CDG — zero rows on a default index).
+
+Read `gitnexus://repo/{name}/schema` before writing Cypher — it is the authoritative schema for the indexed repo.
 
 ```cypher
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})

.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md

@@ -17,7 +17,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 
 ```
 1. impact({target: "X", direction: "upstream"})  → Map all dependents
-2. query({query: "X"})                            → Find execution flows involving X
+2. query({search_query: "X"})                            → Find execution flows involving X
 3. context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```
@@ -30,7 +30,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 
 ```
 - [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
-- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
+- [ ] Review graph edits (high confidence) and text_search edits (review carefully)
 - [ ] If satisfied: rename({..., dry_run: false}) — apply edits
 - [ ] detect_changes() — verify only expected files changed
 - [ ] Run tests for affected processes
@@ -66,7 +66,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 ```
 rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
 → 12 edits across 8 files
-→ 10 graph edits (high confidence), 2 ast_search edits (review)
+→ 10 graph edits (high confidence), 2 text_search edits (review)
 → Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
 ```
 
@@ -107,10 +107,10 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
 
 ```
 1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
-   → 12 edits: 10 graph (safe), 2 ast_search (review)
+   → 12 edits: 10 graph (safe), 2 text_search (review)
    → Files: validator.ts, login.ts, middleware.ts, config.json...
 
-2. Review ast_search edits (config.json: dynamic reference!)
+2. Review text_search edits (config.json: dynamic reference!)
 
 3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
    → Applied 12 edits across 8 files

.github/workflows/publish-pypi.yml

@@ -35,12 +35,12 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           enable-cache: true
 
@@ -78,7 +78,7 @@ jobs:
         run: hatch build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
         with:
           packages-dir: dist/
 

.github/workflows/publish.yml

@@ -18,7 +18,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
 

.github/workflows/python-package.yml

@@ -78,10 +78,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
       - name: Install dependencies
         run: uv sync --frozen --extra dev
       - name: Run pre-commit hooks
@@ -109,11 +109,11 @@ jobs:
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
         with:
           # Avoid parallel matrix jobs racing on the same Actions cache reservation
           cache-suffix: py-${{ matrix.python-version }}

.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
           fetch-depth: 0 # Required for generating release notes
 
       - name: Create Release
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           generate_release_notes: true
           draft: false

.github/workflows/trufflehog-full-scan.yml

@@ -24,6 +24,6 @@ jobs:
 
       - name: Full Repository Scan
         if: inputs.scan_type == 'full-repo'
-        uses: trufflesecurity/trufflehog@f446421baf832d6356c42c1743d99abff52ff334 # v3.95.7
+        uses: trufflesecurity/trufflehog@27b0417c16317ca9a472a9a8092acce143b49c55 # v3.95.9
         with:
           extra_args: --results=verified,unknown

.github/workflows/trufflehog-security.yml

@@ -21,6 +21,6 @@ jobs:
           fetch-depth: 0 # Required for TruffleHog to scan git history
 
       - name: Secret Scanning
-        uses: trufflesecurity/trufflehog@f446421baf832d6356c42c1743d99abff52ff334 # v3.95.7
+        uses: trufflesecurity/trufflehog@27b0417c16317ca9a472a9a8092acce143b49c55 # v3.95.9
         with:
           extra_args: --results=verified,unknown