fix(server): log skip-embedding count and table-not-found swallow path

Addresses review feedback on PR #823:
- Log count of already-embedded nodes when skipNodeIds is populated
  (aids debugging if Kuzu driver row shape changes).
- Log when the 'table does not exist' swallow path fires so ops can
  catch it if Kuzu ever changes error wording.
- Document the {} config positional argument with an inline comment
  referencing the runEmbeddingPipeline signature.

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

@@ -17,13 +17,12 @@ npx gitnexus analyze
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
 
-| Flag                | Effect                                                                                                  |
-| ------------------- | ------------------------------------------------------------------------------------------------------- |
-| `--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.    |
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
 
-**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.
+**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 runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
 
 ### status — Check index freshness
 

.cursor/.gitignore

@@ -1 +0,0 @@
-plans/

.dockerignore

@@ -1,21 +0,0 @@
-.git
-.gitignore
-.DS_Store
-
-node_modules
-**/node_modules
-
-dist
-**/dist
-coverage
-**/coverage
-
-.env
-.env.local
-.env.*.local
-
-**/*.tsbuildinfo
-
-.gitnexus
-gitnexus-web/playwright-report
-gitnexus-web/test-results

.env.example

@@ -1,19 +0,0 @@
-# Images (signed Cosign keyless on every push from main / vX.Y.Z tags).
-# Available from both GHCR (default below) and Docker Hub — pick one:
-#   GHCR:       ghcr.io/abhigyanpatwari/gitnexus{,-web}:latest
-#   Docker Hub: akonlabs/gitnexus{,-web}:latest
-# Both registries receive the same digest from a single signed build.
-SERVER_IMAGE=ghcr.io/abhigyanpatwari/gitnexus:latest
-WEB_IMAGE=ghcr.io/abhigyanpatwari/gitnexus-web:latest
-
-# Container names
-SERVER_CONTAINER_NAME=gitnexus-server
-WEB_CONTAINER_NAME=gitnexus-web
-
-# Host ports — the web UI expects the server on http://localhost:4747 by default.
-SERVER_HOST_PORT=4747
-WEB_HOST_PORT=4173
-
-# Optional read-only mount, exposed to the server as /workspace.
-# Override with the directory that contains the repos you want to index.
-WORKSPACE_DIR=./

.github/actions/docker-build-push-retry/action.yml

@@ -1,105 +0,0 @@
-# Wraps docker/build-push-action with one automatic retry. Upstream explicitly
-# keeps retry out of the action (docker/build-push-action#1422); a local
-# composite keeps docker.yml readable and pins the same action SHA in one place.
-name: Docker build-push (with retry)
-description: >-
-  Runs docker/build-push-action twice on failure with a configurable backoff,
-  then exposes the digest from whichever attempt succeeded.
-
-inputs:
-  context:
-    description: Build context path
-    required: false
-    default: '.'
-  file:
-    description: Dockerfile path (relative to repo root)
-    required: true
-  platforms:
-    description: Comma-separated platforms list for buildx
-    required: true
-  push:
-    description: Whether to push (string 'true' or 'false')
-    required: true
-  tags:
-    description: Newline-separated image tags (from docker/metadata-action)
-    required: true
-  labels:
-    description: Labels string (from docker/metadata-action)
-    required: true
-  cache-from:
-    description: buildx cache-from value
-    required: true
-  cache-to:
-    description: buildx cache-to value (include ignore-error=true for GHA cache flakes)
-    required: true
-  retry-wait-seconds:
-    description: Seconds to sleep before the second attempt
-    required: false
-    default: '45'
-
-outputs:
-  digest:
-    description: Manifest digest from the successful build attempt
-    value: ${{ steps.resolve.outputs.digest }}
-
-runs:
-  using: composite
-  steps:
-    - name: Build and push (attempt 1)
-      id: try1
-      continue-on-error: true
-      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
-      with:
-        context: ${{ inputs.context }}
-        file: ${{ inputs.file }}
-        platforms: ${{ inputs.platforms }}
-        push: ${{ inputs.push == 'true' }}
-        tags: ${{ inputs.tags }}
-        labels: ${{ inputs.labels }}
-        cache-from: ${{ inputs.cache-from }}
-        cache-to: ${{ inputs.cache-to }}
-        provenance: mode=max
-        sbom: true
-
-    - name: Backoff before Docker build retry
-      if: steps.try1.outcome == 'failure'
-      shell: bash
-      env:
-        RETRY_WAIT_SECONDS: ${{ inputs.retry-wait-seconds }}
-      run: |
-        echo "::warning::Docker build-push attempt 1 failed; retrying in ${RETRY_WAIT_SECONDS}s…"
-        sleep "${RETRY_WAIT_SECONDS}"
-
-    - name: Build and push (attempt 2)
-      id: try2
-      if: steps.try1.outcome == 'failure'
-      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
-      with:
-        context: ${{ inputs.context }}
-        file: ${{ inputs.file }}
-        platforms: ${{ inputs.platforms }}
-        push: ${{ inputs.push == 'true' }}
-        tags: ${{ inputs.tags }}
-        labels: ${{ inputs.labels }}
-        cache-from: ${{ inputs.cache-from }}
-        cache-to: ${{ inputs.cache-to }}
-        provenance: mode=max
-        sbom: true
-
-    - name: Resolve image digest
-      id: resolve
-      if: always()
-      shell: bash
-      run: |
-        set -euo pipefail
-        if [ "${{ steps.try1.outcome }}" = "success" ]; then
-          echo "digest=${{ steps.try1.outputs.digest }}" >> "$GITHUB_OUTPUT"
-          exit 0
-        fi
-        if [ "${{ steps.try2.outcome }}" = "success" ]; then
-          echo "::notice::docker-build-push retry succeeded (attempt 2); investigate if this recurs across runs."
-          echo "digest=${{ steps.try2.outputs.digest }}" >> "$GITHUB_OUTPUT"
-          exit 0
-        fi
-        echo "::error::Docker build and push failed after two attempts (registry/cache flake or real build error)."
-        exit 1

.github/actions/setup-gitnexus-web/action.yml

@@ -1,13 +1,12 @@
 name: Setup GitNexus Web
-description: Setup Node.js 22, build gitnexus-shared, install web dependencies
+description: Setup Node.js 20, build gitnexus-shared, install web dependencies
 
 runs:
   using: composite
   steps:
     - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
       with:
-        # Vite 7 requires Node ^20.19.0 || >=22.12.0 (require(esm) support).
-        node-version: 22
+        node-version: 20
         cache: npm
         cache-dependency-path: gitnexus-web/package-lock.json
 

.github/actions/setup-gitnexus/action.yml

@@ -1,5 +1,5 @@
 name: Setup GitNexus
-description: Setup Node.js 22, install dependencies, and optionally build
+description: Setup Node.js 20, install dependencies, and optionally build
 
 inputs:
   build:
@@ -12,7 +12,7 @@ runs:
   steps:
     - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
       with:
-        node-version: 22
+        node-version: 20
         cache: npm
         cache-dependency-path: gitnexus/package-lock.json
 

.github/dependabot.yml

@@ -1,122 +0,0 @@
-version: 2
-updates:
-  # Keep third-party Actions SHA pins current. See CONTRIBUTING.md — when
-  # reviewing these bumps, verify the SHA corresponds to the claimed tag by
-  # running `gh api repos/<owner>/<action>/git/refs/tags/<tag>` before merge.
-  - package-ecosystem: github-actions
-    directory: /
-    schedule:
-      interval: weekly
-    cooldown:
-      default-days: 7
-    open-pull-requests-limit: 5
-    commit-message:
-      prefix: chore
-      include: scope
-    labels:
-      - dependencies
-      - ci
-
-  # Keep pinned Docker base-image digests current for the root Dockerfiles.
-  - package-ecosystem: docker
-    directory: /
-    schedule:
-      interval: weekly
-    cooldown:
-      default-days: 7
-    open-pull-requests-limit: 5
-    commit-message:
-      prefix: chore(deps)
-      include: scope
-    labels:
-      - dependencies
-      - ci
-
-  # Keep the nested test-image Docker base digest current as well.
-  - package-ecosystem: docker
-    directory: /gitnexus
-    schedule:
-      interval: weekly
-    cooldown:
-      default-days: 7
-    open-pull-requests-limit: 5
-    commit-message:
-      prefix: chore(deps)
-      include: scope
-    labels:
-      - dependencies
-      - ci
-
-  # Gitnexus npm deps — tree-sitter grammars checked daily so we catch
-  # new releases that unblock the tree-sitter 0.25 upgrade ASAP. Grammars
-  # are grouped so lockstep bumps produce a single PR. The tree-sitter
-  # RUNTIME is pinned — upgrade deliberately via the drift check workflow.
-  # See .github/scripts/check-tree-sitter-upgrade-readiness.py for
-  # the upgrade readiness tracker.
-  - package-ecosystem: npm
-    directory: /gitnexus
-    schedule:
-      interval: daily
-    cooldown:
-      default-days: 7
-      semver-major-days: 30
-      semver-minor-days: 7
-      semver-patch-days: 3
-    open-pull-requests-limit: 10
-    commit-message:
-      prefix: chore(deps)
-      include: scope
-    labels:
-      - dependencies
-    groups:
-      tree-sitter-grammars:
-        patterns:
-          - tree-sitter-*
-        exclude-patterns:
-          - tree-sitter
-          - tree-sitter-cli
-    ignore:
-      # Pin the tree-sitter runtime at 0.21.x until the drift check
-      # reports all grammars are peer-dep compatible with 0.25.
-      - dependency-name: tree-sitter
-        update-types:
-          - version-update:semver-major
-          - version-update:semver-minor
-      # tree-sitter-cli follows the runtime's version cadence. Bump when
-      # regenerating vendor/tree-sitter-proto/src/parser.c, not on a schedule.
-      - dependency-name: tree-sitter-cli
-
-  # gitnexus-web (thin frontend client).
-  - package-ecosystem: npm
-    directory: /gitnexus-web
-    schedule:
-      interval: weekly
-    cooldown:
-      default-days: 7
-      semver-major-days: 30
-      semver-minor-days: 7
-      semver-patch-days: 3
-    open-pull-requests-limit: 5
-    commit-message:
-      prefix: chore(deps)
-      include: scope
-    labels:
-      - dependencies
-      - frontend
-
-  # Shared types package.
-  - package-ecosystem: npm
-    directory: /gitnexus-shared
-    schedule:
-      interval: weekly
-    cooldown:
-      default-days: 7
-      semver-major-days: 30
-      semver-minor-days: 7
-      semver-patch-days: 3
-    open-pull-requests-limit: 5
-    commit-message:
-      prefix: chore(deps)
-      include: scope
-    labels:
-      - dependencies

.github/release-drafter.yml

@@ -1,53 +0,0 @@
-# release-drafter config — used only for PR autolabeling by
-# `.github/workflows/pr-labeler.yml` (the workflow passes `disable-releaser: true`,
-# so the draft-release side of release-drafter never runs).
-#
-# The labels applied here are the same ones `.github/release.yml` maps to
-# categorized release-notes sections.
-#
-# `sync-labels: true` removes managed autolabels that no longer match the PR —
-# critical for the breaking-change case: if a PR title drops the `!` or the body
-# drops `BREAKING CHANGE:`, the `breaking` label is pulled off automatically.
-
-# Required by release-drafter; not used because releaser is disabled.
-name-template: 'unused'
-tag-template: 'unused'
-template: |
-  $CHANGES
-
-sync-labels: true
-
-autolabeler:
-  - label: enhancement
-    title:
-      - '/^feat(\([^)]+\))?!?:/i'
-  - label: bug
-    title:
-      - '/^fix(\([^)]+\))?!?:/i'
-  - label: performance
-    title:
-      - '/^perf(\([^)]+\))?!?:/i'
-  - label: refactor
-    title:
-      - '/^refactor(\([^)]+\))?!?:/i'
-  - label: documentation
-    title:
-      - '/^docs(\([^)]+\))?!?:/i'
-  - label: test
-    title:
-      - '/^test(\([^)]+\))?!?:/i'
-  - label: ci
-    title:
-      - '/^ci(\([^)]+\))?!?:/i'
-  - label: dependencies
-    title:
-      - '/^(build|deps)(\([^)]+\))?!?:/i'
-  - label: chore
-    title:
-      - '/^(chore|revert)(\([^)]+\))?!?:/i'
-  # Breaking-change marker: either `!` in the type prefix or `BREAKING CHANGE:` in body.
-  - label: breaking
-    title:
-      - '/^[a-z]+(\([^)]+\))?!:/i'
-    body:
-      - '/BREAKING[ -]CHANGE:/i'

.github/scripts/check-tree-sitter-upgrade-readiness.py

@@ -1,809 +0,0 @@
-#!/usr/bin/env python3
-"""Monitor tree-sitter 0.25 upgrade readiness.
-
-Tracks two things Dependabot cannot see:
-
-  1. Peer-dep compatibility. Each tree-sitter-* grammar declares a peer
-     dependency on the tree-sitter runtime. We want to know when every
-     grammar's *latest npm release* satisfies tree-sitter@0.25.0 so we
-     can upgrade without --legacy-peer-deps.
-
-  2. Vendored upstream drift. vendor/tree-sitter-proto/ is a snapshot of
-     coder3101/tree-sitter-proto's parser.c. When upstream moves, we want
-     to know whether we can pick it up.
-
-Invoked from .github/workflows/tree-sitter-upgrade-readiness.yml daily.
-Runs locally too:
-
-    python3 .github/scripts/check-tree-sitter-upgrade-readiness.py
-
-Outputs Markdown to stdout. Exit 0 when every grammar is upgrade-ready
-and the vendored proto is in sync. Exit 1 when blockers remain (the
-workflow uses this to open or update a tracking issue).
-
-No external deps -- stdlib only, so it runs on any vanilla runner.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import pathlib
-import re
-import sys
-import urllib.error
-import urllib.parse
-import urllib.request
-
-REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
-GITNEXUS_DIR = REPO_ROOT / "gitnexus"
-
-# ── Upgrade target ──────────────────────────────────────────────────────
-# The runtime version we want to upgrade TO. Update this when the goal
-# changes (e.g. once 0.25 lands and we target 0.26).
-TARGET_RUNTIME = "0.25.0"
-TARGET_RUNTIME_MAJOR_MINOR = ".".join(TARGET_RUNTIME.split(".")[:2])
-
-# Tree-sitter runtime -> (min_abi, max_abi) it can load. Only the current
-# and target entries matter; extend when changing TARGET_RUNTIME.
-RUNTIME_ABI_RANGES: dict[str, tuple[int, int]] = {
-    "0.21": (13, 14),
-    "0.25": (13, 15),
-}
-
-assert TARGET_RUNTIME_MAJOR_MINOR in RUNTIME_ABI_RANGES, (
-    f"RUNTIME_ABI_RANGES has no entry for {TARGET_RUNTIME_MAJOR_MINOR!r}. "
-    f"Add the ABI range after auditing the upstream release notes."
-)
-
-# Grammars we use. Values are the upstream GitHub repos to check for
-# unreleased ABI bumps (owner/repo, branch, parser.c path).
-GRAMMARS: dict[str, tuple[str, str, str]] = {
-    "tree-sitter-c":          ("tree-sitter/tree-sitter-c",          "master", "src/parser.c"),
-    "tree-sitter-c-sharp":    ("tree-sitter/tree-sitter-c-sharp",    "master", "src/parser.c"),
-    "tree-sitter-cpp":        ("tree-sitter/tree-sitter-cpp",        "master", "src/parser.c"),
-    "tree-sitter-dart":       ("UserNobody14/tree-sitter-dart",      "master", "src/parser.c"),
-    "tree-sitter-go":         ("tree-sitter/tree-sitter-go",         "master", "src/parser.c"),
-    "tree-sitter-java":       ("tree-sitter/tree-sitter-java",       "master", "src/parser.c"),
-    "tree-sitter-javascript": ("tree-sitter/tree-sitter-javascript", "master", "src/parser.c"),
-    "tree-sitter-kotlin":     ("fwcd/tree-sitter-kotlin",            "main",   "src/parser.c"),
-    "tree-sitter-php":        ("tree-sitter/tree-sitter-php",        "master", "php/src/parser.c"),
-    "tree-sitter-python":     ("tree-sitter/tree-sitter-python",     "master", "src/parser.c"),
-    "tree-sitter-ruby":       ("tree-sitter/tree-sitter-ruby",       "master", "src/parser.c"),
-    "tree-sitter-rust":       ("tree-sitter/tree-sitter-rust",       "master", "src/parser.c"),
-    "tree-sitter-swift":      ("alex-pinkus/tree-sitter-swift",      "main",   "src/parser.c"),
-    "tree-sitter-typescript": ("tree-sitter/tree-sitter-typescript", "master",  "typescript/src/parser.c"),
-    # Vendored parsers — kept here so the upstream coords for drift
-    # detection are co-located with every other grammar's coords.
-    "tree-sitter-proto":      ("coder3101/tree-sitter-proto",        "main",   "src/parser.c"),
-}
-
-# Grammars deliberately held below npm latest. The readiness report surfaces
-# these so reviewers can tell intentional pins apart from drift, and so the
-# context for each pin (which issue motivated it) is visible at a glance.
-# Add an entry whenever you pin a grammar below npm latest.
-INTENTIONAL_PINS: dict[str, str] = {
-    "tree-sitter-c": (
-        "#1242 — last release built against the tree-sitter@0.21 ABI; "
-        "tree-sitter-c@0.23.x prebuilds segfault on Windows under tree-sitter@0.21.1"
-    ),
-    "tree-sitter-cpp": (
-        "#1242 — last 0.23.x release before tree-sitter-cpp added a runtime "
-        "dep on the broken-ABI tree-sitter-c@^0.23.1; pinning here removes "
-        "the need for a transitive override"
-    ),
-}
-
-
-# ── Helpers ─────────────────────────────────────────────────────────────
-
-def _load_package_json() -> dict:
-    return json.loads((GITNEXUS_DIR / "package.json").read_text())
-
-
-def read_current_runtime() -> str:
-    """Return the tree-sitter runtime version pinned in package.json (e.g. '0.21')."""
-    pkg = _load_package_json()
-    raw = pkg["dependencies"]["tree-sitter"]
-    match = re.search(r"(\d+)\.(\d+)", raw)
-    if not match:
-        raise SystemExit(f"could not parse tree-sitter version: {raw!r}")
-    return f"{match.group(1)}.{match.group(2)}"
-
-
-def read_pinned_grammar_versions() -> dict[str, str]:
-    """Return the grammar version range pinned in gitnexus/package.json.
-
-    Looks at both runtime and optional dependencies. Returns the raw range
-    string (e.g. '0.21.4', '^0.23.0', 'file:./vendor/...') so the report can
-    expose how flexible each pin is.
-    """
-    pkg = _load_package_json()
-    pinned: dict[str, str] = {}
-    for section in ("dependencies", "optionalDependencies"):
-        for name, spec in (pkg.get(section) or {}).items():
-            if name.startswith("tree-sitter-"):
-                pinned[name] = spec
-    return pinned
-
-
-def npm_view_json(pkg: str) -> dict | None:
-    """Fetch package metadata from the npm registry via HTTPS.
-
-    Uses the registry API directly so we don't depend on the npm CLI
-    being available (it's a batch file on Windows which complicates
-    subprocess calls).
-    """
-    url = f"https://registry.npmjs.org/{pkg}/latest"
-    try:
-        req = urllib.request.Request(url, headers={"Accept": "application/json"})
-        with urllib.request.urlopen(req, timeout=8) as resp:
-            return json.loads(resp.read().decode("utf-8"))
-    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError):
-        return None
-
-
-def satisfies_target(peer_range: str | None, target: str) -> bool:
-    """Check if a semver range like '^0.22.4' or '^0.25.0' satisfies the target.
-
-    Simple heuristic: extract the minimum version from the range and check
-    if target >= min. For caret ranges (^X.Y.Z), the upper bound is the
-    next major (for X>0) or next minor (for X==0). We check both bounds.
-    """
-    if peer_range is None:
-        # No peer dep declared = no constraint = compatible.
-        return True
-    match = re.search(r"(\d+)\.(\d+)\.(\d+)", peer_range)
-    if not match:
-        return False
-    min_major, min_minor, min_patch = int(match.group(1)), int(match.group(2)), int(match.group(3))
-
-    t_match = re.search(r"(\d+)\.(\d+)\.(\d+)", target)
-    if not t_match:
-        return False
-    t_major, t_minor, t_patch = int(t_match.group(1)), int(t_match.group(2)), int(t_match.group(3))
-
-    # Target must be >= minimum.
-    target_tuple = (t_major, t_minor, t_patch)
-    min_tuple = (min_major, min_minor, min_patch)
-    if target_tuple < min_tuple:
-        return False
-
-    # For caret ranges with major 0: ^0.X.Y allows [0.X.Y, 0.(X+1).0).
-    if peer_range.startswith("^") and min_major == 0:
-        if t_major != 0 or t_minor >= min_minor + 1:
-            return False
-    # For caret ranges with major >0: ^X.Y.Z allows [X.Y.Z, (X+1).0.0).
-    elif peer_range.startswith("^") and min_major > 0:
-        if t_major >= min_major + 1:
-            return False
-
-    return True
-
-
-_GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN")
-
-
-def fetch_text(url: str, timeout: int = 8) -> str | None:
-    """Fetch a URL and return its text, or None on failure.
-
-    Adds an Authorization header for github.com URLs when GITHUB_TOKEN is
-    set (raises the rate limit from 60 to 5 000 requests/hour).
-    """
-    headers: dict[str, str] = {}
-    # Parse the URL and check the hostname rather than substring-matching
-    # on the full URL string (CodeQL py/incomplete-url-substring-sanitization).
-    # `https://evil.com/?u=github.com` would have passed the substring check.
-    try:
-        parsed_host = urllib.parse.urlparse(url).hostname or ""
-    except ValueError:
-        parsed_host = ""
-    is_github_host = parsed_host == "github.com" or parsed_host.endswith(
-        (".github.com", ".githubusercontent.com")
-    ) or parsed_host == "githubusercontent.com"
-    if _GITHUB_TOKEN and is_github_host:
-        headers["Authorization"] = f"Bearer {_GITHUB_TOKEN}"
-    try:
-        req = urllib.request.Request(url, headers=headers)
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
-            return resp.read().decode("utf-8", errors="ignore")
-    except (urllib.error.URLError, urllib.error.HTTPError):
-        return None
-
-
-def extract_abi_from_text(text: str) -> int | None:
-    """Extract LANGUAGE_VERSION from parser.c text."""
-    match = re.search(r"#define\s+LANGUAGE_VERSION\s+(\d+)", text[:4096])
-    return int(match.group(1)) if match else None
-
-
-def extract_language_version(parser_c: pathlib.Path) -> int | None:
-    """Return the LANGUAGE_VERSION defined in a parser.c, or None if absent."""
-    if not parser_c.is_file():
-        return None
-    with parser_c.open("r", encoding="utf-8", errors="ignore") as fh:
-        head = fh.read(4096)
-    return extract_abi_from_text(head)
-
-
-def md_h(text: str, level: int = 2) -> str:
-    return f"{'#' * level} {text}\n"
-
-
-def _first_sentence(text: str) -> str:
-    """Return the leading sentence of a free-form rationale string.
-
-    Vendor package.json `_vendoredBy` fields often look like
-    "<reason>. <install-script breadcrumb>. Do NOT <warning>." — the
-    first sentence is what reviewers actually want to read; the rest is
-    noise in this context. Match a sentence-ending '.' followed by
-    whitespace; fall back to the whole string if nothing matches.
-    """
-    text = text.strip()
-    match = re.search(r"\.\s+[A-Z]", text)
-    return text[: match.start() + 1] if match else text
-
-
-def range_includes(spec: str | None, version: str) -> bool:
-    """Return True if pinned-range `spec` accepts the concrete `version`.
-
-    Handles the spec shapes we actually use in package.json:
-      - exact pins  ('0.21.4')
-      - caret / tilde ranges ('^0.23.0', '~0.23.5')
-      - non-registry pins ('file:./vendor/...', 'git+...') — always False,
-        because there's no meaningful "behind npm latest" comparison.
-    """
-    if not spec or spec == "—":
-        return False
-    if spec.startswith(("file:", "git", "http")):
-        return False
-    if spec.startswith(("^", "~")):
-        return satisfies_target(spec, version)
-    return spec.strip() == version.strip()
-
-
-def is_vendored_pin(spec: str | None) -> bool:
-    return bool(spec) and spec.startswith(("file:", "git", "http"))
-
-
-def vendored_drift_summary(
-    name: str, upstream_repo: str, upstream_branch: str, parser_path: str
-) -> dict:
-    """Inspect a vendored grammar under gitnexus/vendor/<name>.
-
-    Returns the vendored package.json's ``version`` and ``_vendoredBy``
-    fields (which carry the human rationale for vendoring), the vendored
-    parser's ABI, and a comparison against upstream main. We deliberately
-    rely on ``_vendoredBy`` rather than a parallel registry in this
-    script: the rationale belongs next to the vendored sources, not in
-    a daily-running CI script.
-    """
-    vendor_dir = GITNEXUS_DIR / "vendor" / name
-    pkg: dict = {}
-    pkg_path = vendor_dir / "package.json"
-    if pkg_path.is_file():
-        try:
-            pkg = json.loads(pkg_path.read_text(encoding="utf-8", errors="ignore"))
-        except json.JSONDecodeError:
-            pass
-
-    vendored_parser = vendor_dir / parser_path
-    if not vendored_parser.is_file():
-        vendored_parser = vendor_dir / "src" / "parser.c"
-    vendored_abi = extract_language_version(vendored_parser)
-
-    upstream_url = (
-        f"https://raw.githubusercontent.com/{upstream_repo}/"
-        f"{upstream_branch}/{parser_path}"
-    )
-    upstream_text = fetch_text(upstream_url)
-    upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
-
-    sha_text = fetch_text(
-        f"https://api.github.com/repos/{upstream_repo}/commits/{upstream_branch}"
-    )
-    upstream_sha = "?"
-    if sha_text:
-        try:
-            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
-        except json.JSONDecodeError:
-            pass
-
-    local_text = (
-        vendored_parser.read_text(encoding="utf-8", errors="ignore")
-        if vendored_parser.is_file()
-        else ""
-    )
-    in_sync = bool(
-        upstream_text
-        and local_text.replace("\r\n", "\n") == upstream_text.replace("\r\n", "\n")
-    )
-
-    return {
-        "name": name,
-        "vendored_version": pkg.get("version", "?"),
-        "vendored_by": pkg.get("_vendoredBy"),
-        "vendored_abi": vendored_abi,
-        "upstream_repo": upstream_repo,
-        "upstream_branch": upstream_branch,
-        "upstream_sha": upstream_sha,
-        "upstream_abi": upstream_abi,
-        "in_sync": in_sync,
-    }
-
-
-# ── Main ────────────────────────────────────────────────────────────────
-
-
-def _classify_grammar(
-    *,
-    name: str,
-    pinned_spec: str | None,
-    npm_version: str,
-    peer_range: str | None,
-    fetch_failed: bool,
-    target_compat: bool,
-    current_compat: bool,
-    upstream_progress: str | None,
-) -> dict:
-    """Decide a single primary disposition + a separate bump-now hint.
-
-    Buckets are mutually exclusive and ordered by what a reviewer should
-    look at first:
-      - fetch_failed   : npm registry fetch failed (treat as blocker, but
-                          surface separately so reviewers don't confuse it
-                          with an upstream block)
-      - intentional    : pinned in INTENTIONAL_PINS — explicit choice
-      - ready          : npm-latest peer dep already accepts the target
-                          runtime; nothing to do
-      - waiting        : main has a fix (ABI 15 or relaxed peer) but no
-                          published npm release yet
-      - blocked        : peer dep too tight on both npm and main
-
-    Independently of bucket, `bump_now` reports whether reviewers can
-    move the pin forward today without touching the runtime — we only
-    suggest it when npm-latest's peer dep also accepts our *current*
-    runtime, otherwise the bump would break `npm install`.
-    """
-    is_vendored = is_vendored_pin(pinned_spec)
-    behind_latest = (
-        not is_vendored
-        and npm_version != "?"
-        and not range_includes(pinned_spec, npm_version)
-    )
-    # Intentional pins must never appear as actionable bumps — by definition
-    # we're holding them back on purpose. The pin can only be lifted by
-    # editing INTENTIONAL_PINS and package.json together.
-    bump_now = behind_latest and current_compat and name not in INTENTIONAL_PINS
-
-    if fetch_failed:
-        bucket = "fetch_failed"
-    elif name in INTENTIONAL_PINS:
-        bucket = "intentional"
-    elif target_compat:
-        bucket = "ready"
-    elif upstream_progress:
-        bucket = "waiting"
-    else:
-        bucket = "blocked"
-
-    return {
-        "name": name,
-        "pinned_spec": pinned_spec or "—",
-        "npm_version": npm_version,
-        "peer_range": peer_range,
-        "target_compat": target_compat,
-        "current_compat": current_compat,
-        "upstream_progress": upstream_progress,
-        "behind_latest": behind_latest,
-        "bump_now": bump_now,
-        "bucket": bucket,
-        "is_vendored": is_vendored,
-    }
-
-
-def main() -> int:
-    blockers: dict[str, str] = {}
-    lines: list[str] = []
-    lines.append(md_h("Tree-sitter 0.25 upgrade readiness", 1))
-    lines.append("")
-
-    current_runtime = read_current_runtime()
-    current_abi_range = RUNTIME_ABI_RANGES.get(current_runtime, (0, 0))
-    target_abi_range = RUNTIME_ABI_RANGES.get(TARGET_RUNTIME_MAJOR_MINOR, (0, 0))
-    pinned_versions = read_pinned_grammar_versions()
-
-    lines.append(
-        f"`tree-sitter@{current_runtime}.x` (ABI {current_abi_range[0]}–{current_abi_range[1]}) "
-        f"→ target `tree-sitter@{TARGET_RUNTIME}` "
-        f"(ABI {target_abi_range[0]}–{target_abi_range[1]})."
-    )
-    lines.append("")
-
-    # First pass: gather raw data + classification per grammar. We render
-    # the human-friendly buckets first, then the raw matrix in a <details>
-    # block at the end. Status text in the matrix is preserved verbatim
-    # so the workflow's row-diff change-detection keeps working.
-    grammar_rows: list[dict] = []
-    raw_matrix: list[str] = [
-        "| Grammar | Pinned | npm latest | Peer dep | Satisfies 0.25? | ABI | Upstream ABI | Status |",
-        "|---|---|---|---|---|---|---|---|",
-    ]
-
-    vendored_grammars: list[dict] = []
-
-    for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
-        pinned_spec = pinned_versions.get(name, "—")
-
-        # Vendored grammars don't have an "npm latest" we install from —
-        # we ship our own copy under gitnexus/vendor/<name>. Treat them
-        # as a separate kind of artefact: their readiness for the runtime
-        # upgrade depends on the vendored ABI being in the target range,
-        # not on a peer-dep negotiation.
-        if is_vendored_pin(pinned_spec):
-            v = vendored_drift_summary(name, upstream_repo, upstream_branch, parser_path)
-            v["pinned_spec"] = pinned_spec
-            # Three-state classification: in-range, out-of-range, or
-            # not-introspectable (e.g. tree-sitter-swift ships only
-            # prebuilt .node binaries, no parser.c — assume compatible).
-            if v["vendored_abi"] is None:
-                v["target_compat"] = True
-                v["abi_state"] = "prebuilt"
-                status = "Vendored (prebuilt — ABI not introspectable)"
-            elif target_abi_range[0] <= v["vendored_abi"] <= target_abi_range[1]:
-                v["target_compat"] = True
-                v["abi_state"] = "in_range"
-                status = "Vendored (ABI in target range)"
-            else:
-                v["target_compat"] = False
-                v["abi_state"] = "out_of_range"
-                status = "Vendored (ABI out of range)"
-                blockers[name] = (
-                    f"vendored `{name}`: ABI {v['vendored_abi']} outside target range "
-                    f"{target_abi_range[0]}..{target_abi_range[1]}"
-                )
-            # Keep vendored grammars in the raw matrix so the workflow's
-            # row-diff change-detection picks up status transitions on
-            # them too. npm-only columns get sentinels.
-            raw_matrix.append(
-                f"| `{name}` | {pinned_spec} | (vendored) | (vendored) | "
-                f"{'Yes' if v['target_compat'] else '**No**'} | "
-                f"{v['vendored_abi'] or '?'} | {v['upstream_abi'] or '?'} | {status} |"
-            )
-            vendored_grammars.append(v)
-            continue
-
-        # Fetch latest npm metadata.
-        info = npm_view_json(name)
-        fetch_failed = info is None
-        npm_version = "?"
-        peer_range = None
-        peer_optional = True
-        if info:
-            npm_version = info.get("version", "?")
-            peers = info.get("peerDependencies") or {}
-            peer_range = peers.get("tree-sitter")
-            meta = info.get("peerDependenciesMeta") or {}
-            ts_meta = meta.get("tree-sitter") or {}
-            peer_optional = ts_meta.get("optional", False) if peer_range else True
-
-        if fetch_failed:
-            peer_display = "? (fetch failed)"
-            target_compat = False
-            current_compat = False
-        else:
-            peer_display = peer_range or "none"
-            if peer_range and not peer_optional:
-                peer_display += " (required)"
-            target_compat = satisfies_target(peer_range, TARGET_RUNTIME)
-            current_compat = satisfies_target(peer_range, f"{current_runtime}.0")
-
-        # Check installed ABI using the same parser_path from GRAMMARS.
-        installed_parser = GITNEXUS_DIR / "node_modules" / name / parser_path
-        if not installed_parser.is_file():
-            # Fallback to default location.
-            installed_parser = GITNEXUS_DIR / "node_modules" / name / "src" / "parser.c"
-        installed_abi = extract_language_version(installed_parser)
-        abi_display = str(installed_abi) if installed_abi else "?"
-
-        # Check upstream (main/master branch) ABI for unreleased work.
-        upstream_url = (
-            f"https://raw.githubusercontent.com/{upstream_repo}/"
-            f"{upstream_branch}/{parser_path}"
-        )
-        upstream_text = fetch_text(upstream_url)
-        upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
-        upstream_abi_display = str(upstream_abi) if upstream_abi else "?"
-
-        # Status text + upstream-progress detection. The Status column
-        # values are preserved as-is to keep the workflow's row-diff
-        # change-detection working on the raw matrix below.
-        upstream_progress: str | None = None
-        if fetch_failed:
-            status = "Unknown (fetch failed)"
-            blockers[name] = f"`{name}`: npm registry fetch failed — could not verify peer dep"
-        elif name in INTENTIONAL_PINS:
-            # An intentional pin is, by definition, a held-back grammar:
-            # whatever npm-latest's peer dep says, our shipped version is
-            # the one whose ABI/peer must accept the target runtime, and
-            # the pin entry exists precisely because it does not. Treat
-            # it as a blocker until the pin is lifted (entry removed from
-            # INTENTIONAL_PINS), at which point this grammar falls back
-            # to standard classification on the next run.
-            status = "Intentionally pinned"
-            blockers[name] = (
-                f"`{name}` intentionally pinned at `{pinned_spec}` "
-                f"({INTENTIONAL_PINS[name]}) — pin must be lifted "
-                f"before the {TARGET_RUNTIME} runtime upgrade"
-            )
-        elif target_compat:
-            status = "Ready"
-        elif upstream_abi and upstream_abi >= 15:
-            status = "Unreleased (ABI 15 on main)"
-            upstream_progress = f"ABI 15 on `{upstream_repo}@{upstream_branch}` not yet published"
-            blockers[name] = f"`{name}`: ABI 15 on `{upstream_repo}` main but not published to npm"
-        else:
-            status = "Blocking"
-            blockers[name] = f"`{name}@{npm_version}`: peer `{peer_display}` incompatible with 0.25"
-
-        # Also check upstream package.json for relaxed peer dep — beats
-        # the ABI-15 hint when both are true.
-        if not target_compat and not fetch_failed:
-            upstream_pkg_url = (
-                f"https://raw.githubusercontent.com/{upstream_repo}/"
-                f"{upstream_branch}/package.json"
-            )
-            upstream_pkg_text = fetch_text(upstream_pkg_url)
-            if upstream_pkg_text:
-                try:
-                    upstream_pkg = json.loads(upstream_pkg_text)
-                    upstream_peer = (upstream_pkg.get("peerDependencies") or {}).get("tree-sitter")
-                    if upstream_peer and satisfies_target(upstream_peer, TARGET_RUNTIME):
-                        status = "Unreleased (peer relaxed on main)"
-                        upstream_progress = (
-                            f"peer relaxed to `{upstream_peer}` on "
-                            f"`{upstream_repo}@{upstream_branch}` not yet published"
-                        )
-                        blockers[name] = f"`{name}`: peer dep relaxed on `{upstream_repo}` main but not published to npm"
-                except json.JSONDecodeError:
-                    pass
-
-        pinned_spec = pinned_versions.get(name, "—")
-        compat_icon = "Yes" if target_compat else "**No**"
-        raw_matrix.append(
-            f"| `{name}` | {pinned_spec} | {npm_version} | {peer_display} | "
-            f"{compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
-        )
-
-        grammar_rows.append(_classify_grammar(
-            name=name,
-            pinned_spec=pinned_spec,
-            npm_version=npm_version,
-            peer_range=peer_range,
-            fetch_failed=fetch_failed,
-            target_compat=target_compat,
-            current_compat=current_compat,
-            upstream_progress=upstream_progress,
-        ))
-
-    # ── Bucketize ────────────────────────────────────────────────────
-    by_bucket: dict[str, list[dict]] = {
-        k: [] for k in ("ready", "intentional", "waiting", "blocked", "fetch_failed")
-    }
-    for row in grammar_rows:
-        by_bucket[row["bucket"]].append(row)
-    bump_now = [r for r in grammar_rows if r["bump_now"]]
-    ready_count = len(by_bucket["ready"])
-
-    # ── TL;DR ────────────────────────────────────────────────────────
-    npm_count = len(grammar_rows)
-    vendored_count = len(vendored_grammars)
-    vendored_ready = sum(1 for v in vendored_grammars if v["target_compat"])
-
-    if not blockers:
-        verdict = "**Ready** — all grammars are 0.25-compatible. The runtime upgrade can proceed."
-    else:
-        moved = "no" if not by_bucket["waiting"] else f"yes — {len(by_bucket['waiting'])} grammars have unreleased fixes on main"
-        verdict = (
-            f"**Blocked** — {len(blockers)} grammars are not yet 0.25-compatible. "
-            f"Upstream movement: {moved}."
-        )
-
-    lines.append(md_h("TL;DR", 2))
-    lines.append(verdict)
-    lines.append("")
-    lines.append(f"- {ready_count}/{npm_count} npm-installed grammars already accept tree-sitter@{TARGET_RUNTIME}")
-    if vendored_count:
-        lines.append(
-            f"- {vendored_ready}/{vendored_count} vendored grammars at an ABI within the target runtime range"
-        )
-    lines.append(f"- {len(by_bucket['intentional'])} intentionally pinned (see below)")
-    lines.append(f"- {len(by_bucket['waiting'])} waiting on an upstream npm release")
-    lines.append(f"- {len(by_bucket['blocked'])} blocked on upstream (no fix even on main)")
-    if by_bucket['fetch_failed']:
-        lines.append(f"- {len(by_bucket['fetch_failed'])} could not be checked (npm registry unreachable)")
-    if bump_now:
-        lines.append(
-            f"- **{len(bump_now)} bump candidate(s) you can take TODAY** (npm-latest "
-            f"is newer than the pin AND its peer dep accepts our current runtime)"
-        )
-    lines.append("")
-
-    # ── What you can do today ───────────────────────────────────────
-    if bump_now:
-        lines.append(md_h("What you can do today", 2))
-        lines.append(
-            "These pins lag npm latest and the latest version's peer dep already "
-            "accepts our current `tree-sitter@" + current_runtime + ".x` runtime. "
-            "Bumping is independent of the 0.25 upgrade and should be a quick PR."
-        )
-        lines.append("")
-        for r in sorted(bump_now, key=lambda r: r["name"]):
-            lines.append(
-                f"- `{r['name']}`: `{r['pinned_spec']}` → `{r['npm_version']}` "
-                f"(peer `{r['peer_range'] or 'none'}`)"
-            )
-        lines.append("")
-
-    # ── Per-disposition sections ────────────────────────────────────
-    def _emit_bucket(title: str, body_intro: str, rows: list[dict], render) -> None:
-        if not rows:
-            return
-        lines.append(md_h(f"{title} ({len(rows)})", 3))
-        lines.append(body_intro)
-        lines.append("")
-        for r in sorted(rows, key=lambda r: r["name"]):
-            lines.append(render(r))
-        lines.append("")
-
-    lines.append(md_h("Disposition", 2))
-
-    _emit_bucket(
-        "Ready for 0.25",
-        "These grammars' npm-latest peer dep already accepts the target runtime. No action needed for the upgrade.",
-        by_bucket["ready"],
-        lambda r: (
-            f"- `{r['name']}` — pinned `{r['pinned_spec']}`, npm latest `{r['npm_version']}`"
-            + ("  _(also a bump candidate — see above)_" if r["bump_now"] else "")
-        ),
-    )
-
-    if by_bucket["intentional"]:
-        lines.append(md_h(f"Intentionally pinned ({len(by_bucket['intentional'])})", 3))
-        lines.append(
-            "Deliberately held below npm latest. These are **not** drift — each entry "
-            "lists the issue motivating the pin and the condition for unpinning."
-        )
-        lines.append("")
-        for r in sorted(by_bucket["intentional"], key=lambda r: r["name"]):
-            reason = INTENTIONAL_PINS.get(r["name"], "(no rationale recorded)")
-            lines.append(
-                f"- `{r['name']}` pinned at `{r['pinned_spec']}` "
-                f"(npm latest `{r['npm_version']}`)\n  {reason}"
-            )
-        lines.append("")
-
-    _emit_bucket(
-        "Waiting on upstream npm release",
-        "Fixes are merged on the upstream main branch but not yet published to npm. "
-        "We can move forward as soon as upstream cuts a release.",
-        by_bucket["waiting"],
-        lambda r: (
-            f"- `{r['name']}@{r['npm_version']}` — peer `{r['peer_range'] or 'none'}`. "
-            f"_{r['upstream_progress']}_"
-        ),
-    )
-
-    _emit_bucket(
-        "Blocked on upstream",
-        "Peer dep is too tight on both the latest npm release and on upstream main. "
-        "These need an upstream issue/PR before we can proceed.",
-        by_bucket["blocked"],
-        lambda r: (
-            f"- `{r['name']}@{r['npm_version']}` — peer `{r['peer_range'] or 'none'}`"
-            + (" _(vendored)_" if r["is_vendored"] else "")
-        ),
-    )
-
-    _emit_bucket(
-        "Could not check",
-        "npm registry fetch failed for these grammars. Re-run the workflow to retry.",
-        by_bucket["fetch_failed"],
-        lambda r: f"- `{r['name']}` (pinned `{r['pinned_spec']}`)",
-    )
-
-    # ── Vendored parsers ────────────────────────────────────────────
-    if vendored_grammars:
-        lines.append(md_h(f"Vendored parsers ({len(vendored_grammars)})", 2))
-        lines.append(
-            "These grammars ship from `gitnexus/vendor/` rather than the npm "
-            "registry. Their compatibility is governed by the **vendored "
-            "ABI** (must lie in the target runtime's range), not by a peer-"
-            "dep negotiation. The rationale for each vendored copy lives in "
-            "its own `package.json` `_vendoredBy` field."
-        )
-        lines.append("")
-        for v in sorted(vendored_grammars, key=lambda v: v["name"]):
-            sync_label = (
-                "in sync with upstream" if v["in_sync"] else "diverged from upstream"
-            )
-            if v["abi_state"] == "in_range":
-                abi_label = f"ABI `{v['vendored_abi']}` (in target range)"
-            elif v["abi_state"] == "prebuilt":
-                abi_label = "ABI `prebuilt` (binary-only vendor, source not introspectable)"
-            else:
-                abi_label = (
-                    f"ABI `{v['vendored_abi']}` (**outside** target range "
-                    f"{target_abi_range[0]}..{target_abi_range[1]})"
-                )
-            upstream_abi_str = (
-                f"ABI `{v['upstream_abi']}`" if v["upstream_abi"] else "ABI `?`"
-            )
-            lines.append(
-                f"- **`{v['name']}`** `{v['vendored_version']}` — {abi_label}, "
-                f"upstream `{v['upstream_repo']}@{v['upstream_sha']}` "
-                f"{upstream_abi_str} · {sync_label}"
-            )
-            if v["vendored_by"]:
-                # Show the first sentence — vendor package.json fields tend
-                # to start with the rationale and tail off into install-
-                # script breadcrumbs that aren't useful in this report.
-                rationale = _first_sentence(v["vendored_by"])
-                lines.append(f"  - **Why vendored:** {rationale}")
-            # Action computation: needs regen iff upstream ABI exceeds
-            # vendored AND is still within target range. If upstream ABI
-            # exceeds the target, that's a runtime-side blocker. For
-            # prebuilt-only vendors we can't drive this from source ABI;
-            # the action is a manual upstream-binary refresh, surfaced
-            # via the in-sync flag instead.
-            if v["abi_state"] == "prebuilt":
-                if not v["in_sync"]:
-                    lines.append(
-                        "  - **Action:** check whether upstream has shipped a new "
-                        "prebuilt release; this vendor ships binary-only artefacts."
-                    )
-            elif v["upstream_abi"] and v["vendored_abi"] and v["upstream_abi"] > v["vendored_abi"]:
-                if v["upstream_abi"] <= target_abi_range[1]:
-                    lines.append(
-                        f"  - **Action:** after upgrading to tree-sitter@{TARGET_RUNTIME}, "
-                        f"regenerate `parser.c` from upstream `{v['upstream_sha']}`."
-                    )
-                else:
-                    lines.append(
-                        f"  - **Action:** wait for a runtime supporting ABI "
-                        f"{v['upstream_abi']}; current target ({TARGET_RUNTIME}) only "
-                        f"goes up to ABI {target_abi_range[1]}."
-                    )
-                    blockers[f"vendored-{v['name']}-abi"] = (
-                        f"vendored {v['name']}: upstream ABI {v['upstream_abi']} outside target range"
-                    )
-            elif not v["in_sync"]:
-                lines.append(
-                    "  - **Action:** review upstream changes; vendored copy may "
-                    "need a refresh (no ABI bump required)."
-                )
-        lines.append("")
-
-    # ── Raw matrix (for completeness + workflow row-diff) ────────────
-    lines.append(md_h("Full grammar matrix", 2))
-    lines.append(
-        "<details><summary>Click to expand the raw per-grammar table "
-        "(used by the workflow's change-detection bot).</summary>\n"
-    )
-    lines.extend(raw_matrix)
-    lines.append("\n</details>")
-    lines.append("")
-
-    print("\n".join(lines))
-    return 1 if blockers else 0
-
-
-if __name__ == "__main__":
-    # Force UTF-8 output: the report contains em-dashes and arrows that
-    # Windows' default cp1252 codepage can't encode, while Linux runners
-    # default to UTF-8 anyway.
-    try:
-        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
-    except Exception:
-        pass
-    sys.exit(main())

.github/scripts/check-workflow-concurrency.py

@@ -1,179 +0,0 @@
-#!/usr/bin/env python3
-"""Enforce the GitHub Actions concurrency convention.
-
-See CONTRIBUTING.md -> "GitHub Actions — Concurrency Convention" for the rules.
-
-Invoked from .github/workflows/ci-quality.yml. Runs locally too:
-    python3 .github/scripts/check-workflow-concurrency.py .github/workflows
-
-Rules:
-  1. Every entry-point (non-reusable) workflow declares a top-level
-     `concurrency:` block.
-  2. Reusable workflows (on: workflow_call ONLY) do NOT declare one.
-  3. The `concurrency.group` expression MUST reference either
-     `${{ github.workflow }}` or one of the approved hardcoded literal prefixes
-     for workflows that are simultaneously entry-points AND reusable (on: push/
-     workflow_call). Two such exceptions are currently approved:
-       - `CI-` for ci.yml (the original canonical form)
-       - `docker-build-push-` for docker.yml
-     This is checked by substring containment rather than prefix match because
-     the group value is a conditional expression that resolves to a `CI-…` or
-     `docker-build-push-…` literal at runtime.
-
-We deliberately do not use a YAML library — keeps the script dependency-free
-on any vanilla runner. `on:` block parsing is line-based and handles both the
-flat (`on: workflow_call`) and mapping (`on:\n  workflow_call:`) forms.
-"""
-
-from __future__ import annotations
-
-import pathlib
-import re
-import sys
-
-
-REQUIRED_TOKENS = ("${{ github.workflow }}", "CI-", "docker-build-push-")
-
-
-def is_reusable(lines: list[str]) -> bool:
-    """Return True iff the workflow's `on:` block names only `workflow_call`."""
-    in_on = False
-    on_indent: int | None = None
-    keys: list[str] = []
-
-    for raw in lines:
-        # Skip blank lines and comments
-        stripped = raw.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-
-        indent = len(raw) - len(raw.lstrip(" "))
-
-        if not in_on:
-            if raw.startswith("on:"):
-                remainder = raw[len("on:"):].strip()
-                if not remainder:
-                    # `on:` followed by indented mapping on next lines
-                    in_on = True
-                    on_indent = indent
-                    continue
-                if remainder.startswith("[") and remainder.endswith("]"):
-                    # Flow-style list: on: [workflow_call]
-                    items = [
-                        item.strip() for item in remainder.strip("[]").split(",")
-                    ]
-                    return items == ["workflow_call"]
-                # Scalar form: on: workflow_call  (or a single other event)
-                return remainder == "workflow_call"
-            continue
-
-        # Inside the `on:` block; stop when indentation returns to <= on_indent
-        if on_indent is not None and indent <= on_indent:
-            break
-
-        # Only consider keys at on_indent + indentation step (anything deeper
-        # is nested config like `types:`)
-        if ":" not in stripped:
-            continue
-        # Heuristic: first-level event keys are those with indent == on_indent + 2
-        # (the canonical step for a 2-space YAML doc). We collect all first-level
-        # keys by tracking the smallest indent seen inside the block.
-        keys.append((indent, stripped.split(":", 1)[0].strip()))
-
-    if not keys:
-        return False
-
-    # Take only the outermost-indented keys as the event list
-    min_indent = min(i for i, _ in keys)
-    events = [name for i, name in keys if i == min_indent]
-    return events == ["workflow_call"]
-
-
-CONCURRENCY_RE = re.compile(r"^concurrency:\s*$")
-GROUP_RE = re.compile(r"^\s+group:\s*(.+?)\s*$")
-
-
-def extract_group_key(lines: list[str]) -> str | None:
-    """Return the `group:` value of the top-level `concurrency:` block, or None."""
-    for idx, raw in enumerate(lines):
-        if CONCURRENCY_RE.match(raw):
-            # Scan forward until we leave the concurrency block (next top-level key
-            # is at column 0 and ends with `:`).
-            for follow in lines[idx + 1:]:
-                if follow and not follow.startswith(" ") and follow.rstrip().endswith(":"):
-                    break
-                m = GROUP_RE.match(follow)
-                if m:
-                    return m.group(1).strip().strip("'").strip('"')
-            break
-    return None
-
-
-def has_top_level_concurrency(lines: list[str]) -> bool:
-    return any(CONCURRENCY_RE.match(raw) for raw in lines)
-
-
-def check(workflows_dir: pathlib.Path) -> int:
-    fail = 0
-    files = sorted(
-        list(workflows_dir.glob("*.yml")) + list(workflows_dir.glob("*.yaml"))
-    )
-    for path in files:
-        lines = path.read_text(encoding="utf-8").splitlines()
-        reusable = is_reusable(lines)
-        has_conc = has_top_level_concurrency(lines)
-
-        if reusable:
-            if has_conc:
-                print(
-                    f"::error file={path}::Reusable workflow (on: workflow_call) "
-                    "must NOT declare its own concurrency block — it inherits "
-                    "from the caller. See CONTRIBUTING.md -> GitHub Actions — "
-                    "Concurrency Convention."
-                )
-                fail = 1
-            continue
-
-        if not has_conc:
-            print(
-                f"::error file={path}::Missing top-level concurrency block. "
-                "See CONTRIBUTING.md -> GitHub Actions — Concurrency Convention."
-            )
-            fail = 1
-            continue
-
-        group = extract_group_key(lines)
-        if group is None:
-            print(
-                f"::error file={path}::concurrency block is missing a "
-                "`group:` key."
-            )
-            fail = 1
-            continue
-
-        if not any(token in group for token in REQUIRED_TOKENS):
-            print(
-                f"::error file={path}::concurrency.group `{group}` must "
-                f"reference one of {REQUIRED_TOKENS} (use ${{{{ github.workflow }}}} "
-                "for normal entry-point workflows; use an approved literal prefix "
-                "only for workflows that are both entry-points AND reusable — "
-                "see CONTRIBUTING.md -> GitHub Actions — Concurrency Convention)."
-            )
-            fail = 1
-
-    return fail
-
-
-def main(argv: list[str]) -> int:
-    if len(argv) != 2:
-        print(f"usage: {argv[0]} <workflows-dir>", file=sys.stderr)
-        return 2
-    workflows_dir = pathlib.Path(argv[1])
-    if not workflows_dir.is_dir():
-        print(f"not a directory: {workflows_dir}", file=sys.stderr)
-        return 2
-    return check(workflows_dir)
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv))

.github/workflows/ci-e2e.yml

@@ -3,9 +3,6 @@ name: E2E Tests
 on:
   workflow_call:
 
-permissions:
-  contents: read
-
 jobs:
   check-changes:
     name: Check web module changes
@@ -14,8 +11,8 @@ jobs:
     outputs:
       web_changed: ${{ steps.filter.outputs.web }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v3
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3
         id: filter
         with:
           filters: |
@@ -29,10 +26,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Configure e2e GitNexus home
-        run: echo "GITNEXUS_HOME=${RUNNER_TEMP}/gitnexus-home" >> "$GITHUB_ENV"
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - uses: ./.github/actions/setup-gitnexus-web
 
@@ -50,14 +44,9 @@ jobs:
 
       - name: Analyze repository (index for backend)
         run: |
-          E2E_REPO="${RUNNER_TEMP}/gitnexus-e2e-repo"
-          rm -rf "${E2E_REPO}"
-          mkdir -p "${E2E_REPO}"
-          cp -R gitnexus/test/fixtures/mini-repo/src "${E2E_REPO}/src"
-          printf '%s\n' '{"name":"e2e-mini-repo","version":"0.0.0","private":true}' > "${E2E_REPO}/package.json"
-          node gitnexus/dist/cli/index.js analyze "${E2E_REPO}" --skip-git --skip-agents-md --name e2e-mini-repo
-          if [ ! -d "${E2E_REPO}/.gitnexus" ]; then
-            echo "::error::No fixture .gitnexus index created"
+          node gitnexus/dist/cli/index.js analyze || true
+          if [ ! -d ".gitnexus" ]; then
+            echo "::error::No .gitnexus index created"
             exit 1
           fi
 
@@ -85,7 +74,7 @@ jobs:
 
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: e2e-results
           path: |

.github/workflows/ci-quality.yml

@@ -3,18 +3,15 @@ name: Quality Checks
 on:
   workflow_call:
 
-permissions:
-  contents: read
-
 jobs:
   format:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: 22
+          node-version: 20
           cache: npm
           cache-dependency-path: package-lock.json
       - run: npm ci
@@ -24,10 +21,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: 22
+          node-version: 20
           cache: npm
           cache-dependency-path: package-lock.json
       - run: npm ci
@@ -37,7 +34,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - uses: ./.github/actions/setup-gitnexus
       - run: npx tsc --noEmit
         working-directory: gitnexus
@@ -46,30 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - uses: ./.github/actions/setup-gitnexus-web
       - run: npx tsc -b --noEmit
         working-directory: gitnexus-web
-
-  # Enforces the convention documented in CONTRIBUTING.md → "GitHub Actions —
-  # Concurrency Convention":
-  #   1. Every entry-point (non-reusable) workflow declares a top-level
-  #      `concurrency:` block.
-  #   2. Reusable workflows (`on: workflow_call` only) do NOT declare one —
-  #      they inherit concurrency from the caller.
-  #   3. The concurrency group key starts with `${{ github.workflow }}` or
-  #      the literal `CI-` prefix (the documented ci.yml exception for
-  #      reusable-workflow-safe grouping).
-  # Reusability is detected by parsing each workflow's `on:` block, not an
-  # allowlist, so new reusable workflows never produce false positives.
-  workflow-convention:
-    name: Workflow concurrency convention
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Validate workflow concurrency convention
-        shell: bash
-        run: |
-          set -euo pipefail
-          python3 .github/scripts/check-workflow-concurrency.py .github/workflows

.github/workflows/ci-report.yml

@@ -14,16 +14,6 @@ permissions:
   contents: read # needed for sparse checkout of vitest.config.ts
   pull-requests: write # needed to post sticky PR comment
 
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Serialize sticky-comment writes per PR so two rapid CI completions don't race.
-# Internal PRs surface in `pull_requests[0].number`. Fork PRs leave that array empty,
-# so we fall back to `<head-repo-full-name>/<head-branch>`, which is stable across
-# reruns and subsequent pushes for the same fork PR (unlike `workflow_run.id` which
-# is unique per run and therefore does not serialize anything).
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.workflow_run.pull_requests[0].number || format('{0}/{1}', github.event.workflow_run.head_repository.full_name, github.event.workflow_run.head_branch) }}
-  cancel-in-progress: false
-
 jobs:
   pr-report:
     name: PR Report
@@ -36,7 +26,7 @@ jobs:
     steps:
       # ── Download artifacts from the CI run ────────────────────────
       - name: Download artifacts
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
         with:
           script: |
             const fs = require('fs');
@@ -95,37 +85,35 @@ jobs:
 
           # Validate PR number is a positive integer (artifact comes from
           # untrusted fork code, so treat contents defensively).
-          PR_NUM=$(tr -d '[:space:]' < "$DIR/pr_number")
+          PR_NUM=$(cat "$DIR/pr_number" | tr -d '[:space:]')
           if ! [[ "$PR_NUM" =~ ^[0-9]+$ ]]; then
             echo "skip=true" >> "$GITHUB_OUTPUT"
             echo "::error::Invalid PR number in artifact: '$PR_NUM'"
             exit 0
           fi
 
+          echo "skip=false"              >> "$GITHUB_OUTPUT"
+          echo "pr_number=$PR_NUM"       >> "$GITHUB_OUTPUT"
           # Validate job-result strings against known GitHub Actions values.
           # Artifact contents come from the PR workflow (potentially untrusted
           # fork code), so we whitelist to prevent newline injection into
           # GITHUB_OUTPUT.
           validate_result() {
             local val
-            val=$(tr -d '[:space:]' < "$1")
+            val=$(cat "$1" | tr -d '[:space:]')
             case "$val" in
               success|failure|cancelled|skipped) echo "$val" ;;
               *) echo "unknown" ;;
             esac
           }
 
-          {
-            echo "skip=false"
-            echo "pr_number=$PR_NUM"
-            echo "quality=$(validate_result "$DIR/quality_result")"
-            echo "tests=$(validate_result "$DIR/tests_result")"
-            echo "e2e=$(validate_result "$DIR/e2e_result")"
-          } >> "$GITHUB_OUTPUT"
+          echo "quality=$(validate_result "$DIR/quality_result")"        >> "$GITHUB_OUTPUT"
+          echo "tests=$(validate_result "$DIR/tests_result")"            >> "$GITHUB_OUTPUT"
+          echo "e2e=$(validate_result "$DIR/e2e_result")"                >> "$GITHUB_OUTPUT"
 
       - name: Checkout (for vitest config)
         if: steps.meta.outputs.skip != 'true'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           sparse-checkout: gitnexus/vitest.config.ts
           sparse-checkout-cone-mode: false
@@ -134,21 +122,20 @@ jobs:
       - name: Fetch base branch coverage
         if: steps.meta.outputs.skip != 'true'
         id: base-coverage
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
         with:
           script: |
             const fs = require('fs');
             const path = require('path');
 
-            // Find recent successful CI runs on main (check several in case
-            // the most recent artifact has expired).
+            // Find the latest successful CI run on main
             const runs = await github.rest.actions.listWorkflowRuns({
               owner: context.repo.owner,
               repo: context.repo.repo,
               workflow_id: 'ci.yml',
               branch: 'main',
               status: 'success',
-              per_page: 5,
+              per_page: 1,
             });
 
             if (runs.data.workflow_runs.length === 0) {
@@ -157,47 +144,32 @@ jobs:
               return;
             }
 
-            // Try each run until we find a downloadable test-reports artifact
-            for (const run of runs.data.workflow_runs) {
-              const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                run_id: run.id,
-              });
+            const mainRunId = runs.data.workflow_runs[0].id;
+            const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: mainRunId,
+            });
 
-              const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
-              if (!testReports) {
-                core.info(`Run ${run.id}: no test-reports artifact, trying next`);
-                continue;
-              }
-
-              try {
-                const zip = await github.rest.actions.downloadArtifact({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  artifact_id: testReports.id,
-                  archive_format: 'zip',
-                });
-
-                const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
-                fs.mkdirSync(dest, { recursive: true });
-                fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
-                core.setOutput('found', 'true');
-                core.setOutput('dir', dest);
-                return;
-              } catch (err) {
-                // 410 Gone means the artifact expired; try the next run
-                if (err.status === 410 || err.response?.status === 410) {
-                  core.info(`Run ${run.id}: artifact expired, trying next`);
-                  continue;
-                }
-                throw err;
-              }
+            const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
+            if (!testReports) {
+              core.setOutput('found', 'false');
+              core.info('No test-reports artifact on main branch');
+              return;
             }
 
-            // All attempts exhausted — no usable base coverage
-            core.setOutput('found', 'false');
-            core.info('No downloadable test-reports artifact found on main (all expired or missing)');
+            const zip = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: testReports.id,
+              archive_format: 'zip',
+            });
+
+            const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
+            fs.mkdirSync(dest, { recursive: true });
+            fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
+            core.setOutput('found', 'true');
+            core.setOutput('dir', dest);
 
       - name: Extract base coverage
         if: steps.meta.outputs.skip != 'true' && steps.base-coverage.outputs.found == 'true'
@@ -252,7 +224,7 @@ jobs:
               printf -v "${prefix}_BRANCH_COV" '%s' ""
               printf -v "${prefix}_FUNCS_COV" '%s' ""
               printf -v "${prefix}_LINES_COV" '%s' ""
-              return 0
+              return 1
             fi
           }
 
@@ -281,17 +253,14 @@ jobs:
             fi
           }
 
-          # `_` placeholder for the suite-count column — positional
-          # readability for sum_results' 6-field output, but the value
-          # isn't surfaced in the report (suites are tracked per-test
-          # framework, not as a top-line metric).
-          read -r CLI_T CLI_P CLI_F CLI_S _ CLI_D <<< "$(sum_results "$RESULTS_FILE")"
-          read -r WEB_T WEB_P WEB_F WEB_S _ WEB_D <<< "$(sum_results "$WEB_RESULTS_FILE")"
+          read CLI_T CLI_P CLI_F CLI_S CLI_SU CLI_D <<< "$(sum_results "$RESULTS_FILE")"
+          read WEB_T WEB_P WEB_F WEB_S WEB_SU WEB_D <<< "$(sum_results "$WEB_RESULTS_FILE")"
 
           TOTAL=$((CLI_T + WEB_T))
           PASSED=$((CLI_P + WEB_P))
           FAILED=$((CLI_F + WEB_F))
           SKIPPED=$((CLI_S + WEB_S))
+          SUITES=$((CLI_SU + WEB_SU))
           DURATION=$((CLI_D > WEB_D ? CLI_D : WEB_D))
 
           # ── Status helpers ──
@@ -437,7 +406,7 @@ jobs:
 
       - name: Comment on PR
         if: steps.meta.outputs.skip != 'true'
-        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
         with:
           header: ci-report
           number: ${{ steps.meta.outputs.pr_number }}

.github/workflows/ci-scope-parity.yml

@@ -1,113 +0,0 @@
-name: Scope Resolution Parity
-
-# Reusable workflow — called from ci.yml. Does NOT declare concurrency;
-# it inherits the caller's concurrency group per the convention documented
-# in CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-#
-# ── Purpose (RFC #909 Ring 3, §6.4 "Observability gates") ──────────────
-# For every language in `MIGRATED_LANGUAGES` (exported from
-# `gitnexus/src/core/ingestion/registry-primary-flag.ts`), run the
-# resolver integration test at `test/integration/resolvers/<slug>.test.ts`
-# TWICE on every PR:
-#
-#   1. `REGISTRY_PRIMARY_<LANG>=0` — legacy DAG path (guarantees we haven't
-#      broken the old path while migrating). Known legacy gaps may be skipped
-#      through the resolver test helper's expected-failure list.
-#   2. `REGISTRY_PRIMARY_<LANG>=1` — registry-primary path (guarantees the
-#      new path carries the same behavior — the parity gate).
-#
-# BOTH must pass. The source of truth is the TypeScript constant — adding
-# a language to that `Set` is the ONLY contributor action; CI auto-
-# discovers it, runs parity, and the language's default production path
-# flips to registry-primary in the same change.
-#
-# When the set is empty (e.g. mid-Ring-3 for every language), the parity
-# matrix is skipped and the workflow reports success — no-op until a
-# language is explicitly claimed migrated.
-
-on:
-  workflow_call:
-
-permissions:
-  contents: read
-
-jobs:
-  discover:
-    name: Discover migrated languages
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    outputs:
-      languages: ${{ steps.read.outputs.languages }}
-      has-any: ${{ steps.read.outputs.has-any }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: ./.github/actions/setup-gitnexus
-
-      - name: Extract MIGRATED_LANGUAGES from registry-primary-flag.ts
-        id: read
-        shell: bash
-        working-directory: gitnexus
-        run: |
-          set -euo pipefail
-          # `tsx` evaluates the TS source directly (no build step), imports
-          # the exported `Set`, and emits a GH-Actions-friendly JSON matrix.
-          LANGS=$(npx tsx scripts/ci-list-migrated-languages.ts)
-          COUNT=$(printf '%s' "$LANGS" | jq 'length')
-          HAS_ANY="false"
-          if [[ "$COUNT" -gt 0 ]]; then HAS_ANY="true"; fi
-          echo "languages=$LANGS" >> "$GITHUB_OUTPUT"
-          echo "has-any=$HAS_ANY" >> "$GITHUB_OUTPUT"
-          echo "Discovered $COUNT migrated language(s): $LANGS"
-          echo "Parity matrix will run: $HAS_ANY"
-
-  parity:
-    name: ${{ matrix.lang.slug }} parity
-    needs: discover
-    if: needs.discover.outputs.has-any == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    strategy:
-      # One language failing must not abort the others — we want the full
-      # parity matrix result on a single CI run so a reviewer sees every
-      # regression at once rather than one-at-a-time.
-      fail-fast: false
-      matrix:
-        lang: ${{ fromJSON(needs.discover.outputs.languages) }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'true'
-
-      - name: Verify resolver test file exists
-        shell: bash
-        working-directory: gitnexus
-        run: |
-          set -euo pipefail
-          TEST_FILE="test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"
-          if [[ ! -f "$TEST_FILE" ]]; then
-            echo "::error title=Missing resolver test::\
-          Expected $TEST_FILE for '${{ matrix.lang.slug }}' (listed in \
-          MIGRATED_LANGUAGES). Either fix the slug or add the test file \
-          before listing this language as migrated."
-            exit 1
-          fi
-
-      - name: Resolver tests — legacy DAG (REGISTRY_PRIMARY_${{ matrix.lang.envvar }}=0)
-        shell: bash
-        working-directory: gitnexus
-        env:
-          FLAG_NAME: REGISTRY_PRIMARY_${{ matrix.lang.envvar }}
-        # Explicitly force the flag to `0` even though it also defaults to
-        # `MIGRATED_LANGUAGES.has(lang)` — once a language is in the set,
-        # the default flips to registry-primary, so an unset env var would
-        # silently re-run the same path as step #2. `env FOO=0 cmd` spawns
-        # `cmd` with the override scoped to just this invocation.
-        run: env "$FLAG_NAME=0" npx vitest run "test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"
-
-      - name: Resolver tests — registry-primary (REGISTRY_PRIMARY_${{ matrix.lang.envvar }}=1)
-        shell: bash
-        working-directory: gitnexus
-        env:
-          FLAG_NAME: REGISTRY_PRIMARY_${{ matrix.lang.envvar }}
-        run: env "$FLAG_NAME=1" npx vitest run "test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"

.github/workflows/ci-tests.yml

@@ -3,16 +3,13 @@ name: Tests
 on:
   workflow_call:
 
-permissions:
-  contents: read
-
 jobs:
   tests:
     name: ubuntu / coverage
     runs-on: ubuntu-latest
     timeout-minutes: 25
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - uses: ./.github/actions/setup-gitnexus
         with:
           build: 'true'
@@ -44,12 +41,9 @@ jobs:
           --outputFile=web-test-results.json
         working-directory: gitnexus-web
 
-      - name: Run docker-server integration tests
-        run: node --test docker-server.test.mjs
-
       - name: Upload test reports
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: test-reports
           path: |
@@ -69,7 +63,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 25
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - uses: ./.github/actions/setup-gitnexus
         with:
           build: 'true'

.github/workflows/ci.yml

@@ -1,35 +1,23 @@
 name: CI
 
 on:
+  push:
+    branches: [main]
+    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
   pull_request:
     branches: [main]
     paths-ignore: ['**.md', 'docs/**', 'LICENSE']
   workflow_call:
 
-permissions:
-  contents: read
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Hardcoded `CI-` prefix (not `${{ github.workflow }}`) because this workflow is
-# invoked as a reusable workflow from publish.yml and release-candidate.yml. In
-# called-workflow context `github.workflow` evaluation is ambiguous across GitHub
-# Actions versions, and a prefix that could resolve to the caller's name would
-# share a concurrency group with the caller → deadlock. A literal prefix is
-# immune. Direct `pull_request` invocations use `CI-<ref>`; invocations from a
-# reusable-workflow caller fall into a per-run-unique group that never serializes
-# with the caller. `push` to main is handled by release-candidate.yml, which
-# calls this workflow once before publishing.
 concurrency:
-  group: ${{ github.event_name == 'pull_request' && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
 
 # ── Reusable workflow orchestration ─────────────────────────────────
 # Each concern lives in its own workflow file for maintainability:
 #   ci-quality.yml       — typecheck (tsc --noEmit)
 #   ci-tests.yml         — unit + integration tests with coverage + cross-platform
 #   ci-e2e.yml           — E2E tests (only when gitnexus-web/ changes)
-#   ci-scope-parity.yml  — RFC #909 Ring 3 parity gate: legacy DAG + registry-primary
-#                          both pass, per migrated language in the JSON registry
 #
 # Shared setup is DRY via .github/actions/setup-gitnexus composite action.
 
@@ -49,11 +37,6 @@ jobs:
     permissions:
       contents: read
 
-  scope-parity:
-    uses: ./.github/workflows/ci-scope-parity.yml
-    permissions:
-      contents: read
-
   # ── Save PR metadata for the reporting workflow ─────────────────
   # The ci-report.yml workflow (triggered by workflow_run) needs the
   # PR number and job results to post a comment.  We save them as an
@@ -62,7 +45,7 @@ jobs:
   save-pr-meta:
     name: Save PR Metadata
     if: always() && github.event_name == 'pull_request'
-    needs: [quality, tests, e2e, scope-parity]
+    needs: [quality, tests, e2e]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -73,14 +56,12 @@ jobs:
           QUALITY: ${{ needs.quality.result }}
           TESTS: ${{ needs.tests.result }}
           E2E: ${{ needs.e2e.result }}
-          SCOPE_PARITY: ${{ needs.scope-parity.result }}
         run: |
           mkdir -p pr-meta
-          echo "$PR_NUMBER"      > pr-meta/pr_number
-          echo "$QUALITY"        > pr-meta/quality_result
-          echo "$TESTS"          > pr-meta/tests_result
-          echo "$E2E"            > pr-meta/e2e_result
-          echo "$SCOPE_PARITY"   > pr-meta/scope_parity_result
+          echo "$PR_NUMBER"  > pr-meta/pr_number
+          echo "$QUALITY"    > pr-meta/quality_result
+          echo "$TESTS"      > pr-meta/tests_result
+          echo "$E2E"        > pr-meta/e2e_result
           # TODO(post-merge): remove backward-compat copies once ci-report.yml
           # on main reads underscore names.
           # Backward-compat: ci-report.yml on main still reads hyphenated
@@ -93,7 +74,7 @@ jobs:
           cp pr-meta/e2e_result      pr-meta/e2e-result
 
       - name: Upload PR metadata
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: pr-meta
           path: pr-meta/
@@ -103,7 +84,7 @@ jobs:
   # Single required check for branch protection.
   ci-status:
     name: CI Gate
-    needs: [quality, tests, e2e, scope-parity]
+    needs: [quality, tests, e2e]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -114,12 +95,10 @@ jobs:
           QUALITY: ${{ needs.quality.result }}
           TESTS: ${{ needs.tests.result }}
           E2E: ${{ needs.e2e.result }}
-          SCOPE_PARITY: ${{ needs.scope-parity.result }}
         run: |
-          echo "Quality:        $QUALITY"
-          echo "Tests:          $TESTS"
-          echo "E2E:            $E2E"
-          echo "Scope parity:   $SCOPE_PARITY"
+          echo "Quality:     $QUALITY"
+          echo "Tests:       $TESTS"
+          echo "E2E:         $E2E"
           if [[ "$QUALITY" != "success" ]] ||
              [[ "$TESTS" != "success" ]]; then
             echo "::error::Quality or test jobs failed"
@@ -129,14 +108,3 @@ jobs:
             echo "::error::E2E job failed"
             exit 1
           fi
-          # scope-parity is a reusable workflow. With an empty migrated-
-          # languages list, its parity matrix is skipped and the outer
-          # workflow still reports `success`. If any entry's legacy-DAG or
-          # registry-primary run fails, the workflow reports `failure`.
-          # Accept only `success`; `skipped` would mean the entire
-          # discover job was skipped too (upstream failure), which should
-          # still block.
-          if [[ "$SCOPE_PARITY" != "success" ]]; then
-            echo "::error::Scope-resolution parity gate failed (RFC #909 Ring 3)"
-            exit 1
-          fi

.github/workflows/claude-code-review.yml

@@ -0,0 +1,95 @@
+name: Claude Code Review
+
+# Uses pull_request_target so the workflow runs as defined on the default branch,
+# which allows access to secrets for posting review comments on fork PRs.
+# SECURITY: The checkout pins the fork's HEAD SHA (not the branch name) to
+# prevent TOCTOU races (force-push between trigger and checkout). The
+# claude-code-action sandboxes execution — it does NOT run arbitrary code
+# from the checked-out source.
+
+on:
+  # Trigger only when explicitly requested:
+  #   - Add the "claude-review" label to a PR, OR
+  #   - Comment "@claude" or "/review" on a PR
+  pull_request_target:
+    types: [labeled]
+  issue_comment:
+    types: [created]
+
+# Serialize per-PR to avoid racing review comments.
+concurrency:
+  group: claude-review-${{ github.event.issue.number || github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  claude-review:
+    # Run only when:
+    #   1. The "claude-review" label is added to a non-draft PR by a trusted contributor, OR
+    #   2. A trusted contributor comments "@claude" or "/review" on a PR
+    if: |
+      (
+        github.event_name == 'pull_request_target' &&
+        github.event.label.name == 'claude-review' &&
+        github.event.pull_request.draft == false &&
+        (github.event.pull_request.author_association == 'OWNER' ||
+         github.event.pull_request.author_association == 'MEMBER' ||
+         github.event.pull_request.author_association == 'COLLABORATOR')
+      ) ||
+      (
+        github.event_name == 'issue_comment' &&
+        github.event.issue.pull_request &&
+        (contains(github.event.comment.body, '@claude') ||
+         contains(github.event.comment.body, '/review')) &&
+        (github.event.comment.author_association == 'OWNER' ||
+         github.event.comment.author_association == 'MEMBER' ||
+         github.event.comment.author_association == 'COLLABORATOR')
+      )
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+
+    steps:
+      # For issue_comment triggers, resolve the PR number, head SHA, and fork repo
+      - name: Resolve PR context
+        id: pr
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        with:
+          script: |
+            let pr;
+            if (context.eventName === 'issue_comment') {
+              const resp = await github.rest.pulls.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.issue.number,
+              });
+              pr = resp.data;
+            } else {
+              pr = context.payload.pull_request;
+            }
+            core.setOutput('number', pr.number);
+            core.setOutput('sha', pr.head.sha);
+            core.setOutput('repo', pr.head.repo.full_name);
+            core.setOutput('branch', pr.head.ref);
+
+      - name: Checkout PR head
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          repository: ${{ steps.pr.outputs.repo }}
+          ref: ${{ steps.pr.outputs.sha }}
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          allowed_non_write_users: '*'
+          show_full_output: true
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'

.github/workflows/claude.yml

@@ -1,17 +1,8 @@
 name: Claude Code
 
-# Label-triggered code-review requests use pull_request_target so the workflow
-# runs as defined on the default branch, which allows access to secrets for
-# posting review comments on fork PRs. SECURITY: PR checkouts pin the fork's
-# HEAD SHA (not the branch name) to prevent TOCTOU races.
-# The claude-code-action sandboxes execution; it does not run arbitrary code
-# from the checked-out source.
-
 on:
   issue_comment:
     types: [created]
-  pull_request_target:
-    types: [labeled]
   pull_request_review_comment:
     types: [created]
   issues:
@@ -19,13 +10,9 @@ on:
   pull_request_review:
     types: [submitted]
 
-permissions:
-  contents: read
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
 # Serialize per-PR/issue to avoid racing comments.
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number || github.event.issue.id }}
+  group: claude-code-${{ github.event.issue.number || github.event.pull_request.number || github.event.issue.id }}
   cancel-in-progress: false
 
 jobs:
@@ -33,10 +20,7 @@ jobs:
     if: |
       (
         github.event_name == 'issue_comment' &&
-        (
-          contains(github.event.comment.body, '@claude') ||
-          (github.event.issue.pull_request && contains(github.event.comment.body, '/review'))
-        ) &&
+        contains(github.event.comment.body, '@claude') &&
         (github.event.comment.author_association == 'OWNER' ||
          github.event.comment.author_association == 'MEMBER' ||
          github.event.comment.author_association == 'COLLABORATOR')
@@ -61,14 +45,6 @@ jobs:
         (github.event.issue.author_association == 'OWNER' ||
          github.event.issue.author_association == 'MEMBER' ||
          github.event.issue.author_association == 'COLLABORATOR')
-      ) ||
-      (
-        github.event_name == 'pull_request_target' &&
-        github.event.label.name == 'claude-review' &&
-        github.event.pull_request.draft == false &&
-        (github.event.pull_request.author_association == 'OWNER' ||
-         github.event.pull_request.author_association == 'MEMBER' ||
-         github.event.pull_request.author_association == 'COLLABORATOR')
       )
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -82,61 +58,45 @@ jobs:
       # For PR-related triggers, resolve the fork repo so we can checkout correctly.
       - name: Resolve PR context
         id: pr
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
         with:
           script: |
             // Determine if this event is PR-related
-            let pr = null;
+            let prNumber = null;
             if (context.eventName === 'issue_comment' && context.payload.issue.pull_request) {
-              const resp = await github.rest.pulls.get({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                pull_number: context.payload.issue.number,
-              });
-              pr = resp.data;
+              prNumber = context.payload.issue.number;
             } else if (context.eventName === 'pull_request_review_comment') {
-              pr = context.payload.pull_request;
+              prNumber = context.payload.pull_request.number;
             } else if (context.eventName === 'pull_request_review') {
-              pr = context.payload.pull_request;
-            } else if (context.eventName === 'pull_request_target') {
-              pr = context.payload.pull_request;
+              prNumber = context.payload.pull_request.number;
             }
 
-            if (!pr) {
+            if (!prNumber) {
               core.setOutput('is_pr', 'false');
               return;
             }
 
+            const resp = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber,
+            });
+            const pr = resp.data;
+
             core.setOutput('is_pr', 'true');
-            core.setOutput('number', String(pr.number));
+            core.setOutput('number', String(prNumber));
             core.setOutput('sha', pr.head.sha);
             core.setOutput('repo', pr.head.repo.full_name);
             core.setOutput('branch', pr.head.ref);
 
-      - name: Resolve Claude mode
-        id: mode
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
-        with:
-          script: |
-            const body = (context.payload.comment?.body ?? '').toLowerCase();
-            const isCodeReview =
-              (context.eventName === 'pull_request_target' &&
-                context.payload.label?.name === 'claude-review') ||
-              (context.eventName === 'issue_comment' &&
-                Boolean(context.payload.issue?.pull_request) &&
-                body.includes('/review'));
-
-            core.setOutput('code_review', isCodeReview ? 'true' : 'false');
-
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           repository: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.repo || github.repository }}
           ref: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.sha || '' }}
           fetch-depth: 1
 
       - name: Run Claude Code
-        if: steps.mode.outputs.code_review != 'true'
         id: claude
         uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
         with:
@@ -148,18 +108,3 @@ jobs:
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
-
-      - name: Run Claude Code Review
-        if: steps.mode.outputs.code_review == 'true'
-        id: claude-review
-        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          allowed_non_write_users: '*'
-          show_full_output: true
-          # Review posts use Bash (`gh`, etc.); default mode asks for approval — impossible in CI.
-          claude_args: '--dangerously-skip-permissions'
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review https://github.com/${{ github.repository }}/pull/${{ steps.pr.outputs.number }} --comment'

.github/workflows/codeql.yml

@@ -1,74 +0,0 @@
-name: CodeQL
-
-# Static analysis (SAST) for TypeScript/JavaScript and Python sources.
-# Findings upload to the GitHub Security tab as SARIF.
-#
-# Advisory only on first introduction — see docs/plans/2026-05-03-001-feat-automated-security-scans-plan.md.
-# Promote to a required check after baseline triage (operator decision).
-
-on:
-  pull_request:
-    branches: [main]
-    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
-  push:
-    branches: [main]
-  schedule:
-    # Weekly Monday 06:00 UTC — catches advisories newly published against
-    # already-merged code without waiting for the next PR.
-    - cron: '0 6 * * 1'
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  analyze:
-    name: Analyze (${{ matrix.language }})
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    permissions:
-      actions: read
-      contents: read
-      # security-events:write is what enables SARIF upload to the Security tab.
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [javascript-typescript, python]
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          # Don't leave GITHUB_TOKEN in .git/config for downstream steps to read.
-          persist-credentials: false
-
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
-        with:
-          languages: ${{ matrix.language }}
-          queries: security-and-quality
-          # Exclude generated/vendored code; tune after first-run signal.
-          # gitnexus/vendor/ holds tree-sitter-proto sources (regenerated, not authored).
-          # CodeQL path filters use .gitignore-style globs and do NOT support
-          # brace expansion — list each generated parser file separately.
-          config: |
-            paths-ignore:
-              - '**/dist/**'
-              - '**/node_modules/**'
-              - 'gitnexus/vendor/**'
-              - 'gitnexus/src/core/parsing/**/parser.c'
-              - 'gitnexus/src/core/parsing/**/parser.js'
-              # Test fixtures are intentionally synthetic inputs (broken/unused
-              # code, malformed samples) used to exercise the analyzer. CodeQL
-              # findings here are noise, not real bugs.
-              - '**/test/fixtures/**'
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
-        with:
-          category: '/language:${{ matrix.language }}'

.github/workflows/dependency-review.yml

@@ -1,39 +0,0 @@
-name: Dependency Review
-
-# Blocks PRs that introduce dependencies with high/critical known vulnerabilities.
-# Reads the dependency graph diff between PR head and base.
-#
-# This is a required-check candidate after one week of clean runs
-# (operator decision — see docs/plans/2026-05-03-001-feat-automated-security-scans-plan.md).
-
-on:
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  review:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      contents: read
-      # pull-requests:write enables the inline summary comment on failure.
-      pull-requests: write
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Dependency Review
-        uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
-        with:
-          fail-on-severity: high
-          comment-summary-in-pr: on-failure

.github/workflows/docker.yml

@@ -1,262 +0,0 @@
-name: Docker Build & Push
-
-on:
-  push:
-    tags:
-      - 'v*'
-  pull_request:
-  # workflow_dispatch is allowed for dry-run testing only. Publishing is still
-  # exclusively tag-driven so that every signed image corresponds 1:1 to a
-  # published `gitnexus@X.Y.Z` on npm. dry_run:true (the default) skips all
-  # push, sign, and attestation steps — the build runs but nothing is published.
-  workflow_dispatch:
-    inputs:
-      dry_run:
-        description: 'Build only — skip push, signing, and attestations'
-        required: false
-        default: true
-        type: boolean
-  workflow_call:
-    inputs:
-      tag:
-        description: >-
-          The full v-prefixed tag to build (e.g. v1.2.3-rc.1).
-          The tag must already exist in the repo and its tree must contain
-          a gitnexus/package.json whose version matches the tag.
-        required: true
-        type: string
-
-permissions:
-  contents: read
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Tag refs are unique per release, so distinct tags run in parallel.
-# Re-pushes of the same tag serialize. cancel-in-progress: false — never cancel a publish mid-flight.
-# Hardcoded `docker-build-push-` prefix (not `${{ github.workflow }}`) when invoked as a reusable
-# workflow: in called-workflow context `github.workflow` is ambiguous and could resolve to the
-# caller's name, sharing a concurrency group with the caller → deadlock.
-# Direct tag-push invocations use `docker-build-push-<ref>`; workflow_call invocations get a
-# per-run-unique group (they are already serialized by the caller's own concurrency group).
-concurrency:
-  group: ${{ (github.event_name == 'push') && format('docker-build-push-{0}', github.ref) || format('docker-build-push-nested-{0}', github.run_id) }}
-  cancel-in-progress: false
-
-jobs:
-  build-push:
-    name: Build & Push ${{ matrix.image.name }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    permissions:
-      contents: read
-      packages: write
-      # Required for Cosign keyless signing via the OIDC token exchange,
-      # and for build provenance / SBOM attestations.
-      id-token: write
-      attestations: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        image:
-          # Static UI bundle. Small, fast image. Drop-in replacement for the
-          # legacy single-image setup at the same `gitnexus` repository slug
-          # is intentionally avoided — the UI now lives at `gitnexus-web` and
-          # the CLI/server takes the canonical `gitnexus` slug below.
-          - name: gitnexus-web
-            dockerfile: Dockerfile.web
-            slug: gitnexus-web
-          # CLI / `gitnexus serve` backend. Heavy native deps (tree-sitter,
-          # onnxruntime-node) live only in this image.
-          - name: gitnexus
-            dockerfile: Dockerfile.cli
-            slug: gitnexus
-
-    steps:
-      # Only the workflow_call path requires a non-empty `inputs.tag` — callers
-      # (e.g. release-candidate.yml) must pass the RC tag explicitly. On direct
-      # tag pushes the tag comes from `github.ref`, so `inputs.tag` is always
-      # empty and validating it here would break every real release (#1064).
-      # The downstream "Verify tag matches gitnexus/package.json version" step
-      # handles both event types by falling back to GITHUB_REF.
-      - name: Validate tag input
-        if: github.event_name == 'workflow_call'
-        shell: bash
-        env:
-          TAG_INPUT: ${{ inputs.tag }}
-        run: |
-          if [ -z "${TAG_INPUT}" ]; then
-            echo "::error::No tag provided to docker.yml — refusing to build/push."
-            exit 1
-          fi
-
-      # When triggered by workflow_call the caller passes the RC tag as an input;
-      # we check out that tag so the Dockerfile and package.json match the built image.
-      # For tag-push events github.ref is already the tag ref — no override needed.
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          ref: ${{ inputs.tag || github.ref }}
-
-      # ── Lock the docker image version to the npm package version ──────────
-      # Mirrors the check in publish.yml: refuse to build unless the git tag
-      # exactly matches `gitnexus/package.json`'s version. This guarantees
-      # `ghcr.io/<owner>/gitnexus:X.Y.Z` always corresponds to the same
-      # `gitnexus@X.Y.Z` published to npm — no drift, no surprises.
-      - name: Verify tag matches gitnexus/package.json version
-        id: version
-        if: github.event_name != 'workflow_dispatch' && github.event_name != 'pull_request'
-        shell: bash
-        env:
-          # For workflow_call the tag comes from the caller input; for push events
-          # it is derived from GITHUB_REF (set to empty so the else-branch fires).
-          INPUT_TAG: ${{ inputs.tag }}
-        run: |
-          if [ -n "$INPUT_TAG" ]; then
-            TAG_VERSION="${INPUT_TAG#v}"
-          else
-            TAG_VERSION="${GITHUB_REF#refs/tags/v}"
-          fi
-          if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
-            echo "::error::Tag does not follow semver: v$TAG_VERSION"
-            exit 1
-          fi
-          PKG_VERSION=$(node -p "require('./gitnexus/package.json').version")
-          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
-            echo "::error::Tag version (v$TAG_VERSION) does not match gitnexus/package.json version ($PKG_VERSION)"
-            exit 1
-          fi
-          echo "version=$PKG_VERSION" >> "$GITHUB_OUTPUT"
-          echo "Version verified: $PKG_VERSION"
-
-      # Required for multi-platform (linux/arm64) emulation.
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
-
-      - name: Install Cosign
-        uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003 # v4.1.1
-
-      - name: Log in to GitHub Container Registry
-        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      # Docker Hub is a mirror of GHCR: same tags, same digests, same Cosign
-      # signatures. GHCR remains authoritative (it is the registry the
-      # ClusterImagePolicy globs against by default), but Docker Hub is the
-      # registry most users reach for first, so we publish there too.
-      # Requires repo secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN (a scoped
-      # access token, NOT the account password) with write access to the
-      # `akonlabs/gitnexus` and `akonlabs/gitnexus-web` repos.
-      - name: Log in to Docker Hub
-        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      # Computes image tags and labels from the verified semver tag:
-      #   v1.2.3        → :1.2.3, :1.2, :1, :latest (auto, only for non-prerelease)
-      #   v1.2.3-rc.1   → :1.2.3-rc.1 only (prereleases never become :latest)
-      # `:latest` is only emitted for tag pushes thanks to `flavor: latest=auto`,
-      # ensuring it always points at a real npm-published version.
-      #
-      # For workflow_call invocations github.ref is the caller's branch ref, so
-      # the type=semver patterns would not match. In that case we add an explicit
-      # type=raw tag using the version already verified above, so the same
-      # image-naming rules apply regardless of how the workflow was triggered.
-      # NOTE: We check `inputs.tag` rather than `github.event_name` because in a
-      # reusable workflow the github context is inherited from the caller —
-      # `github.event_name` would still be "push", not "workflow_call".
-      - name: Extract Docker metadata
-        id: meta
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
-        with:
-          # Dual-registry publish. metadata-action expands the same tag set
-          # against every image ref listed here, and build-push-action pushes
-          # one build to all of them, so the GHCR and Docker Hub images share
-          # a digest and are byte-identical. The Docker Hub namespace
-          # (`akonlabs`) is hardcoded because it differs from the GitHub org
-          # (`abhigyanpatwari`) — `github.repository_owner` would produce the
-          # wrong ref.
-          images: |
-            ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
-            docker.io/akonlabs/${{ matrix.image.slug }}
-          flavor: latest=auto
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
-            type=raw,value=${{ steps.version.outputs.version }},enable=${{ inputs.tag != '' }}
-
-      # Transient 502s from GHCR / Docker Hub / GHA cache during multi-platform
-      # exports are retried inside `.github/actions/docker-build-push-retry`
-      # (see docker/build-push-action#1422 — retry policy stays out of the
-      # upstream action). `ignore-error=true` on cache-to avoids cache export
-      # flakes failing an otherwise successful push.
-      - name: Build and push
-        id: build
-        uses: ./.github/actions/docker-build-push-retry
-        with:
-          context: .
-          file: ${{ matrix.image.dockerfile }}
-          platforms: linux/amd64,linux/arm64
-          push: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha,scope=${{ matrix.image.slug }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.image.slug }},ignore-error=true
-
-      # Cosign keyless signing. Each pushed tag is signed by the workflow's
-      # OIDC identity, so consumers can verify the image with the strict,
-      # fully-anchored identity regex (kept in sync with README.md and
-      # deploy/kubernetes/cluster-image-policy.yaml — update all three together).
-      # NOTE: `${...}` expression syntax is NOT evaluated inside YAML comments, so
-      # the example below uses literal `<owner>/<repo>` placeholders that consumers
-      # substitute themselves; the canonical, fully-rendered command lives in README.md.
-      #   cosign verify ghcr.io/<owner>/<slug>:<tag> \
-      #     --certificate-identity-regexp '^https://github\.com/<owner>/<repo>/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
-      #     --certificate-oidc-issuer https://token.actions.githubusercontent.com
-      # Do NOT relax to `@.*` — that accepts signatures from any ref, including
-      # unprotected branches and PRs, and defeats the supply-chain guarantee.
-      - name: Sign image with Cosign (keyless)
-        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
-        env:
-          # Cosign v2 (installed by sigstore/cosign-installer above) makes
-          # keyless the default. COSIGN_EXPERIMENTAL is a v1-only opt-in flag
-          # that is now deprecated/no-op, so it is intentionally omitted.
-          DIGEST: ${{ steps.build.outputs.digest }}
-          TAGS: ${{ steps.meta.outputs.tags }}
-        run: |
-          # Sign every tag at the same digest so consumers can verify by tag or by digest.
-          # Use `while read` instead of `for $TAGS` to be robust against tags that
-          # could ever contain whitespace (the metadata-action output is newline-
-          # separated, not space-separated).
-          while IFS= read -r tag; do
-            [[ -n "$tag" ]] && cosign sign --yes "${tag}@${DIGEST}"
-          done <<< "$TAGS"
-
-      # Attach the SBOM produced by buildx as a verifiable attestation on the
-      # digest. Attestations are pushed as OCI referrers to the registry named
-      # in `subject-name`, so we call the action once per registry. The digest
-      # is identical across registries (same build, same push), so consumers
-      # pulling from either GHCR or Docker Hub see the same provenance.
-      - name: Generate build provenance attestation (GHCR)
-        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
-        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
-        with:
-          subject-name: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
-          subject-digest: ${{ steps.build.outputs.digest }}
-          push-to-registry: true
-
-      - name: Generate build provenance attestation (Docker Hub)
-        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
-        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
-        with:
-          subject-name: docker.io/akonlabs/${{ matrix.image.slug }}
-          subject-digest: ${{ steps.build.outputs.digest }}
-          push-to-registry: true

.github/workflows/gitleaks.yml

@@ -1,48 +0,0 @@
-name: Gitleaks
-
-# Deterministic in-CI secret scanning. Defense-in-depth on top of GitHub's
-# native secret-scanning push protection (which is a repo Settings toggle —
-# see SECURITY.md for the recommended admin action).
-#
-# PR runs scan the diff (fast); main pushes scan full history.
-
-on:
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  gitleaks:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      contents: read
-      pull-requests: write
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          # Full history needed for the on-push full-history scan; on PRs the
-          # action diffs against the base ref so the cost is bounded by the PR.
-          fetch-depth: 0
-          # Don't bake the token into the cloned .git/config; downstream
-          # steps (and Gitleaks itself) don't need it for repo operations.
-          persist-credentials: false
-
-      # No GITLEAKS_LICENSE secret is required for OSS / public-repo usage.
-      # If this repo becomes private, the action will require a license key.
-      - name: Gitleaks
-        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: true
-          GITLEAKS_ENABLE_SUMMARY: true

.github/workflows/pr-autofix-apply.yml

@@ -1,595 +0,0 @@
-name: PR Autofix (apply)
-
-# CHATOPS HALF of the autofix pipeline.
-#
-# Triggered when a contributor comments `/autofix` on a PR. Validates
-# permission, locates the most recent successful `pr-autofix.yml`
-# artifact for the PR's current head SHA, applies the patch to the PR
-# head, and pushes a commit back to the PR branch.
-#
-# This workflow runs from the default branch's copy of the file
-# regardless of where the comment originates -- that's the trust
-# anchor. Comment body and author login are untrusted; both flow
-# through env vars and pattern-matched, never interpolated into shell.
-#
-# Fork PR support: `git push` with the GITHUB_TOKEN succeeds against
-# fork branches only when the contributor enabled "Allow edits by
-# maintainers" on the PR (the default). When they disabled it, we
-# fail loud with a 👎 reaction and an explanation comment.
-
-on:
-  issue_comment:
-    types: [created]
-
-concurrency:
-  # Per-PR scope. issue_comment events expose `github.event.issue.number`
-  # for both PR and Issue comments; the `pull_request != null` guard on
-  # the job ensures we only run on PRs, so this number is the PR number.
-  # cancel-in-progress: false — a second `/autofix` should wait for the
-  # first to finish (idempotency check on the second invocation handles
-  # the no-op case).
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
-  cancel-in-progress: false
-
-permissions: {}
-
-jobs:
-  apply:
-    name: apply-autofix
-    # Pre-filter at the workflow level so non-PR comments and unrelated
-    # comments don't even spawn a runner. The job-level body re-check
-    # below (Step 1) is the strict gate.
-    if: >-
-      github.event.issue.pull_request != null
-      && startsWith(github.event.comment.body, '/autofix')
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      # React on the triggering comment + post reply comments.
-      pull-requests: write
-      # Push the apply commit to the PR head branch.
-      contents: write
-      # Required by actions/download-artifact to fetch artifacts produced
-      # by a different workflow run.
-      actions: read
-    steps:
-      - name: Validate comment body precisely
-        id: body
-        env:
-          BODY: ${{ github.event.comment.body }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          # Whole-line, case-sensitive match: `^/autofix\s*$`. The
-          # workflow-level startsWith guard is coarse — `please don't
-          # /autofix this code` would pass that filter but fail this one.
-          # We exit silently (no reaction) on body mismatch so quoted
-          # text in unrelated discussions doesn't get a visible response.
-          if [[ ! "${BODY}" =~ ^/autofix[[:space:]]*$ ]]; then
-            echo "Body did not match strict /autofix regex — exiting silently."
-            echo "match=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          echo "match=true" >> "$GITHUB_OUTPUT"
-
-      - name: Validate commenter permission
-        id: perm
-        if: steps.body.outputs.match == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          COMMENTER: ${{ github.event.comment.user.login }}
-          PR_AUTHOR: ${{ github.event.issue.user.login }}
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          # Retry wrapper for transient 5xx / 429 / network blips.
-          # Mirrors the helper in pr-autofix-publish.yml. Used on
-          # idempotent GETs only; reactions/comment-POSTs are NOT
-          # wrapped (retrying a POST would dupe the resource).
-          gh_retry() {
-            local n=0 max=3
-            while true; do
-              if gh "$@"; then return 0; fi
-              n=$((n+1))
-              if [ "$n" -ge "$max" ]; then return 1; fi
-              sleep $((n * 2))
-            done
-          }
-
-          # Allowlist the commenter login before it flows into a URL.
-          # GitHub usernames: alphanumeric + dashes, max 39 chars.
-          if ! [[ "${COMMENTER}" =~ ^[A-Za-z0-9-]{1,39}$ ]]; then
-            echo "::error::Invalid commenter login format: $(printf '%q' "${COMMENTER}")"
-            echo "allowed=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Self-comparison: PR author can always /autofix their own PR.
-          if [ "${COMMENTER}" = "${PR_AUTHOR}" ]; then
-            echo "Commenter is PR author — granting access."
-            echo "allowed=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Repo permission lookup. admin/write/maintain are sufficient.
-          # Distinguish API failure (5xx, 429, network) from genuine
-          # permission denial (404 = not a collaborator). Conflating them
-          # would silently refuse a legitimate maintainer with a public
-          # 👎 every time GitHub blips. gh_retry handles transient blips;
-          # the stderr-grep distinguishes 404 from persistent failure.
-          perm_stderr=$(mktemp)
-          if permission=$(gh_retry api "repos/${GH_REPO}/collaborators/${COMMENTER}/permission" \
-                --jq '.permission' 2>"$perm_stderr"); then
-            echo "Commenter permission: ${permission}"
-            case "${permission}" in
-              admin|write|maintain)
-                echo "allowed=true" >> "$GITHUB_OUTPUT"
-                ;;
-              *)
-                echo "allowed=false" >> "$GITHUB_OUTPUT"
-                ;;
-            esac
-          else
-            err=$(cat "$perm_stderr")
-            echo "Permission lookup stderr: ${err}" >&2
-            # 404 (not a collaborator) is a genuine deny.
-            # Anything else is a transient API/network failure.
-            if grep -qE "HTTP 404|Not Found" "$perm_stderr"; then
-              echo "allowed=false" >> "$GITHUB_OUTPUT"
-            else
-              echo "::error::Permission lookup failed transiently — refusing to act."
-              echo "allowed=api-failed" >> "$GITHUB_OUTPUT"
-            fi
-          fi
-
-      - name: React 😕 on transient permission-API failure
-        if: steps.body.outputs.match == 'true' && steps.perm.outputs.allowed == 'api-failed'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          COMMENT_ID: ${{ github.event.comment.id }}
-          PR: ${{ github.event.issue.number }}
-          RUN_ID: ${{ github.run_id }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-            -f content="confused" >/dev/null
-          gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-            -f body="⚠️ Couldn't verify your repo permission (transient GitHub API failure). Please comment \`/autofix\` again. ([apply run](https://github.com/${GH_REPO}/actions/runs/${RUN_ID}))" \
-            >/dev/null
-          exit 1
-
-      - name: React 👎 on permission denial
-        if: steps.body.outputs.match == 'true' && steps.perm.outputs.allowed == 'false'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          COMMENT_ID: ${{ github.event.comment.id }}
-          PR: ${{ github.event.issue.number }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-            -f content="-1" >/dev/null
-          gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-            -f body="🚫 \`/autofix\` is restricted to users with write access or the PR author. Comment ignored." \
-            >/dev/null
-          # Hard exit so the rest of the job is skipped.
-          exit 1
-
-      - name: React 👀 to acknowledge
-        if: steps.perm.outputs.allowed == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          COMMENT_ID: ${{ github.event.comment.id }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-            -f content="eyes" >/dev/null
-
-      - name: Resolve PR head and locate autofix run
-        id: locate
-        if: steps.perm.outputs.allowed == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          PR: ${{ github.event.issue.number }}
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          # Same retry wrapper used in the permission step, repeated
-          # because each YAML `run:` block is a fresh bash session.
-          gh_retry() {
-            local n=0 max=3
-            while true; do
-              if gh "$@"; then return 0; fi
-              n=$((n+1))
-              if [ "$n" -ge "$max" ]; then return 1; fi
-              sleep $((n * 2))
-            done
-          }
-
-          # Fetch PR metadata. All fields here are server-controlled API
-          # output, but we still allowlist before exporting so anything
-          # weird short-circuits before $GITHUB_OUTPUT. Wrapped in
-          # gh_retry so transient blips don't surface as "no autofix run
-          # found" with a wrong remediation.
-          if ! pr_json=$(gh_retry api "repos/${GH_REPO}/pulls/${PR}"); then
-            echo "::error::PR metadata fetch failed after retries."
-            echo "found_status=api-failed" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          head_sha=$(jq -r '.head.sha' <<< "${pr_json}")
-          head_ref=$(jq -r '.head.ref' <<< "${pr_json}")
-          head_repo=$(jq -r '.head.repo.full_name' <<< "${pr_json}")
-
-          [[ "${head_sha}"  =~ ^[0-9a-f]{40}$                         ]] || { echo "::error::Bad head_sha";  exit 1; }
-          [[ "${head_ref}"  =~ ^[A-Za-z0-9._/-]+$                     ]] || { echo "::error::Bad head_ref";  exit 1; }
-          [[ "${head_repo}" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$      ]] || { echo "::error::Bad head_repo"; exit 1; }
-
-          # Find the latest successful pr-autofix.yml run for this head SHA.
-          if ! runs_json=$(gh_retry api "repos/${GH_REPO}/actions/workflows/pr-autofix.yml/runs?head_sha=${head_sha}&per_page=10"); then
-            echo "::error::Workflow run lookup failed after retries."
-            echo "found_status=api-failed" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          run_id=$(jq -r '[.workflow_runs[] | select(.conclusion == "success")] | .[0].id // empty' <<< "${runs_json}")
-
-          if [ -n "${run_id}" ] && [[ "${run_id}" =~ ^[0-9]+$ ]]; then
-            echo "found_status=success" >> "$GITHUB_OUTPUT"
-            {
-              echo "found=true"
-              echo "head_sha=${head_sha}"
-              echo "head_ref=${head_ref}"
-              echo "head_repo=${head_repo}"
-              echo "run_id=${run_id}"
-            } >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # No successful run. Distinguish "still running" (producer in
-          # flight after a recent push) from "never ran / all failed".
-          # in_progress / queued / pending / waiting cover the GitHub
-          # workflow-run lifecycle states that precede success/failure.
-          in_progress=$(jq -r '[.workflow_runs[] | select(.status == "in_progress" or .status == "queued" or .status == "pending" or .status == "waiting")] | length' <<< "${runs_json}")
-          if [ "${in_progress:-0}" -gt 0 ]; then
-            echo "::warning::pr-autofix run is still in progress for head ${head_sha}."
-            echo "found_status=in-progress" >> "$GITHUB_OUTPUT"
-          else
-            echo "::warning::No successful pr-autofix run found for head ${head_sha}."
-            echo "found_status=not-found" >> "$GITHUB_OUTPUT"
-          fi
-          # Existing `found` boolean is preserved so downstream gates
-          # (`steps.locate.outputs.found == 'true'`) still work.
-          echo "found=false" >> "$GITHUB_OUTPUT"
-
-      - name: Reply when locate did not yield a usable run
-        if: steps.perm.outputs.allowed == 'true' && steps.locate.outputs.found != 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          COMMENT_ID: ${{ github.event.comment.id }}
-          PR: ${{ github.event.issue.number }}
-          FOUND_STATUS: ${{ steps.locate.outputs.found_status }}
-          RUN_ID: ${{ github.run_id }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          run_url="https://github.com/${GH_REPO}/actions/runs/${RUN_ID}"
-          case "${FOUND_STATUS}" in
-            in-progress)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="confused" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="⏳ A pr-autofix run is still in progress for this PR's current head SHA. Wait for it to finish, then comment \`/autofix\` again. ([apply run](${run_url}))" \
-                >/dev/null
-              ;;
-            api-failed)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="confused" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="⚠️ Couldn't reach the GitHub API to look up the autofix run (transient failure after retries). Please comment \`/autofix\` again. ([apply run](${run_url}))" \
-                >/dev/null
-              ;;
-            *)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="-1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="🤔 No successful autofix run found for this PR's current head SHA. Push a new commit to trigger one, then comment \`/autofix\` again." \
-                >/dev/null
-              ;;
-          esac
-          exit 1
-
-      # Pinned to v8.0.1. Same SHA as pr-autofix-publish.yml.
-      # `continue-on-error: true` lets the workflow proceed when the
-      # artifact is expired or pruned (1-day retention). The apply
-      # step distinguishes "patch file missing entirely" (artifact-
-      # expired) from "patch file zero bytes" (genuinely empty patch).
-      - name: Download autofix artifact
-        if: steps.locate.outputs.found == 'true'
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        continue-on-error: true
-        with:
-          name: autofix
-          run-id: ${{ steps.locate.outputs.run_id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          path: autofix-in
-
-      # Pinned to v5.0.4. Verify SHA via:
-      #   gh api repos/actions/checkout/git/refs/tags/v5.0.4
-      #
-      # `persist-credentials: false` disables the default behavior where
-      # actions/checkout writes the GITHUB_TOKEN into `.git/config` as an
-      # extraheader. That default is convenient (subsequent git commands
-      # auth automatically) but it means the token is sitting on disk in
-      # the checkout directory — an `actions/upload-artifact` step on
-      # this directory would leak the token. We don't upload, but
-      # zizmor's `credential-persistence` lint flags it defensively.
-      # Push auth is provided inline at push time via the URL.
-      - name: Checkout PR head
-        if: steps.locate.outputs.found == 'true'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v5.0.4
-        with:
-          repository: ${{ steps.locate.outputs.head_repo }}
-          ref: ${{ steps.locate.outputs.head_sha }}
-          token: ${{ secrets.GITHUB_TOKEN }}
-          persist-credentials: false
-          # Fetch full history so the push doesn't hit shallow-clone errors.
-          fetch-depth: 0
-          path: pr-checkout
-
-      - name: Apply patch and push
-        id: apply
-        if: steps.locate.outputs.found == 'true'
-        env:
-          HEAD_REF: ${{ steps.locate.outputs.head_ref }}
-          HEAD_REPO: ${{ steps.locate.outputs.head_repo }}
-          # The SHA we resolved earlier in `locate` — this is what the
-          # remote ref MUST still equal at push time. If the contributor
-          # force-pushed between resolve and now, the lease fails and
-          # we surface that distinctly from a fork-without-maintainer
-          # -edit push failure.
-          HEAD_SHA: ${{ steps.locate.outputs.head_sha }}
-          # Auth for the push only — never persisted to disk. Provided
-          # via env to avoid interpolating into the shell command line.
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        shell: bash
-        working-directory: pr-checkout
-        run: |
-          set -euo pipefail
-          patch="../autofix-in/autofix.patch"
-
-          # Distinguish artifact-expired (file missing entirely, because
-          # actions/download-artifact ran with continue-on-error and the
-          # 1-day retention had elapsed) from genuinely empty patch
-          # (file present, zero bytes, formatter found nothing).
-          if [ ! -e "$patch" ]; then
-            echo "::warning::Patch file does not exist — autofix artifact likely expired."
-            echo "result=artifact-expired" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          if [ ! -s "$patch" ]; then
-            echo "::warning::Empty patch — nothing to apply."
-            echo "result=empty-patch" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Sensitive-paths guard: refuse to apply patches that touch
-          # `.github/` — workflow files, action definitions, CODEOWNERS,
-          # dependabot config, etc. A malicious PR could ship a custom
-          # prettier/ESLint config that reformats workflow YAML; the
-          # producer would then capture those edits in autofix.patch,
-          # and a maintainer running `/autofix` would push them under
-          # `contents: write`. The default GITHUB_TOKEN lacks `workflows`
-          # scope so the platform would reject workflow-file pushes
-          # anyway, but that surfaces as a generic `push-failed` and
-          # misleads users into enabling maintainer-edit. Reject early
-          # with a specific reason. CODEOWNERS and dependabot.yml live
-          # under .github/ but outside .github/workflows/ — the broader
-          # match is intentional (they all govern trust boundaries).
-          if grep -qE '^(diff --git|---|\+\+\+) [ab]?/?\.github/' "$patch"; then
-            echo "::warning::Patch touches .github/ — refusing to apply (sensitive paths)."
-            echo "result=sensitive-paths" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Re-entrancy guard: if HEAD itself is an autofix bot commit,
-          # refuse to apply again. Without this, lint/formatter config
-          # drift between runs could pump arbitrary apply commits into
-          # the same PR if an automated agent watches the sticky and
-          # re-fires `/autofix` on each new "fixes-available" surface.
-          # The contributor can still get out by force-pushing a
-          # human-authored commit to revert the autofix and re-trigger.
-          head_author=$(git log -1 --format='%ae' HEAD)
-          head_subject=$(git log -1 --format='%s' HEAD)
-          if [ "${head_author}" = "41898282+github-actions[bot]@users.noreply.github.com" ] \
-             && [[ "${head_subject}" =~ ^chore\(autofix\) ]]; then
-            echo "::warning::HEAD is an autofix bot commit — refusing to re-apply (loop guard)."
-            echo "result=loop-prevented" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Idempotency probe: does the forward apply work?
-          if git apply --check "$patch" 2>/dev/null; then
-            echo "Patch applies cleanly — proceeding."
-          elif git apply --check --reverse "$patch" 2>/dev/null; then
-            # Reverse-check passes => the patch is already applied to
-            # the current tree. Treat as success no-op.
-            echo "Patch is already applied (reverse-check passed) — no-op."
-            echo "result=already-applied" >> "$GITHUB_OUTPUT"
-            exit 0
-          else
-            echo "::error::Patch does not apply (stale or conflicting)."
-            echo "result=stale" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Wrap the apply/commit phase so any non-zero exit sets a
-          # meaningful `result=` instead of leaving it unset (which would
-          # send the user to the `*` "unexpected state" arm with a
-          # non-actionable confused-emoji reply).
-          if ! {
-            git config user.email "41898282+github-actions[bot]@users.noreply.github.com" &&
-            git config user.name  "github-actions[bot]" &&
-            git apply "$patch" &&
-            git add -A &&
-            git commit -m "chore(autofix): apply prettier + eslint fixes via /autofix command"
-          }; then
-            echo "::error::git apply / config / commit failed after idempotency probe passed."
-            echo "result=apply-failed" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Push to the PR head branch with a lease against the resolved
-          # SHA. The lease ensures the remote ref still points at HEAD_SHA
-          # when the push lands — if the contributor force-pushed in the
-          # window between resolve and now, the lease fails and we return
-          # `lease-failed` (NOT `push-failed`, which would mislead users
-          # into enabling maintainer-edit). For fork PRs, the push still
-          # requires "Allow edits by maintainers" to be enabled.
-          #
-          # Auth is supplied inline via `-c http.<base>.extraheader` (NOT
-          # via a `https://x-access-token:TOKEN@…` URL — those leak into
-          # process listings and `git remote -v` output). The header is
-          # set per-invocation; it never lands in `.git/config` on disk.
-          # The token is base64-encoded for the Basic auth header per
-          # GitHub's documented pattern for this scope.
-          push_url="https://github.com/${HEAD_REPO}.git"
-          auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${GITHUB_TOKEN}" | base64 -w0)"
-          # GitHub's secret-masker only masks the raw token, not its
-          # base64-encoded form. Mask the encoded value so any subsequent
-          # log line (set -x, GIT_TRACE, error spew) gets ***-redacted.
-          echo "::add-mask::${auth_header}"
-          push_stderr=$(mktemp)
-          if git -c http.extraheader="${auth_header}" \
-                push --force-with-lease="refs/heads/${HEAD_REF}:${HEAD_SHA}" \
-                "${push_url}" "HEAD:${HEAD_REF}" 2>"$push_stderr"; then
-            echo "result=applied" >> "$GITHUB_OUTPUT"
-          else
-            cat "$push_stderr" >&2
-            # `--force-with-lease` reports "stale info" when the remote
-            # ref has moved past the expected SHA. Other lease-failure
-            # phrases git emits include "remote rejected" (server-side
-            # reject), "non-fast-forward", and the literal flag name. Match
-            # any of those to distinguish from auth/network/maintainer-
-            # edit failures.
-            if grep -qE "stale info|force-with-lease|rejected.*non-fast-forward|remote rejected|! \[rejected\]" "$push_stderr"; then
-              echo "::error::git push lease failed — branch moved during apply."
-              echo "result=lease-failed" >> "$GITHUB_OUTPUT"
-            else
-              echo "::error::git push failed — likely fork without maintainer-edit enabled."
-              echo "result=push-failed" >> "$GITHUB_OUTPUT"
-            fi
-            exit 0
-          fi
-
-      - name: React and reply on outcome
-        if: always() && steps.locate.outputs.found == 'true' && steps.apply.outcome != 'skipped'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          COMMENT_ID: ${{ github.event.comment.id }}
-          PR: ${{ github.event.issue.number }}
-          RESULT: ${{ steps.apply.outputs.result }}
-          RUN_ID: ${{ github.run_id }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          run_url="https://github.com/${GH_REPO}/actions/runs/${RUN_ID}"
-
-          case "${RESULT}" in
-            applied)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="+1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="✅ Applied autofix and pushed a commit. ([apply run](${run_url}))" \
-                >/dev/null
-              ;;
-            already-applied)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="+1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="✅ Autofix is already applied — no changes needed." \
-                >/dev/null
-              ;;
-            empty-patch)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="+1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="✅ No autofix to apply — formatter found nothing." \
-                >/dev/null
-              ;;
-            artifact-expired)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="confused" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="⏳ The autofix artifact for this PR's head SHA has expired (1-day retention). Push a new commit to regenerate it, then comment \`/autofix\` again. ([apply run](${run_url}))" \
-                >/dev/null
-              exit 1
-              ;;
-            loop-prevented)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="confused" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="🔁 Refusing to re-apply autofix on top of an existing autofix commit. If formatter rules drifted and you genuinely need another pass, push a human-authored commit (or revert the existing autofix commit) before commenting \`/autofix\` again. ([apply run](${run_url}))" \
-                >/dev/null
-              exit 1
-              ;;
-            sensitive-paths)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="-1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="🛑 Refusing to apply: the autofix patch touches files under \`.github/\` (workflow / CODEOWNERS / dependabot config). Apply formatter changes to those files manually in a regular commit so they get human review. ([apply run](${run_url}))" \
-                >/dev/null
-              exit 1
-              ;;
-            stale)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="-1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="⚠️ The autofix patch is stale or conflicts with the current head — push a new commit to regenerate, then comment \`/autofix\` again. ([apply run](${run_url}))" \
-                >/dev/null
-              exit 1
-              ;;
-            apply-failed)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="-1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="⚠️ Autofix applied cleanly in the dry run, but \`git apply\` / \`git commit\` failed when actually landing the patch. This usually means a race with concurrent edits or a corrupt patch. See logs: ${run_url}" \
-                >/dev/null
-              exit 1
-              ;;
-            push-failed)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="-1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="⚠️ Couldn't push the autofix commit. If this is a fork PR, please tick **Allow edits by maintainers** in the PR sidebar, then comment \`/autofix\` again. ([apply run](${run_url}))" \
-                >/dev/null
-              exit 1
-              ;;
-            lease-failed)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="-1" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="⚠️ The PR head moved while autofix was applying — a new commit landed in the window between resolve and push. Comment \`/autofix\` again to retry against the latest head. ([apply run](${run_url}))" \
-                >/dev/null
-              exit 1
-              ;;
-            *)
-              gh api -X POST "repos/${GH_REPO}/issues/comments/${COMMENT_ID}/reactions" \
-                -f content="confused" >/dev/null
-              gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-                -f body="❓ Autofix run finished in an unexpected state (\`${RESULT:-unknown}\`). See logs: ${run_url}" \
-                >/dev/null
-              exit 1
-              ;;
-          esac

.github/workflows/pr-autofix-publish.yml

@@ -1,316 +0,0 @@
-name: PR Autofix (publish)
-
-# TRUSTED HALF of the autofix pipeline.
-#
-# Triggered by `pr-autofix.yml` completing on a PR (including fork PRs).
-# Downloads the diff artifact produced by the untrusted job, verifies
-# its claimed PR identity against the workflow_run authority, then
-# posts (or edits) a single sticky summary comment plus a
-# `gitnexus/autofix` Check Run. This job NEVER checks out fork code —
-# it only consumes the diff (data) and calls the GitHub API. That
-# isolation is what makes it safe to run under `pull-requests: write`
-# on fork-triggered events.
-#
-# The sticky comment is the contributor signal: heading
-# "## :sparkles: PR Autofix" in the PR's top-level comments, with a
-# fenced `gitnexus-autofix` JSON block carrying machine-readable state
-# for AI agents. Contributors apply the patch by commenting `/autofix`
-# on the PR — handled by the separate `pr-autofix-apply.yml` workflow.
-
-on:
-  workflow_run:
-    workflows: ['PR Autofix']
-    types: [completed]
-
-concurrency:
-  # Key on PR identity, NOT workflow_run.id — workflow_run.id is per-run
-  # unique, which would defeat serialization and let two parallel
-  # publishes both POST a sticky summary comment. CONTRIBUTING.md
-  # § GitHub Actions — Concurrency Convention names this anti-pattern
-  # explicitly. For fork PRs, `pull_requests[]` is empty in the
-  # workflow_run payload, so we fall back to head-repo + head-branch.
-  group: ${{ github.workflow }}-${{ github.event.workflow_run.pull_requests[0].number || format('{0}/{1}', github.event.workflow_run.head_repository.full_name, github.event.workflow_run.head_branch) }}
-  cancel-in-progress: false
-
-permissions: {}
-
-jobs:
-  publish:
-    name: publish-autofix
-    if: >-
-      github.event.workflow_run.event == 'pull_request'
-      && github.event.workflow_run.conclusion == 'success'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      pull-requests: write
-      # Required by actions/download-artifact to fetch artifacts produced
-      # by a different workflow run.
-      actions: read
-      # Required to create the `gitnexus/autofix` Check Run that reports
-      # the outcome (clean / fixes-available) to the PR's Checks tab.
-      # Branch protection or agents can grep the conclusion + output
-      # title without parsing the sticky comment.
-      checks: write
-    steps:
-      # Pinned to v8.0.1. Verify SHA via:
-      #   gh api repos/actions/download-artifact/git/refs/tags/v8.0.1
-      - name: Download autofix artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          name: autofix
-          run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          path: autofix-in
-
-      - name: Read and validate metadata
-        id: meta
-        shell: bash
-        run: |
-          set -euo pipefail
-          test -f autofix-in/metadata.json
-          jq . autofix-in/metadata.json
-
-          # The artifact comes from the untrusted half running fork code.
-          # Every field is allowlist-validated before it can flow into
-          # $GITHUB_OUTPUT. A newline in head_ref would otherwise let a
-          # malicious branch name inject a second `pr_number=N` line and
-          # redirect this job's reviewdog suggestions / sticky summary
-          # comment onto a victim PR under github-actions[bot] with
-          # pull-requests: write.
-          assert_field() {
-            local key="$1" pattern="$2" value
-            value=$(jq -r ".${key} // empty" autofix-in/metadata.json)
-            if [ -z "$value" ] || ! [[ "$value" =~ $pattern ]]; then
-              echo "::error::metadata.${key} failed allowlist (got: $(printf '%q' "$value"))"
-              exit 1
-            fi
-            printf '%s' "$value"
-          }
-
-          SCHEMA=$(assert_field    schema         '^gitnexus\.pr-autofix/v[0-9]+$')
-          PR_NUMBER=$(assert_field pr_number      '^[0-9]+$')
-          HEAD_SHA=$(assert_field  head_sha       '^[0-9a-f]{40}$')
-          HEAD_REF=$(assert_field  head_ref       '^[A-Za-z0-9._/-]+$')
-          HEAD_REPO=$(assert_field head_repo      '^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$')
-          BASE_REPO=$(assert_field base_repo      '^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$')
-          CHANGED=$(assert_field   changed_lines  '^[0-9]+$')
-
-          # Defence-in-depth: refuse to act if the artifact claims to
-          # belong to a different repo than the one that triggered us.
-          if [ "$BASE_REPO" != "${GITHUB_REPOSITORY}" ]; then
-            echo "::error::Artifact base_repo does not match \$GITHUB_REPOSITORY — refusing to publish."
-            exit 1
-          fi
-
-          {
-            echo "schema=${SCHEMA}"
-            echo "pr_number=${PR_NUMBER}"
-            echo "head_sha=${HEAD_SHA}"
-            echo "head_ref=${HEAD_REF}"
-            echo "head_repo=${HEAD_REPO}"
-            echo "base_repo=${BASE_REPO}"
-            echo "changed_lines=${CHANGED}"
-          } >> "$GITHUB_OUTPUT"
-
-      # Cross-verify the artifact's claimed identity against the
-      # GitHub-controlled workflow_run event. The previous step's
-      # allowlist only proves the fields are well-formed — not that
-      # they refer to the PR/SHA that actually triggered this run.
-      # A fork-controlled `npm run lint:fix` could plausibly mutate
-      # metadata.json to reference another PR or SHA, redirecting our
-      # write-scoped sticky/check-run onto an attacker-chosen target.
-      #
-      # Authority sources are all server-controlled GitHub event fields:
-      #   - workflow_run.head_sha
-      #   - workflow_run.head_repository.full_name
-      #   - workflow_run.pull_requests[].number  (within-repo PRs only;
-      #     empty array on fork PRs — fall back to commits/{sha}/pulls)
-      #
-      # Mismatch => fail loud BEFORE any sticky/check-run side effect.
-      - name: Verify metadata against workflow_run authority
-        id: verify
-        if: steps.meta.outputs.changed_lines != '0'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          META_PR_NUMBER: ${{ steps.meta.outputs.pr_number }}
-          META_HEAD_SHA: ${{ steps.meta.outputs.head_sha }}
-          META_HEAD_REPO: ${{ steps.meta.outputs.head_repo }}
-          WF_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
-          WF_HEAD_REPO: ${{ github.event.workflow_run.head_repository.full_name }}
-          WF_PR_NUMBERS: ${{ toJSON(github.event.workflow_run.pull_requests.*.number) }}
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          # 1) head_sha must match exactly. workflow_run.head_sha is the
-          # commit GitHub actually ran the producer against — definitive.
-          if [ "${META_HEAD_SHA}" != "${WF_HEAD_SHA}" ]; then
-            echo "::error::Artifact head_sha (${META_HEAD_SHA}) does not match workflow_run.head_sha (${WF_HEAD_SHA}) — refusing to publish."
-            exit 1
-          fi
-
-          # 2) head_repo must match exactly. Same authority anchor.
-          if [ "${META_HEAD_REPO}" != "${WF_HEAD_REPO}" ]; then
-            echo "::error::Artifact head_repo (${META_HEAD_REPO}) does not match workflow_run.head_repository (${WF_HEAD_REPO}) — refusing to publish."
-            exit 1
-          fi
-
-          # 3) pr_number must reference an open PR with this head SHA.
-          # Within-repo PRs: workflow_run.pull_requests[] is populated.
-          # Fork PRs: that array is empty by GitHub design — fall back
-          # to the REST commit-to-PRs lookup. Fail closed if the lookup
-          # finds no matching open PR (avoids attacker-forged PR ids).
-          allowed_numbers=$(jq -c '.' <<< "${WF_PR_NUMBERS}")
-          if [ "${allowed_numbers}" = "[]" ]; then
-            echo "workflow_run.pull_requests is empty (fork PR) — falling back to commits/{sha}/pulls."
-            allowed_numbers=$(gh api "repos/${GH_REPO}/commits/${WF_HEAD_SHA}/pulls" \
-              --jq '[.[] | select(.state == "open") | .number]' 2>/dev/null || echo "[]")
-            if [ "${allowed_numbers}" = "[]" ]; then
-              echo "::error::No open PR found for head ${WF_HEAD_SHA} via commits/{sha}/pulls — refusing to publish."
-              exit 1
-            fi
-          fi
-
-          if ! jq -e --argjson n "${META_PR_NUMBER}" 'index($n) != null' <<< "${allowed_numbers}" >/dev/null; then
-            echo "::error::Artifact pr_number (${META_PR_NUMBER}) is not in the authoritative PR list (${allowed_numbers}) — refusing to publish."
-            exit 1
-          fi
-
-          echo "Verified: metadata identity matches workflow_run authority (PR=${META_PR_NUMBER}, head_sha=${META_HEAD_SHA}, head_repo=${META_HEAD_REPO})."
-
-      - name: Upsert sticky summary comment
-        # Only post when ci-quality found something fixable (= the
-        # autofix patch is non-empty). When prettier/eslint are clean
-        # the patch is zero bytes and the sticky comment is pure noise,
-        # so we skip it.
-        if: >-
-          always()
-          && steps.meta.outputs.pr_number != ''
-          && steps.meta.outputs.changed_lines != '0'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          PR: ${{ steps.meta.outputs.pr_number }}
-          CHANGED: ${{ steps.meta.outputs.changed_lines }}
-          HEAD_SHA: ${{ steps.meta.outputs.head_sha }}
-          RUN_ID: ${{ github.run_id }}
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          # Stable heading + marker — agents grep for these exact strings.
-          marker="<!-- gitnexus:pr-autofix-summary -->"
-          heading="## :sparkles: PR Autofix"
-
-          # Single state. The /autofix slash command works for any diff
-          # size — there's no 3K cap and no no-overlap dead-end because
-          # the apply workflow uses `git apply` + push, not the GitHub
-          # review-comment API.
-          ui_state="fixes-available"
-          prose="Found fixable formatting / unused-import issues across **${CHANGED}** changed lines. **Comment \`/autofix\` on this PR to apply them**, or run \`npm run lint:fix && npm run format\` locally."
-
-          # Machine-readable JSON block — agents parse this instead of
-          # regexing English. Fenced code-block info string is
-          # `gitnexus-autofix` so agents can locate it without ambiguity.
-          # Schema bumped from v1 -> v2: adds `apply_command`. The v1
-          # field set is preserved as a superset, but the `state` enum
-          # is redefined (v1: suggestions-posted | skipped-too-large |
-          # diff-no-overlap; v2: fixes-available). v1 readers checking
-          # `schema == 'gitnexus.pr-autofix/v1'` see an unfamiliar version
-          # and fall back to prose, which is the intended migration path.
-          json=$(jq -n -c \
-            --arg state        "${ui_state}" \
-            --argjson pr_number "${PR}" \
-            --argjson changed_lines "${CHANGED}" \
-            --arg head_sha     "${HEAD_SHA}" \
-            --arg run_id       "${RUN_ID}" \
-            '{schema:"gitnexus.pr-autofix/v2", state:$state, pr_number:$pr_number, changed_lines:$changed_lines, head_sha:$head_sha, run_id:$run_id, apply_command:"/autofix"}')
-
-          # Multi-line quoted string instead of a column-0 heredoc — YAML's
-          # `run: |` block ends as soon as a content line dedents below the
-          # block's first-line indent, which would mis-parse the workflow.
-          body="${marker}
-          ${heading}
-
-          ${prose}
-
-          \`\`\`gitnexus-autofix
-          ${json}
-          \`\`\`"
-          # Strip the leading 10-space indent that the YAML block requires
-          # so the rendered comment body starts at column 0.
-          body="$(printf '%s\n' "$body" | sed 's/^          //')"
-
-          # Small retry wrapper for transient 5xx / rate-limit responses
-          # on the GitHub REST API. Three tries with linear backoff. We
-          # only retry GET (idempotent) and PATCH on a known comment id
-          # (idempotent). POST is NOT wrapped — retrying a comment-create
-          # would create duplicates if the first attempt actually landed.
-          gh_retry() {
-            local n=0 max=3
-            while true; do
-              if gh "$@"; then return 0; fi
-              n=$((n+1))
-              if [ "$n" -ge "$max" ]; then return 1; fi
-              sleep $((n * 2))
-            done
-          }
-
-          # Find existing bot comment by the marker and edit-in-place; else create.
-          # CRITICAL: filter by `.user.login == "github-actions[bot]"`. A regular
-          # user posting a comment containing the marker would otherwise be the
-          # `head -n1` match; PATCH on someone else's comment 403s, `set -e`
-          # aborts, and the bot is permanently DoS'd for that PR.
-          existing=$(gh_retry api "repos/${GH_REPO}/issues/${PR}/comments" \
-            --paginate --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | contains(\"${marker}\"))) | .id" \
-            | head -n1 || true)
-
-          if [ -n "${existing}" ]; then
-            gh_retry api -X PATCH "repos/${GH_REPO}/issues/comments/${existing}" \
-              -f body="${body}" >/dev/null
-            echo "Updated comment ${existing}."
-          else
-            gh api -X POST "repos/${GH_REPO}/issues/${PR}/comments" \
-              -f body="${body}" >/dev/null
-            echo "Created summary comment."
-          fi
-
-      - name: Emit gitnexus/autofix Check Run
-        # Stable check name `gitnexus/autofix` so PR-watching agents can
-        # `gh pr checks <pr>` and read the conclusion + title without
-        # parsing the sticky comment. Two outcomes:
-        #   clean            → conclusion: success
-        #   fixes-available  → conclusion: neutral
-        # `neutral` does not block branch-protection required-checks but
-        # is visually distinct from a green pass.
-        if: always() && steps.meta.outputs.head_sha != ''
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GH_REPO: ${{ github.repository }}
-          HEAD_SHA: ${{ steps.meta.outputs.head_sha }}
-          CHANGED: ${{ steps.meta.outputs.changed_lines }}
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          if [ "${CHANGED}" = "0" ]; then
-            conclusion="success"
-            title="Formatting clean"
-            summary="Prettier and ESLint --fix produced no changes."
-          else
-            conclusion="neutral"
-            title="Autofix available — comment /autofix to apply"
-            summary="Comment \`/autofix\` on this PR to apply formatter + unused-import fixes (works at any diff size). Or run \`npm run lint:fix && npm run format\` locally."
-          fi
-
-          gh api -X POST "repos/${GH_REPO}/check-runs" \
-            -f name="gitnexus/autofix" \
-            -f head_sha="${HEAD_SHA}" \
-            -f status="completed" \
-            -f conclusion="${conclusion}" \
-            -f "output[title]=${title}" \
-            -f "output[summary]=${summary}" \
-            >/dev/null
-          echo "Posted check-run gitnexus/autofix=${conclusion} (${title})"

.github/workflows/pr-autofix.yml

@@ -1,146 +0,0 @@
-name: PR Autofix
-
-# UNTRUSTED HALF of the autofix pipeline.
-#
-# Runs `npm run lint:fix` + `npm run format` against the PR head
-# (including fork heads) and uploads the resulting diff as an artifact.
-# This job has NO privileged token and CANNOT post to the PR. The trusted
-# `pr-autofix-publish.yml` workflow downloads the artifact via
-# `workflow_run` and posts a sticky summary comment + Check Run.
-# Contributors apply the patch by commenting `/autofix` on the PR —
-# handled by the separate `pr-autofix-apply.yml` ChatOps workflow.
-#
-# Why the split:
-#   ESLint loads plugins from fork-controlled `node_modules`, so running
-#   it in a job with `pull-requests: write` would let a malicious fork PR
-#   ship a poisoned eslint plugin and execute arbitrary code under that
-#   token. By keeping fork code execution in this job (token: read-only)
-#   and posting from a separate trusted job that never touches fork
-#   code, we get the autofix UX for fork PRs without the supply-chain
-#   hole. (See autofix.ci for the same pattern.)
-#
-# Removes unused imports via `eslint-plugin-unused-imports`, already in
-# devDependencies and wired into the `lint` config.
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-    # Skip lockfile / generated-file PRs entirely — `action-suggester`
-    # cannot post on diffs > ~3k lines (GitHub returns 406) and these
-    # paths produce massive diffs no human wants suggested back inline.
-    paths-ignore:
-      - '**/package-lock.json'
-      - '**/*.snap'
-      - '**/dist/**'
-      - '**/node_modules/**'
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
-  # Don't cancel in-flight runs; the publish workflow may already be
-  # downloading the artifact and a cancelled untrusted run produces no
-  # signal at all (worse DX than waiting).
-  cancel-in-progress: false
-
-# This workflow runs untrusted fork code. Top-level deny-all and NO
-# job-level grants — the job can only read its own checkout.
-permissions: {}
-
-jobs:
-  autofix:
-    name: autofix
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          # PR head commit (not the synthetic merge ref) — we need the
-          # exact tree the contributor pushed so suggestions line up.
-          ref: ${{ github.event.pull_request.head.sha }}
-          repository: ${{ github.event.pull_request.head.repo.full_name }}
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-          cache: npm
-          cache-dependency-path: package-lock.json
-
-      # `--ignore-scripts` blocks pre/postinstall lifecycle hooks. ESLint
-      # plugins still load from node_modules (that is the actual escape
-      # hatch on a typical fork), but this job has no token to abuse —
-      # which is the whole point of the split.
-      - run: npm ci --ignore-scripts
-
-      - name: ESLint --fix (removes unused imports)
-        run: npm run lint:fix
-        # Lint errors that --fix can't auto-resolve must not block the
-        # diff artifact — partial fixes are still useful as suggestions.
-        continue-on-error: true
-
-      - name: Prettier --write
-        run: npm run format
-        continue-on-error: true
-
-      - name: Capture diff and metadata
-        id: capture
-        # Pass GitHub-context values via env: rather than `${{ }}`
-        # interpolated directly into the bash body. `head.ref` and
-        # `head.repo.full_name` are fork-controlled strings; expanding
-        # them into shell source is the canonical template-injection
-        # vector zizmor flags. Even though this job has `permissions: {}`,
-        # routing through env: makes it impossible for a future scope
-        # grant to turn into RCE. Inside bash, reference as `$HEAD_REF`
-        # etc. — the values are then plain strings, not code.
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          HEAD_REF: ${{ github.event.pull_request.head.ref }}
-          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
-          BASE_REPO: ${{ github.repository }}
-        shell: bash
-        run: |
-          set -euo pipefail
-          mkdir -p autofix-out
-
-          # Produce a unified diff of the working tree vs. the PR head.
-          # Empty diff => nothing to suggest; the publish job short-circuits.
-          git diff --no-color > autofix-out/autofix.patch
-
-          # NOTE: `changed_lines` is the line-count of the patch file,
-          # (hunk headers + context lines + added/removed). Surfaced in
-          # the sticky comment so contributors and AI agents have a
-          # quick size hint before invoking `/autofix`.
-          changed_lines=$(wc -l < autofix-out/autofix.patch | tr -d ' ')
-          echo "changed_lines=${changed_lines}" >> "$GITHUB_OUTPUT"
-
-          # Carry PR identity over to the trusted job. workflow_run
-          # context is base-repo-only, so the publish job needs these
-          # to call the GitHub PR API on the right resource.
-          # CONTRACT: keep this schema in sync with pr-autofix-publish.yml's
-          # `assert_field` validators and the agent-facing JSON block in
-          # the sticky comment. Bump `schema` when changing field names.
-          jq -n \
-            --arg     schema        'gitnexus.pr-autofix/v1' \
-            --argjson pr_number     "${PR_NUMBER}" \
-            --arg     head_sha      "${HEAD_SHA}" \
-            --arg     head_ref      "${HEAD_REF}" \
-            --arg     head_repo     "${HEAD_REPO}" \
-            --arg     base_repo     "${BASE_REPO}" \
-            --argjson changed_lines "${changed_lines}" \
-            '{schema:$schema, pr_number:$pr_number, head_sha:$head_sha, head_ref:$head_ref, head_repo:$head_repo, base_repo:$base_repo, changed_lines:$changed_lines}' \
-            > autofix-out/metadata.json
-
-          echo "--- metadata ---"
-          cat autofix-out/metadata.json
-          echo "--- diff (head) ---"
-          head -c 2000 autofix-out/autofix.patch || true
-
-      # Pinned to v7.0.1. Verify SHA via:
-      #   gh api repos/actions/upload-artifact/git/refs/tags/v7.0.1
-      - name: Upload autofix artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: autofix
-          path: autofix-out/
-          retention-days: 1
-          if-no-files-found: error

.github/workflows/pr-description-check.yml

@@ -8,9 +8,8 @@ on:
 permissions:
   pull-requests: write
 
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  group: pr-desc-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
@@ -19,7 +18,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Check PR description quality
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: |
             const MIN_BODY_LENGTH = 50;

.github/workflows/pr-labeler.yml

@@ -1,116 +0,0 @@
-name: PR Conventional Labeler
-
-# Two workflows in one file with different triggers, matched to the minimum
-# privilege each needs:
-#
-#   validate-title (on: pull_request)
-#     Fork-safe. Runs with the PR-head's read-only GITHUB_TOKEN. Uses
-#     `amannn/action-semantic-pull-request` to fail the check when the PR
-#     title doesn't follow the conventional-commit format. Because the
-#     action only reads the event payload, no fork-controlled code runs.
-#
-#   autolabel (on: pull_request_target)
-#     Needs `pull-requests: write` to apply labels, so must be
-#     pull_request_target. Uses `release-drafter/release-drafter` with
-#     `dry-run: true` to only run the autolabeler against the
-#     `.github/release-drafter.yml` config from the BASE ref (release-
-#     drafter reads the config from the repository's default branch, NOT
-#     the PR head — verify with `gh api repos/release-drafter/release-drafter/contents/...`
-#     or a fork-test PR before merging if the repo is high-value).
-#     `sync-labels: true` in the config removes managed autolabels that no
-#     longer match (e.g. when `!` or `BREAKING CHANGE:` is dropped).
-#
-# Title format: <type>[(scope)][!]: <subject>
-#   Allowed types: feat, fix, perf, refactor, docs, test, ci, build, chore, revert, deps
-#   Trailing `!` on the type marks a breaking change.
-# See CONTRIBUTING.md → "Pull request titles".
-
-on:
-  pull_request:
-    # Title-only changes fire `edited`. `opened` and `reopened` cover creation.
-    # `synchronize` (push to the PR branch) is intentionally excluded — titles
-    # don't change on push, so it only wastes CI minutes and broadens the
-    # privileged-token exposure window on the autolabel job.
-    types: [opened, edited, reopened]
-  pull_request_target:
-    types: [opened, edited, reopened]
-
-permissions:
-  contents: read
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Include `github.event_name` so `pull_request` (validate-title) and
-# `pull_request_target` (autolabel) runs for the same PR do NOT share a slot
-# and therefore cannot cancel each other — a cancelled required-check would
-# permanently block merge until the next title edit.
-# Within each trigger the latest title edit still supersedes the prior run.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
-jobs:
-  validate-title:
-    # Fork-safe job — only runs on `pull_request` (not `pull_request_target`).
-    # Token is read-only; writes a commit status that branch protection can
-    # require before merge.
-    name: Validate PR title
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      pull-requests: read
-    steps:
-      # Pinned to v6.1.1. Verify SHA via:
-      #   gh api repos/amannn/action-semantic-pull-request/git/refs/tags/v6.1.1
-      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          types: |
-            feat
-            fix
-            perf
-            refactor
-            docs
-            test
-            ci
-            build
-            chore
-            revert
-            deps
-          requireScope: false
-          # Subject must be non-empty. We DO allow capitalized proper nouns
-          # (MCP, GitHub, API, etc.) — the old `^(?![A-Z]).+$` pattern
-          # rejected legitimate titles like `fix: MCP tool schema`.
-          subjectPattern: ^\S.{2,}$
-          subjectPatternError: |
-            The subject "{subject}" in PR title "{title}" is invalid.
-            Subjects must be at least 3 characters and must not start with whitespace.
-          wip: false
-
-  autolabel:
-    # Privileged job — runs only on `pull_request_target` so it can write labels.
-    # Never checks out fork code, never executes fork-controlled input; only
-    # reads the PR metadata (title, body, labels) and calls the GitHub API.
-    name: Apply conventional label
-    if: github.event_name == 'pull_request_target'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      # `contents: read` is required — release-drafter's context.config() reads
-      # `.github/release-drafter.yml` from the repo's default branch via the
-      # repo-contents API. Without it the job silently 403s and no labels are
-      # applied. Job-level permissions nullify all unlisted scopes, so an
-      # explicit grant is necessary here.
-      contents: read
-      pull-requests: write
-    steps:
-      # Pinned to v7.2.0. Verify SHA via:
-      #   gh api repos/release-drafter/release-drafter/git/refs/tags/v7.2.0
-      # v7 removed `disable-releaser`; use `dry-run: true` to only autolabel.
-      - uses: release-drafter/release-drafter@563bf132657a13ded0b01fcb723c5a58cdd824e2 # v7.2.1
-        with:
-          config-name: release-drafter.yml
-          dry-run: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish.yml

@@ -6,14 +6,6 @@ on:
       - 'v*'
 
 # No workflow-level permissions — scoped per job below.
-permissions: {}
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Tag refs are unique per release, so distinct tags run in parallel. Re-pushes of the
-# same tag serialize. cancel-in-progress: false — never cancel a publish mid-flight.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: false
 
 jobs:
   ci:
@@ -21,9 +13,7 @@ jobs:
     permissions:
       contents: read
       actions: read
-      # No pull-requests:write — `ci.yml`'s save-pr-meta job is gated on
-      # `github.event_name == 'pull_request'`, so it never runs during a
-      # tag-triggered publish. Least-privilege for release-critical paths.
+      pull-requests: write
 
   publish:
     needs: ci
@@ -33,17 +23,13 @@ jobs:
       contents: write
       id-token: write
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: 22
+          node-version: 20
           registry-url: https://registry.npmjs.org
-          # Hermetic install for the published artifact — no cache carry-over
-          # from non-tag contexts. setup-node v5+ caches by default when a
-          # packageManager field is present in package.json, so the explicit
-          # opt-out is required to clear the zizmor cache-poisoning audit.
-          # ~30s slower per release; runs rarely.
-          package-manager-cache: false
+          cache: npm
+          cache-dependency-path: gitnexus/package-lock.json
       - name: Build gitnexus-shared
         run: npm install && npm run build
         working-directory: gitnexus-shared
@@ -96,7 +82,7 @@ jobs:
           fi
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
         with:
           body_path: ${{ steps.changelog.outputs.fallback == 'false' && '/tmp/release-notes.md' || '' }}
           generate_release_notes: ${{ steps.changelog.outputs.fallback == 'true' }}

.github/workflows/release-candidate.yml

@@ -1,459 +0,0 @@
-name: Release Candidate
-
-on:
-  # Publish a release-candidate build whenever a merge/commit lands on main.
-  # Docs/README-only changes are filtered out so prose updates don't
-  # cut a release.
-  push:
-    branches: [main]
-    paths-ignore:
-      - '**.md'
-      - 'docs/**'
-      - 'LICENSE'
-  workflow_dispatch:
-    inputs:
-      bump:
-        description: >-
-          Cycle policy. 'auto' (default) continues the active rc cycle on
-          this branch if there is one, otherwise bumps patch from latest.
-          Choose 'patch' / 'minor' / 'major' to explicitly start or reset
-          an rc cycle.
-        required: false
-        default: 'auto'
-        type: choice
-        options:
-          - auto
-          - patch
-          - minor
-          - major
-      force:
-        description: 'Publish even when HEAD already has an rc marker'
-        required: false
-        default: 'false'
-        type: choice
-        options:
-          - 'false'
-          - 'true'
-
-# No workflow-level permissions — scoped per job below.
-permissions: {}
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Serialize all runs on the same ref (push + workflow_dispatch) to prevent two publishes
-# racing on the rc counter. cancel-in-progress: false — the earlier merge publishes first.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  # ── Skip when HEAD already has an rc marker (retry / duplicate dispatch) ──
-  # The marker is a lightweight tag `rc/<HEAD_SHA>` pushed *before* `npm
-  # publish`, so a failed publish leaves the marker in place and the guard
-  # refuses to re-publish. Recovery path after a partial failure:
-  #   git push --delete origin rc/<HEAD_SHA> v<RC_VERSION>
-  # then redispatch with force=true.
-  guard:
-    name: Check if release candidate should run
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      contents: read
-      pull-requests: read # read PR labels on the merge commit
-    outputs:
-      should_run: ${{ steps.decide.outputs.should_run }}
-      head_sha: ${{ steps.decide.outputs.head_sha }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-
-      - name: Decide
-        id: decide
-        shell: bash
-        env:
-          FORCE: ${{ inputs.force }}
-          BUMP_INPUT: ${{ inputs.bump }}
-          EVENT_NAME: ${{ github.event_name }}
-          GH_TOKEN: ${{ github.token }}
-          REPO: ${{ github.repository }}
-        run: |
-          set -euo pipefail
-          HEAD_SHA=$(git rev-parse HEAD)
-          echo "head_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
-
-          if [ "$FORCE" = "true" ]; then
-            echo "Force flag set — running regardless of marker tag."
-            echo "should_run=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # An explicit cycle reset on dispatch (bump != auto) also bypasses
-          # the dedup guard — the maintainer is deliberately asking for a
-          # new rc from the same commit.
-          if [ "$EVENT_NAME" = "workflow_dispatch" ] \
-             && [ -n "${BUMP_INPUT:-}" ] \
-             && [ "${BUMP_INPUT:-auto}" != "auto" ]; then
-            echo "Explicit bump=$BUMP_INPUT — bypassing marker dedup."
-            echo "should_run=true" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # ── Skip when the merge commit corresponds to a release ─────────
-          # Two complementary checks (belt-and-suspenders):
-          #   1. The HEAD commit subject matches `chore: release vX.Y.Z`
-          #      (the canonical release-PR title in this repo). Anchored
-          #      at both ends to require the bare title or the squash-merge
-          #      `(#NNNN)` suffix exactly — rejects noisy variants like
-          #      `chore: release v1.0.0 (something unrelated)`.
-          #   2. The squash-merged PR carries the `release` label.
-          # Either match suppresses the rc build — stable releases publish
-          # via publish.yml on the v-tag, so the rc cycle should pause for
-          # them rather than racing the npm publish.
-          HEAD_SUBJECT="$(git log -1 --pretty=%s HEAD)"
-          # Sanitise GitHub-Actions annotation prefixes before logging the
-          # raw subject — defence-in-depth so a hypothetical commit subject
-          # containing `::error::` or `::set-output::` cannot forge log
-          # annotations even though %s strips newlines.
-          HEAD_SUBJECT_SAFE="${HEAD_SUBJECT//::/__}"
-          RELEASE_SUBJECT_RE='^chore:[[:space:]]*release[[:space:]]+v[0-9]+\.[0-9]+\.[0-9]+([[:space:]]+\(#[0-9]+\))?$'
-          if [[ "$HEAD_SUBJECT" =~ $RELEASE_SUBJECT_RE ]]; then
-            echo "HEAD commit subject matches a release commit — skipping rc."
-            echo "  subject (sanitised): $HEAD_SUBJECT_SAFE"
-            echo "should_run=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Squash-merge commits include `(#NNNN)` at the end of the subject.
-          if [[ "$HEAD_SUBJECT" =~ \(#([0-9]+)\)[[:space:]]*$ ]]; then
-            PR_NUM="${BASH_REMATCH[1]}"
-            echo "Detected squash-merge of PR #$PR_NUM — checking labels."
-            if LABELS_JSON="$(gh pr view "$PR_NUM" --repo "$REPO" --json labels 2>/dev/null)"; then
-              if printf '%s' "$LABELS_JSON" | jq -e '.labels[] | select(.name == "release")' >/dev/null; then
-                echo "PR #$PR_NUM has the 'release' label — skipping rc."
-                echo "should_run=false" >> "$GITHUB_OUTPUT"
-                exit 0
-              fi
-              echo "PR #$PR_NUM has no 'release' label — proceeding."
-            else
-              # Lookup failure is not fatal — fall through to the dedup check
-              # so a transient GH API hiccup doesn't silently suppress rc builds.
-              echo "::warning::Could not read labels for PR #${PR_NUM} — falling through."
-            fi
-          fi
-
-          # Dedup: is there already an rc/<HEAD_SHA> marker pointing at HEAD?
-          MARKER="rc/${HEAD_SHA}"
-          if git rev-parse "refs/tags/$MARKER" >/dev/null 2>&1; then
-            echo "HEAD already has marker $MARKER — skipping."
-            echo "should_run=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "No marker on HEAD — proceeding."
-            echo "should_run=true" >> "$GITHUB_OUTPUT"
-          fi
-
-  # ── Reuse the stable CI workflow ─────────────────────────────────────
-  ci:
-    needs: guard
-    if: needs.guard.outputs.should_run == 'true'
-    uses: ./.github/workflows/ci.yml
-    permissions:
-      contents: read
-    secrets: inherit
-
-  # ── Publish the rc build to npm + create GitHub prerelease ───────────
-  publish:
-    name: Publish release candidate to npm
-    needs: [guard, ci]
-    if: needs.guard.outputs.should_run == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    permissions:
-      # The default GITHUB_TOKEN cannot be granted `workflows: write`, so
-      # tag pushes that reach a commit which modified `.github/workflows/**`
-      # are rejected with: "refusing to allow a GitHub App to create or
-      # update workflow ... without `workflows` permission". We pass a
-      # fine-grained PAT (RELEASE_PUSH_TOKEN, scoped to this repo with
-      # Contents: write + Workflows: write) to `actions/checkout` so that
-      # the subsequent `git push --atomic` of the v-tag and rc marker
-      # carries the PAT's identity. Job-level GITHUB_TOKEN keeps its
-      # scoped permissions for everything else (npm provenance, etc.).
-      contents: write # push rc tag + marker (via PAT)
-      id-token: write # npm provenance
-    outputs:
-      vtag: ${{ steps.reltag.outputs.vtag }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-          # Use the PAT so `origin` is preauthed for `git push`. Without
-          # this the default GITHUB_TOKEN is wired into the remote, and a
-          # workflows-touching tag push is rejected — see the permissions
-          # block above.
-          token: ${{ secrets.RELEASE_PUSH_TOKEN }}
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org
-          # Hermetic install — release-candidate produces shipped artifacts.
-          # setup-node v5+ caches by default when a packageManager field is
-          # present in package.json; explicit opt-out is required to clear
-          # the zizmor cache-poisoning audit. See cache-poisoning audit.
-          package-manager-cache: false
-
-      - name: Build gitnexus-shared
-        run: npm install && npm run build
-        working-directory: gitnexus-shared
-
-      - name: Install gitnexus dependencies
-        run: npm ci
-        working-directory: gitnexus
-
-      - name: Resolve rc version
-        id: version
-        shell: bash
-        working-directory: gitnexus
-        env:
-          BUMP_INPUT: ${{ inputs.bump }}
-          EVENT_NAME: ${{ github.event_name }}
-          PKG_NAME: gitnexus
-        run: |
-          set -euo pipefail
-
-          # 1. Current published `latest` — the floor for any new rc base.
-          #    Only E404 ("never published") falls back to package.json; any
-          #    other error (network, auth, malformed response) fails fast.
-          NPM_STDERR_LATEST="$(mktemp)"
-          if CURRENT_LATEST="$(npm view "$PKG_NAME" version 2>"$NPM_STDERR_LATEST")"; then
-            :
-          else
-            if grep -q 'E404' "$NPM_STDERR_LATEST"; then
-              CURRENT_LATEST="$(node -p "require('./package.json').version")"
-              echo "Package not on registry (E404) — seeding from package.json: $CURRENT_LATEST"
-            else
-              echo "::error::npm registry unreachable for 'view version':" >&2
-              cat "$NPM_STDERR_LATEST" >&2
-              rm -f "$NPM_STDERR_LATEST"
-              exit 1
-            fi
-          fi
-          rm -f "$NPM_STDERR_LATEST"
-          CURRENT_LATEST_CLEAN="${CURRENT_LATEST%%-*}"
-
-          # 2. Full version list — needed for the counter and for active-cycle
-          #    inference. Same E404-only fallback.
-          NPM_STDERR_VERSIONS="$(mktemp)"
-          if VERSIONS_JSON="$(npm view "$PKG_NAME" versions --json 2>"$NPM_STDERR_VERSIONS")"; then
-            :
-          else
-            if grep -q 'E404' "$NPM_STDERR_VERSIONS"; then
-              VERSIONS_JSON='[]'
-              echo "No published versions for $PKG_NAME yet (E404)."
-            else
-              echo "::error::npm registry unreachable for 'view versions':" >&2
-              cat "$NPM_STDERR_VERSIONS" >&2
-              rm -f "$NPM_STDERR_VERSIONS"
-              exit 1
-            fi
-          fi
-          rm -f "$NPM_STDERR_VERSIONS"
-
-          # 3. Base selection.
-          #    - workflow_dispatch + bump ∈ {patch,minor,major} → explicit cycle
-          #      reset from latest.
-          #    - Everything else (push, or dispatch with bump=auto) → continue
-          #      the highest active rc base > latest if one exists; else
-          #      default to patch from latest.
-          if [ "$EVENT_NAME" = "workflow_dispatch" ] \
-             && [ -n "${BUMP_INPUT:-}" ] \
-             && [ "${BUMP_INPUT:-auto}" != "auto" ]; then
-            BASE="$(npx --yes -p semver@7 semver -i "$BUMP_INPUT" "$CURRENT_LATEST_CLEAN")"
-            echo "Explicit bump=$BUMP_INPUT → BASE=$BASE"
-          else
-            cat > /tmp/active_base.mjs <<'NODESCRIPT'
-          const latest = process.env.LATEST;
-          let v;
-          try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
-          if (!Array.isArray(v)) v = [v];
-          const parse = s => s.split(".").map(n => parseInt(n, 10));
-          const gt = (a, b) => {
-            const [A, B] = [parse(a), parse(b)];
-            for (let i = 0; i < 3; i++) if (A[i] !== B[i]) return A[i] > B[i];
-            return false;
-          };
-          const bases = new Set();
-          for (const s of v) {
-            const m = /^(\d+\.\d+\.\d+)-rc\.\d+$/.exec(s);
-            if (m && gt(m[1], latest)) bases.add(m[1]);
-          }
-          if (!bases.size) { process.stdout.write(""); process.exit(0); }
-          const sorted = [...bases].sort((a, b) => gt(a, b) ? 1 : -1);
-          process.stdout.write(sorted[sorted.length - 1]);
-          NODESCRIPT
-            ACTIVE_BASE="$(LATEST="$CURRENT_LATEST_CLEAN" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/active_base.mjs)"
-            if [ -n "$ACTIVE_BASE" ]; then
-              BASE="$ACTIVE_BASE"
-              echo "Continuing active rc cycle → BASE=$BASE"
-            else
-              BASE="$(npx --yes -p semver@7 semver -i patch "$CURRENT_LATEST_CLEAN")"
-              echo "No active rc cycle → patch bump from latest → BASE=$BASE"
-            fi
-          fi
-
-          # 4. Counter: 1 + max existing N for `${BASE}-rc.*`, else 1.
-          cat > /tmp/next_rc.mjs <<'NODESCRIPT'
-          const base = process.env.BASE;
-          const prefix = base + "-rc.";
-          let v;
-          try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
-          if (!Array.isArray(v)) v = [v];
-          const ns = v
-            .filter(s => typeof s === "string" && s.startsWith(prefix))
-            .map(s => parseInt(s.slice(prefix.length), 10))
-            .filter(n => Number.isInteger(n) && n >= 0);
-          process.stdout.write(String(ns.length ? Math.max(...ns) + 1 : 1));
-          NODESCRIPT
-          NEXT_N="$(BASE="$BASE" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/next_rc.mjs)"
-          RC_VERSION="${BASE}-rc.${NEXT_N}"
-          echo "Computed rc: $RC_VERSION"
-
-          # 5. Defensive: if the exact version already exists on the registry
-          #    (e.g., race with another run), abort before re-publishing.
-          #    Same E404-only pattern used above — a transient network
-          #    failure must fail loudly, not pretend the version is missing.
-          NPM_STDERR_EXISTS="$(mktemp)"
-          if npm view "$PKG_NAME@$RC_VERSION" version 2>"$NPM_STDERR_EXISTS" >/dev/null; then
-            rm -f "$NPM_STDERR_EXISTS"
-            echo "::error::Version $RC_VERSION already exists on npm — aborting."
-            exit 1
-          else
-            if grep -qiE 'E404|not found' "$NPM_STDERR_EXISTS"; then
-              rm -f "$NPM_STDERR_EXISTS"
-              # Version doesn't exist — safe to proceed.
-            else
-              echo "::error::npm registry unreachable for existence check:" >&2
-              cat "$NPM_STDERR_EXISTS" >&2
-              rm -f "$NPM_STDERR_EXISTS"
-              exit 1
-            fi
-          fi
-
-          {
-            echo "base=$BASE"
-            echo "rc_n=$NEXT_N"
-            echo "rc_version=$RC_VERSION"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Apply rc version in-CI
-        shell: bash
-        working-directory: gitnexus
-        run: |
-          set -euo pipefail
-          npm version "${{ steps.version.outputs.rc_version }}" \
-            --no-git-tag-version --allow-same-version
-
-      - name: Build gitnexus
-        run: npm run build
-        working-directory: gitnexus
-
-      - name: Dry-run publish
-        run: npm publish --dry-run --tag rc
-        working-directory: gitnexus
-
-      # ── Acquire the "rc lock" BEFORE publishing (fixes idempotency) ─────
-      # We create two tags and push them atomically:
-      #   v<RC_VERSION>      → annotated tag on a detached release commit
-      #                        whose tree contains the rewritten package.json
-      #                        (so the tag's source matches the npm tarball)
-      #   rc/<HEAD_SHA>      → lightweight tag on HEAD; the guard's dedup key
-      # If this push fails, nothing is published — safe.
-      # If this push succeeds but npm publish fails, the marker stays on
-      # the remote and blocks retries until an operator manually cleans up.
-      - name: Create and push rc tags
-        id: reltag
-        shell: bash
-        working-directory: gitnexus
-        env:
-          RC_VERSION: ${{ steps.version.outputs.rc_version }}
-          HEAD_SHA: ${{ needs.guard.outputs.head_sha }}
-        run: |
-          set -euo pipefail
-          VTAG="v${RC_VERSION}"
-          MARKER="rc/${HEAD_SHA}"
-          git config user.name  'github-actions[bot]'
-          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
-
-          # Detached release commit with the version bump — keeps `main`
-          # pristine but gives the v-tag a tree that matches the published
-          # package contents exactly (fixes release-integrity gap).
-          git add package.json package-lock.json 2>/dev/null || git add package.json
-          git commit -m "release: ${VTAG}" --allow-empty
-          RELEASE_SHA="$(git rev-parse HEAD)"
-          echo "Detached release commit: $RELEASE_SHA"
-
-          # Annotated release tag on the release commit.
-          git tag -a "$VTAG" "$RELEASE_SHA" -m "$VTAG"
-          # Lightweight marker on the user-visible HEAD for the guard.
-          git tag "$MARKER" "$HEAD_SHA"
-
-          # Atomic push of both refs. If either would clobber an existing
-          # remote ref, the push fails and we stop before npm publish.
-          git push --atomic origin "refs/tags/$VTAG" "refs/tags/$MARKER"
-
-          {
-            echo "vtag=$VTAG"
-            echo "marker=$MARKER"
-            echo "release_sha=$RELEASE_SHA"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Publish to npm (rc dist-tag)
-        run: npm publish --provenance --access public --tag rc
-        working-directory: gitnexus
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Create GitHub prerelease
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
-        with:
-          tag_name: ${{ steps.reltag.outputs.vtag }}
-          name: Release Candidate ${{ steps.reltag.outputs.vtag }}
-          prerelease: true
-          make_latest: 'false'
-          generate_release_notes: true
-          body: |
-            Automated release candidate build from `main`.
-
-            **npm:** `npm install gitnexus@rc`
-            **Version:** `${{ steps.version.outputs.rc_version }}`
-            **Target base:** `${{ steps.version.outputs.base }}` (rc #${{ steps.version.outputs.rc_n }})
-            **Source commit (main):** ${{ needs.guard.outputs.head_sha }}
-            **Release commit (versioned tree):** ${{ steps.reltag.outputs.release_sha }}
-
-            Release candidates are pre-stable builds intended for early testing.
-            Stable releases remain on the `latest` dist-tag.
-
-  # ── Build & push RC Docker images ────────────────────────────────────
-  # Calls docker.yml as a reusable workflow so that the build, signing, and
-  # attestation logic stays in one place. The publish job exposes `vtag`
-  # (e.g. `v1.2.3-rc.1`) as an output so we can pass it as the tag input.
-  # RC images are signed with Cosign keyless signing; the OIDC identity
-  # will be `docker.yml@refs/heads/main` (the caller's ref) rather than a
-  # tag ref — see README.md § Docker for the correct verify command for RCs.
-  docker:
-    name: Build & Push RC Docker images
-    needs: [guard, publish]
-    if: needs.guard.outputs.should_run == 'true' && needs.publish.outputs.vtag != ''
-    uses: ./.github/workflows/docker.yml
-    # Reusable workflows do not receive caller secrets unless inherited; without
-    # this, DOCKERHUB_* / GITHUB_TOKEN are empty in docker.yml → "Username and
-    # password required" on Docker Hub login (see same pattern on `ci:` above).
-    secrets: inherit
-    permissions:
-      contents: read
-      packages: write
-      id-token: write
-      attestations: write
-    with:
-      tag: ${{ needs.publish.outputs.vtag }}

.github/workflows/scorecard.yml

@@ -1,58 +0,0 @@
-name: Scorecard
-
-# OpenSSF Scorecard supply-chain posture check. Runs weekly + on main push +
-# branch_protection_rule changes. SARIF uploads to the Security tab; the public
-# badge URL resolves once the first scheduled run lands (see README badge wiring).
-
-on:
-  branch_protection_rule:
-  schedule:
-    - cron: '0 7 * * 1'
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: false
-
-permissions: read-all
-
-jobs:
-  analysis:
-    name: Scorecard analysis
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    permissions:
-      # Needed to upload SARIF results to the Security tab.
-      security-events: write
-      # Needed for the publish_results badge flow (OIDC).
-      id-token: write
-      contents: read
-      actions: read
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Run Scorecard
-        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
-        with:
-          results_file: results.sarif
-          results_format: sarif
-          # publish_results enables the public Scorecard badge.
-          publish_results: true
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: SARIF file
-          path: results.sarif
-          retention-days: 5
-
-      - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
-        with:
-          sarif_file: results.sarif

.github/workflows/tree-sitter-upgrade-readiness.yml

@@ -1,185 +0,0 @@
-name: Tree-sitter Upgrade Readiness
-
-# Monitors readiness for upgrading tree-sitter to 0.25.x. Tracks:
-#   1. Peer-dep compatibility — can each grammar install cleanly with
-#      tree-sitter@0.25.0 without --legacy-peer-deps?
-#   2. Vendored proto drift — has coder3101/tree-sitter-proto moved
-#      ahead of our vendored snapshot?
-# See .github/scripts/check-tree-sitter-upgrade-readiness.py for the logic.
-#
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-
-on:
-  schedule:
-    # Daily at 09:00 UTC. Matches Dependabot's daily cadence so drift
-    # and dep PRs surface together.
-    - cron: '0 9 * * *'
-  workflow_dispatch:
-  pull_request:
-    paths:
-      - '.github/scripts/check-tree-sitter-upgrade-readiness.py'
-      - '.github/workflows/tree-sitter-upgrade-readiness.yml'
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-permissions:
-  contents: read
-
-jobs:
-  readiness:
-    name: Check upgrade readiness
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      contents: read
-      # Needed to open/update the tracking issue on scheduled runs.
-      issues: write
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'false'
-
-      - name: Run upgrade readiness check
-        id: readiness
-        shell: bash
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set +e
-          python3 .github/scripts/check-tree-sitter-upgrade-readiness.py > drift-report.md
-          code=$?
-          set -e
-          echo "exit_code=$code" >> "$GITHUB_OUTPUT"
-          {
-            echo 'report<<DRIFT_EOF'
-            cat drift-report.md
-            echo 'DRIFT_EOF'
-          } >> "$GITHUB_OUTPUT"
-          echo "=== Report ==="
-          cat drift-report.md
-
-      # On PR runs, the script validates that it runs correctly. Blockers
-      # are informational — the scheduled run opens a tracking issue.
-      - name: Annotate PR with readiness status
-        if: github.event_name == 'pull_request' && steps.readiness.outputs.exit_code != '0'
-        run: |
-          echo "::warning::Tree-sitter 0.25 upgrade has blockers. See job output for the full readiness report."
-
-      - name: Upsert tracking issue on scheduled runs
-        if: >
-          github.event_name == 'schedule' &&
-          steps.readiness.outputs.exit_code != '0'
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        env:
-          REPORT: ${{ steps.readiness.outputs.report }}
-        with:
-          script: |
-            const title = 'Tree-sitter 0.25 upgrade readiness';
-            const report = process.env.REPORT;
-            const body = report + '\n\n' +
-              '<sub>Generated daily by `.github/workflows/tree-sitter-upgrade-readiness.yml`. ' +
-              'Closes automatically when all blockers are resolved.</sub>';
-            const { data: open } = await github.rest.issues.listForRepo({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              state: 'open',
-              labels: 'tree-sitter-drift',
-              per_page: 10,
-            });
-            const existing = open.find(i => i.title === title);
-            if (existing) {
-              // Extract ready/total count for the changelog comment.
-              const readyMatch = report.match(/\*\*(\d+)\/(\d+)\*\* grammars ready/);
-              const blockerMatch = report.match(/\*\*(\d+) blocker/);
-              const ready = readyMatch ? readyMatch[1] : '?';
-              const total = readyMatch ? readyMatch[2] : '?';
-              const blockers = blockerMatch ? blockerMatch[1] : '?';
-
-              // Find grammars whose status changed by diffing the old and
-              // new table rows.  Each row looks like:
-              //   | `tree-sitter-foo` | ... | Ready |
-              //   | `tree-sitter-foo` | ... | Blocking |
-              const parseRows = (md) => {
-                const map = {};
-                for (const m of md.matchAll(/\| `(tree-sitter-[^`]+)` \|.*?\| (\S+(?:\s\S+)*?) \|$/gm)) {
-                  map[m[1]] = m[2].trim();
-                }
-                return map;
-              };
-              const oldRows = parseRows(existing.body || '');
-              const newRows = parseRows(report);
-              const changes = [];
-              for (const [name, newStatus] of Object.entries(newRows)) {
-                const oldStatus = oldRows[name];
-                if (oldStatus && oldStatus !== newStatus) {
-                  changes.push(`\`${name}\`: ${oldStatus} → ${newStatus}`);
-                }
-              }
-
-              const today = new Date().toISOString().slice(0, 10);
-              let comment = `**${today}:** ${ready}/${total} ready. ${blockers} blocker(s) remaining.`;
-              if (changes.length > 0) {
-                comment += '\n\nChanges:\n' + changes.map(c => `- ${c}`).join('\n');
-              } else {
-                comment += ' No changes from previous run.';
-              }
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: existing.number,
-                body: comment,
-              });
-
-              await github.rest.issues.update({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: existing.number,
-                body,
-              });
-              core.info(`Updated existing issue #${existing.number}`);
-            } else {
-              const { data: created } = await github.rest.issues.create({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                title,
-                body,
-                labels: ['tree-sitter-drift', 'dependencies'],
-              });
-              core.info(`Opened issue #${created.number}`);
-            }
-
-      - name: Close tracking issue on clean scheduled runs
-        if: >
-          github.event_name == 'schedule' &&
-          steps.readiness.outputs.exit_code == '0'
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        with:
-          script: |
-            const title = 'Tree-sitter 0.25 upgrade readiness';
-            const { data: open } = await github.rest.issues.listForRepo({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              state: 'open',
-              labels: 'tree-sitter-drift',
-              per_page: 10,
-            });
-            const existing = open.find(i => i.title === title);
-            if (existing) {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: existing.number,
-                body: 'All grammars are now compatible with tree-sitter@0.25. Upgrade is ready! Closing automatically.',
-              });
-              await github.rest.issues.update({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: existing.number,
-                state: 'closed',
-              });
-              core.info(`Closed issue #${existing.number}`);
-            }

.github/workflows/triage-sweep.yml

@@ -47,10 +47,8 @@ permissions:
   issues: write
   pull-requests: write
 
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Single global slot — newest manual dispatch supersedes any in-flight run.
 concurrency:
-  group: ${{ github.workflow }}
+  group: triage-sweep
   cancel-in-progress: true
 
 jobs:
@@ -76,7 +74,7 @@ jobs:
         run: pip install -r .github/scripts/triage/requirements.txt
 
       - name: Cache FastEmbed model weights
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
         with:
           path: ${{ github.workspace }}/.fastembed_cache
           key: fastembed-bge-small-en-v1.5

.github/workflows/trivy.yml

@@ -1,82 +0,0 @@
-name: Trivy Image Scan
-
-# Builds Dockerfile.cli and Dockerfile.web, then scans the resulting images
-# for OS-package and language-package CVEs at MEDIUM+ severity.
-# Findings upload to the Security tab; record-only (does not block merges).
-#
-# Trigger on Dockerfile changes in PRs so base-image/npm-layer remediation can
-# be verified before merge without running image scans on every PR.
-
-on:
-  pull_request:
-    paths:
-      - 'Dockerfile.cli'
-      - 'Dockerfile.web'
-      - 'gitnexus/Dockerfile.test'
-      - '.github/workflows/trivy.yml'
-  push:
-    branches: [main]
-  schedule:
-    - cron: '0 8 * * 1'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  scan:
-    name: Trivy (${{ matrix.image.name }})
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    permissions:
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        image:
-          - { dockerfile: Dockerfile.cli, name: gitnexus-cli }
-          - { dockerfile: Dockerfile.web, name: gitnexus-web }
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Setup Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
-
-      - name: Build image (load locally for scan)
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
-        with:
-          context: .
-          file: ${{ matrix.image.dockerfile }}
-          load: true
-          push: false
-          tags: scan-target:${{ matrix.image.name }}
-
-      # aquasecurity/trivy-action versions < 0.35.0 are flagged by
-      # GHSA-69fq-xp46-6x23 (briefly compromised supply chain). Pinned to
-      # v0.36.0 (post-incident clean release) by commit SHA.
-      - name: Run Trivy
-        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
-        with:
-          image-ref: scan-target:${{ matrix.image.name }}
-          format: sarif
-          output: trivy-${{ matrix.image.name }}.sarif
-          severity: MEDIUM,HIGH,CRITICAL
-          # Hides CVEs with no available fix in the base image.
-          ignore-unfixed: true
-          exit-code: '0'
-
-      - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
-        with:
-          sarif_file: trivy-${{ matrix.image.name }}.sarif
-          category: trivy-${{ matrix.image.name }}

.github/workflows/workflow-lint.yml

@@ -1,85 +0,0 @@
-name: Workflow Lint
-
-# Lints .github/workflows/** for both:
-#   - actionlint: YAML syntax, expression typing, shellcheck inside `run:`
-#     blocks, unknown contexts, deprecated runner labels.
-#   - zizmor: security misconfigurations — unpinned actions, dangerous
-#     `${{ }}` interpolation, missing per-job permissions, etc.
-#
-# Scoped to PRs that touch .github/** only — keeps off the typical PR
-# critical path.
-
-on:
-  pull_request:
-    branches: [main]
-    paths:
-      - '.github/**'
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  actionlint:
-    name: actionlint
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      contents: read
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          persist-credentials: false
-
-      # Pinned to v2.1.2. Verify SHA via:
-      #   gh api repos/raven-actions/actionlint/git/refs/tags/v2.1.2
-      # The action wraps the upstream `rhysd/actionlint` binary and emits
-      # GitHub-annotation-formatted findings on PRs.
-      - name: Run actionlint
-        uses: raven-actions/actionlint@205b530c5d9fa8f44ae9ed59f341a0db994aa6f8 # v2.1.2
-        with:
-          fail-on-error: true
-
-  zizmor:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      contents: read
-      security-events: write
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Setup Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-        with:
-          python-version: '3.12'
-
-      - name: Install zizmor
-        # Pinned — resolves to whatever's latest on PyPI otherwise.
-        # Bump via Dependabot pip ecosystem (see .github/dependabot.yml).
-        run: pipx install zizmor==1.24.1
-
-      # Initial threshold: medium. High+ findings fail the job; medium findings
-      # appear in the Security tab without blocking. Tune after first run.
-      # Per-rule exemptions for pre-existing intentional patterns live in
-      # .github/zizmor.yml (each carries a documented mitigation).
-      - name: Run zizmor
-        run: zizmor --config .github/zizmor.yml --format sarif --min-severity medium . > zizmor.sarif
-        continue-on-error: true
-
-      - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
-        with:
-          sarif_file: zizmor.sarif
-          category: zizmor
-
-      - name: Fail on high+ findings
-        run: zizmor --config .github/zizmor.yml --min-severity high .

.github/zizmor.yml

@@ -1,43 +0,0 @@
-# zizmor config — pre-existing intentional patterns flagged on initial introduction.
-# Each ignore below has a documented mitigation. Re-evaluate when the source workflow changes.
-#
-# To run zizmor locally with this config:
-#   zizmor --config .github/zizmor.yml .
-
-rules:
-  dangerous-triggers:
-    ignore:
-      # workflow_run is REQUIRED to post sticky comments on fork PRs — the
-      # default-branch privileged token isn't accessible from `pull_request`
-      # on a fork. Mitigated by: read-only `actions:read` + `contents:read`
-      # for artifact download; `pull-requests:write` is the only write scope;
-      # no checkout of fork code occurs. Header comment in the file documents.
-      - ci-report.yml
-
-      # workflow_run is the trusted half of the autofix pipeline. The
-      # untrusted half (pr-autofix.yml) runs fork code with permissions:{}
-      # and produces only a diff artifact (data, not executable code). The
-      # publish job consumes the artifact, allowlist-validates every field
-      # of metadata.json before exporting to $GITHUB_OUTPUT, never checks
-      # out fork code, and never executes anything fork-controlled. Header
-      # comment in the file documents the split.
-      - pr-autofix-publish.yml
-
-      # pull_request_target needed by claude-code-action to access secrets
-      # and post review comments on fork PRs. Mitigated by: PR checkouts pin
-      # the fork's HEAD SHA (not the branch ref) to prevent TOCTOU races,
-      # and claude-code-action sandboxes execution. Header comment documents.
-      - claude.yml
-
-      # pull_request_target on the autolabel job needs `pull-requests:write`
-      # to apply labels. Mitigated by: release-drafter runs with `dry-run:
-      # true`, reads only `.github/release-drafter.yml` from the BASE ref,
-      # and the validate-title job (which runs untrusted `pull_request`
-      # context) holds no write permissions. Header comment documents.
-      - pr-labeler.yml
-
-  # Note: cache-poisoning is NOT exempted. The two prior findings in
-  # publish.yml and release-candidate.yml were fixed structurally by
-  # dropping `cache: npm` from those workflows (matches the pattern used
-  # by PyO3/maturin for the same audit). See the commit that added this
-  # file for the rationale.

.gitignore

@@ -23,7 +23,6 @@ Thumbs.db
 .env
 .env.local
 .env.*.local
-docker/.env
 
 # Logs
 *.log
@@ -82,11 +81,6 @@ GitNexus.sln
 # Git worktrees
 .worktrees/
 
-# Vendored tree-sitter grammar build artifacts (created at install time,
-# never committed). See docs/plans/2026-04-15-002-fix-tree-sitter-proto-vendor-deps-plan.md
-gitnexus/vendor/**/build/
-gitnexus/vendor/**/node_modules/
-
 /github/scripts/triage/__pycache__/
 
 .claude-flow/
@@ -101,10 +95,4 @@ gitnexus/vendor/**/node_modules/
 
 .swarm/
 
-local_docs/
-
-# Local agent scratch / review prompts (never commit)
-.tmp/
-.agents/
-.context/
-gitnexus/web/
+local_docs/

.prettierignore

@@ -2,7 +2,6 @@ dist/
 coverage/
 gitnexus/vendor/
 gitnexus/test/fixtures/
-gitnexus-web/test/fixtures/
 gitnexus-web/playwright-report/
 gitnexus-web/test-results/
 *.d.ts

AGENTS.md

@@ -1,130 +1,117 @@
-<!-- version: 1.7.0 -->
-<!-- Last updated: 2026-04-23 -->
+<!-- version: 1.3.0 -->
+<!--
+  Metadata: version, last reviewed, scope, model policy, reference docs, changelog.
+  Last updated: 2026-03-22
+-->
 
-Last reviewed: 2026-04-23
+Last reviewed: 2026-04-13
 
 **Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
 
+This file uses a standard agent header (version, scope, model policy, reference docs, changelog), adapted for this **TypeScript/JavaScript monorepo**.
+
 ## Scope
 
-| Boundary | Rule |
-|----------|------|
-| **Reads** | `gitnexus/`, `gitnexus-web/`, `eval/`, plugin packages, `.github/`, `.gitnexus/`, docs. |
-| **Writes** | Only paths required for the change; keep diffs minimal. Update lockfiles when deps change. |
-| **Executes** | `npm`, `npx`, `node` under `gitnexus/` and `gitnexus-web/`; `uv run` for Python under `eval/`; documented CI/dev workflows. |
-| **Off-limits** | Real `.env` / secrets, production credentials, unrelated repos, destructive git ops without confirmation. |
+| | |
+|--|--|
+| **Reads** | Repository tree as needed for the task: `gitnexus/`, `gitnexus-web/`, `eval/`, plugin packages, `.github/`, `.gitnexus/` when present, and docs. |
+| **Writes** | Only paths required for the requested change; keep diffs minimal. Update lockfiles when dependencies change. |
+| **Executes** | `npm`, `npx`, `node` under `gitnexus/` and `gitnexus-web/`; `uv run` for Python under `eval/` when applicable; shell utilities for documented CI/dev workflows. |
+| **Off-limits** | User secrets (e.g. real `.env`), production deployment credentials, unrelated repositories, destructive git history operations without explicit human confirmation. |
 
 ## Model Configuration
 
-- **Primary:** Use a named model (e.g. Claude Sonnet 4.x). Avoid `Auto` or unversioned `latest` when reproducibility matters.
-- **Notes:** The GitNexus CLI indexer does not call an LLM.
+- **Primary:** Pin in **Cursor** (Settings → model). Use a **named** model (e.g. GPT-5.2, Claude Sonnet 4.x). Avoid relying on **Auto** when reproducibility or audit trail matters.
+- **Fallback:** As configured in Cursor or your organization (do not encode `latest` or wildcards in automation configs).
+- **Notes:** The open-source GitNexus CLI indexer does not call an LLM. Optional Nexus AI in the web UI uses end-user provider keys and models.
 
 ## Execution Sequence (complex tasks)
 
-For multi-step work, state up front:
-1. Which rules in this file and **[GUARDRAILS.md](GUARDRAILS.md)** apply (and any relevant Signs).
-2. Current **Scope** boundaries.
-3. Which **validation commands** you will run (`cd gitnexus && npm test`, `npx tsc --noEmit`).
+Long sessions dilute instructions. For **multi-step** work, state up front:
 
-On long threads, *"Remember: apply all AGENTS.md rules"* re-weights these instructions against context dilution.
+1. Which rules in this file and **[GUARDRAILS.md](GUARDRAILS.md)** apply (and any relevant Signs).
+2. Current **Scope** boundaries (Reads / Writes / Off-limits).
+3. Which **validation commands** you will run (e.g. `cd gitnexus && npm test`, `npx tsc --noEmit`).
+
+On very long threads, the human may add *“Remember: apply all AGENTS.md rules”* to re-weight rule tokens against context dilution.
 
 ## Claude Code hooks
 
-**PreToolUse** hooks can block tools (e.g. `git_commit`) until checks pass. Adapt to this repo: `cd gitnexus && npm test` before commit.
+Hooks enforce gates that prompts cannot. In **Claude Code**, **PreToolUse** hooks can block tools such as `git_commit` until checks pass. Adapt to this repo: e.g. `cd gitnexus && npm test` before commit.
 
-## Context budget
+## Context budget (Cursor / standards)
 
-Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.md](CONTRIBUTING.md)**. If always-on rules grow, split into **`.cursor/rules/*.mdc`** (globs). **Cursor:** project-wide rules in `.cursor/index.mdc`. **Claude Code:** load `STANDARDS.md` only when needed.
+Generic “core standards” playbooks are often long and stack-specific. For this monorepo, commands and gotchas live under **Cursor Cloud specific instructions** below and in **[CONTRIBUTING.md](CONTRIBUTING.md)**. If always-on rules grow, split domain rules into **`.cursor/rules/*.mdc`** (globs). **Cursor:** project-wide rules live in **`.cursor/index.mdc`** (YAML frontmatter with `alwaysApply: true`). **Claude Code:** optionally load a **`STANDARDS.md`** only when needed (e.g. *“When writing new code, read STANDARDS.md”*) to save context.
 
-## Reference docs
+## Reference Documentation
 
-- **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**
-- **Call-resolution DAG (legacy path):** See ARCHITECTURE.md § Call-Resolution DAG. Typed 6-stage DAG inside the `parse` phase; language-specific behavior behind `inferImplicitReceiver` / `selectDispatch` hooks on `LanguageProvider`. Shared code in `gitnexus/src/core/ingestion/` must not name languages. Types: `gitnexus/src/core/ingestion/call-types.ts`.
-- **Scope-resolution pipeline (RFC #909 Ring 3):** See ARCHITECTURE.md § Scope-Resolution Pipeline. Replaces the legacy DAG for languages in `MIGRATED_LANGUAGES` (see `registry-primary-flag.ts`). A language plugs in by implementing `ScopeResolver` (`scope-resolution/contract/scope-resolver.ts`) and registering it in `SCOPE_RESOLVERS`. CI parity gate runs BOTH paths per migrated language on every PR.
-- **Cursor:** `.cursor/index.mdc` (always-on); `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` deprecated.
-- **GitNexus:** skills in `.claude/skills/gitnexus/`; MCP rules in `gitnexus:start` block below.
+- **This repository:** **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**.
+- **Cursor:** `.cursor/index.mdc` (always-on rules); optional `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` is deprecated — see `.cursor/index.mdc`.
+- **Optional local files:** `NOTES.md` (short vendor-neutral project snapshot). For handoffs, keep notes local (e.g., a scratch file outside the repo) rather than committing `HANDOFF.md`.
+- **GitNexus:** skills under `.claude/skills/gitnexus/`; machine-oriented rules in the `gitnexus:start` … `gitnexus:end` block below.
 
 ## Changelog
 
 | Date | Version | Change |
 |------|---------|--------|
-| 2026-04-23 | 1.7.0 | TypeScript added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). |
-| 2026-04-20 | 1.6.0 | Added scope-resolution pipeline pointer (RFC #909 Ring 3); Python migrated to registry-primary. |
-| 2026-04-19 | 1.5.0 | Cross-repo impact (#794): `impact`/`query`/`context` accept `repo: "@<group>"` + `service`. Removed `group_query`/`group_contracts`/`group_status` MCP tools; added `gitnexus://group/{name}/contracts` and `gitnexus://group/{name}/status` resources. |
-| 2026-04-16 | 1.4.0 | Fixed: web UI description, pre-commit behavior, MCP tools (7->16), added gitnexus-shared, removed stale vite-plugin-wasm gotcha. |
 | 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. |
-| 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication. |
-| 2026-03-23 | 1.1.0 | Updated agent instructions, references, Cursor layout. |
-| 2026-03-22 | 1.0.0 | Initial structured header and changelog. |
+| 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication (was inlined in Reference Docs bullet). |
+| 2026-03-23 | 1.1.0 | Updated agent instructions (sections, references, Cursor layout). |
+| 2026-03-22 | 1.0.0 | Added structured agent header and changelog. |
 
 ---
 
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
-> If any tool warns the index is stale, run `npx gitnexus analyze` first.
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 
 ## Always Do
 
-- **MUST run impact analysis before editing any symbol.** `gitnexus_impact({target: "symbolName", direction: "upstream"})` — report blast radius to the user.
-- **MUST run `gitnexus_detect_changes()` before committing** — verify only expected symbols and flows are affected.
-- **MUST warn the user** if impact returns HIGH or CRITICAL risk.
-- Explore unfamiliar code with `gitnexus_query({query: "concept"})` (process-grouped, ranked) instead of grepping.
-- Full context on a symbol: `gitnexus_context({name: "symbolName"})`.
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
 
 ## When Debugging
 
-1. `gitnexus_query({query: "<error or symptom>"})` — find related execution flows
-2. `gitnexus_context({name: "<suspect function>"})` — callers, callees, process participation
-3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace flow step by step
-4. Regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})`
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
 
 ## When Refactoring
 
-- **Rename:** `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Graph edits are safe; text_search edits need manual review.
-- **Extract/Split:** `gitnexus_context` (incoming/outgoing refs) then `gitnexus_impact` (upstream callers) before moving code.
-- **After any refactor:** `gitnexus_detect_changes({scope: "all"})` to verify scope.
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
 
 ## Never Do
 
-- Edit a symbol without running `gitnexus_impact` first.
-- Ignore HIGH/CRITICAL risk warnings.
-- Rename with find-and-replace — use `gitnexus_rename`.
-- Commit without `gitnexus_detect_changes()`.
-- Add language-specific behavior to shared ingestion code (`gitnexus/src/core/ingestion/`) — use a `LanguageProvider` hook. Seeing `provider.mroStrategy === 'xxx'` or an import from `languages/xxx.ts` in shared code means stop and add a hook.
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
 
 ## Tools Quick Reference
 
-| Tool | When to use | Example |
+| Tool | When to use | Command |
 |------|-------------|---------|
-| `list_repos` | Discover indexed repos | `gitnexus_list_repos({})` |
 | `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
 | `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
 | `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
 | `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
 | `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
 | `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
-| `api_impact` | Pre-change API route impact | `gitnexus_api_impact({route: "/api/users", method: "GET"})` |
-| `route_map` | Route → handler → consumer map | `gitnexus_route_map({})` |
-| `tool_map` | MCP/RPC tool definitions | `gitnexus_tool_map({})` |
-| `shape_check` | Response shape vs consumer access | `gitnexus_shape_check({route: "/api/users"})` |
-| `group_list` | List repo groups | `gitnexus_group_list({})` |
-| `group_sync` | Rebuild group Contract Registry | `gitnexus_group_sync({name: "myGroup"})` |
-| `query` (group mode) | Cross-repo search in a group (RRF-merged) | `gitnexus_query({repo: "@myGroup", query: "auth"})` |
-| `context` (group mode) | 360° view across all member repos | `gitnexus_context({repo: "@myGroup", name: "validateUser"})` |
-| `impact` (group mode) | Cross-repo blast radius via Contract Bridge | `gitnexus_impact({repo: "@myGroup", target: "X", direction: "upstream"})` |
-
-> Group mode: pass `repo: "@<groupName>"` to fan out across all member repos, or `repo: "@<groupName>/<memberPath>"` to target a single member (path keys from `group.yaml`). Optional `service: "<monorepo/path>"` filters by service root. Group-level state (contracts, staleness) lives in the resources table below — there are **no** `group_query` / `group_context` / `group_impact` / `group_contracts` / `group_status` MCP tools.
->
-> For a full walkthrough of setting up a group across multiple repos that communicate over gRPC, see [docs/guides/microservices-grpc.md](docs/guides/microservices-grpc.md).
 
 ## Impact Risk Levels
 
 | Depth | Meaning | Action |
 |-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update |
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
 | d=2 | LIKELY AFFECTED — indirect deps | Should test |
 | d=3 | MAY NEED TESTING — transitive | Test if critical path |
 
@@ -132,88 +119,87 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows)
 
 | Resource | Use for |
 |----------|---------|
-| `gitnexus://repo/GitNexus/context` | Codebase overview, index freshness |
+| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
 | `gitnexus://repo/GitNexus/clusters` | All functional areas |
 | `gitnexus://repo/GitNexus/processes` | All execution flows |
 | `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
-| `gitnexus://group/{name}/contracts` | Group Contract Registry (provider/consumer rows + cross-links) |
-| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness report |
 
 ## Self-Check Before Finishing
 
+Before completing any code modification task, verify:
 1. `gitnexus_impact` was run for all modified symbols
-2. No HIGH/CRITICAL warnings were ignored
-3. `gitnexus_detect_changes()` confirms expected scope
-4. All d=1 dependents were updated
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
 
 ## Keeping the Index Fresh
 
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
 ```bash
-npx gitnexus analyze                 # incremental by default; preserves embeddings
-npx gitnexus analyze --force         # full rebuild from scratch (opt out of incremental)
-npx gitnexus analyze --embeddings    # also generate embeddings for new/changed nodes
-npx gitnexus analyze --drop-embeddings  # explicit opt-in to wipe existing embeddings
+npx gitnexus analyze
 ```
 
-`analyze` runs **incrementally by default**. The pipeline still parses every file every run (cross-file resolution requires it), but tree-sitter parsing is **served from a content-addressed cache** at `.gitnexus/parse-cache.json` for chunks whose file contents haven't changed since the last run. Only changed-file rows (and their importers) are rewritten in LadybugDB; unchanged-file rows are preserved. Output is byte-equivalent to a full rebuild. Pass `--force` to wipe and re-index from scratch (e.g., to recover from a corrupt index, or after upgrading GitNexus).
+If the index previously included embeddings, preserve them by adding `--embeddings`:
 
-The parse cache key is **content-addressed and version-tagged**: it survives `--force` runs, and is automatically invalidated by a `gitnexus` package upgrade (so a new tree-sitter grammar doesn't silently replay stale parse output). Safe to delete `.gitnexus/parse-cache.json` at any time — it'll be rebuilt on the next analyze.
+```bash
+npx gitnexus analyze --embeddings
+```
 
-Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe.
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
 
-> Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself.
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
 
-## CLI Skills
+## CLI
 
-| Task | Skill file |
-|------|-----------|
-| Architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
-| Blast radius / "What breaks?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
-| Debugging / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
-| Refactoring | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
-| Tools/resources/schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
-| CLI commands (index, status, clean, wiki) | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
 
 <!-- gitnexus:end -->
 
-## Repo reference
+## Cursor Cloud specific instructions
 
-### Packages
+### Repository structure
 
-| Package | Path | Purpose |
-|---------|------|---------|
-| **CLI/Core** | `gitnexus/` | TypeScript CLI, indexing pipeline, MCP server. Published to npm. |
-| **Web UI** | `gitnexus-web/` | React/Vite thin client. All queries via `gitnexus serve` HTTP API. |
-| **Shared** | `gitnexus-shared/` | Shared TypeScript types and constants. |
-| Claude Plugin | `gitnexus-claude-plugin/` | Static config for Claude marketplace. |
-| Cursor Integration | `gitnexus-cursor-integration/` | Static config for Cursor editor. |
-| Eval | `eval/` | Python evaluation harness (Docker + LLM API keys). |
+This is a monorepo with two main products and supporting config packages:
+
+| Component | Path | Purpose |
+|-----------|------|---------|
+| **GitNexus CLI/Core** | `gitnexus/` | Main product — TypeScript CLI, indexing pipeline, MCP server. Published to npm. |
+| **GitNexus Web UI** | `gitnexus-web/` | React/Vite browser app — graph explorer + AI chat. Runs entirely in WASM. |
+| Claude Plugin | `gitnexus-claude-plugin/` | Static config for Claude marketplace (no build). |
+| Cursor Integration | `gitnexus-cursor-integration/` | Static config for Cursor editor (no build). |
+| SWE-bench Eval | `eval/` | Python evaluation harness (optional; needs Docker + LLM API keys). |
 
 ### Running services
 
-```bash
-cd gitnexus && npm run dev                 # CLI: tsx watch mode
-cd gitnexus-web && npm run dev             # Web UI: Vite on port 5173
-npx gitnexus serve                         # HTTP API on port 4747 (from any indexed repo)
-```
+- **CLI/Core**: `cd gitnexus && npm run dev` (tsx watch mode) or `npm run build && node dist/cli/index.js <command>`
+- **Web UI**: `cd gitnexus-web && npm run dev` (Vite on port 5173)
+- **Backend mode**: `cd <indexed-repo> && node /workspace/gitnexus/dist/cli/index.js serve` (HTTP API on port 3741 by default)
 
 ### Testing
 
 **CLI / Core (`gitnexus/`)**
-- `npm test` — full vitest suite (~2000 tests)
-- `npm run test:unit` — unit tests only
-- `npm run test:integration` — integration (~1850 tests). LadybugDB file-locking tests may fail in containers (known env issue).
-- `npx tsc --noEmit` — typecheck
+- **Unit tests**: `cd gitnexus && npm test` (vitest, ~2000 tests)
+- **Integration tests**: `cd gitnexus && npm run test:integration` (vitest, ~1850 tests). Two LadybugDB file-locking tests (`lbug-core-adapter`, `search-core`) may fail in containerized environments due to `/tmp` locking limitations — this is a known environment issue, not a code bug.
+- **TypeScript check**: `cd gitnexus && npx tsc --noEmit`
 
 **Web UI (`gitnexus-web/`)**
-- `npm test` — vitest (~200 tests)
-- `npm run test:e2e` — Playwright (7 spec files; requires `gitnexus serve` + `npm run dev`)
-- `npx tsc -b --noEmit` — typecheck
+- **Unit tests**: `cd gitnexus-web && npm test` (vitest, ~200 tests)
+- **E2E tests**: `cd gitnexus-web && E2E=1 npx playwright test` (Playwright, 5 tests — requires `gitnexus serve` + `npm run dev` running)
+- **TypeScript check**: `cd gitnexus-web && npx tsc -b --noEmit`
 
-**Pre-commit hook** (`.husky/pre-commit`): formatting (prettier via lint-staged) + typecheck for staged packages. Tests do **not** run in pre-commit — CI only.
+No separate lint command is configured; TypeScript strict checking serves as the primary static analysis.
 
 ### Gotchas
 
-- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (patches tree-sitter-swift, builds tree-sitter-proto). Native bindings need `python3`, `make`, `g++`.
-- `tree-sitter-kotlin` and `tree-sitter-swift` are optional — install warnings expected.
-- ESLint configured via `eslint.config.mjs` (TS, React Hooks, unused-imports). No `npm run lint` script; use `npx eslint .`. Prettier runs via lint-staged. CI checks both in `ci-quality.yml`.
+- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (patches tree-sitter-swift). Native tree-sitter bindings require `python3`, `make`, and `g++` to be present.
+- `tree-sitter-kotlin` and `tree-sitter-swift` are optional dependencies — install warnings for these are expected and non-blocking.
+- The Web UI uses `vite-plugin-wasm` and requires `Cross-Origin-Opener-Policy`/`Cross-Origin-Embedder-Policy` headers for `SharedArrayBuffer` (handled automatically by Vite dev server).
+- There is no ESLint/Prettier configuration in this repo.

ARCHITECTURE.md

@@ -1,134 +1,99 @@
 # Architecture — GitNexus
 
-Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
+This repository is a **monorepo** with two main products: the **CLI / MCP package** (`gitnexus/`) and the **browser UI** (`gitnexus-web/`). Supporting folders ship editor integrations and plugins without changing the core graph engine.
 
 ## Repository layout
 
 | Path | Role |
 |------|------|
-| `gitnexus/` | npm package `gitnexus`: CLI, MCP server (stdio), HTTP API, ingestion pipeline, LadybugDB graph, embeddings. |
-| `gitnexus-web/` | Vite + React thin client: graph explorer + AI chat. All queries via `gitnexus serve` HTTP API. |
-| `gitnexus-shared/` | Shared TypeScript types and constants (consumed by CLI and Web). |
-| `.claude/`, `gitnexus-claude-plugin/`, `gitnexus-cursor-integration/` | Agent skills and plugin metadata. |
-| `eval/` | Evaluation harnesses for benchmarking tool usage. |
-| `.github/` | CI workflows + composite actions (`setup-gitnexus/`, `setup-gitnexus-web/`). |
+| `gitnexus/` | Published npm package `gitnexus`: CLI, MCP server (stdio), local HTTP API for bridge mode, ingestion pipeline, LadybugDB graph, embeddings (optional). |
+| `gitnexus-web/` | Vite + React UI: in-browser indexing (WASM), graph visualization, optional connection to `gitnexus serve`. |
+| `.claude/`, `gitnexus-claude-plugin/`, `gitnexus-cursor-integration/` | Packaged **skills** and plugin metadata so agents discover the same workflows as documented in `AGENTS.md`. |
+| `eval/` | Evaluation harnesses and docs for benchmarking tool usage. |
+| `.github/` | CI workflows (quality, unit, integration, E2E) and composite actions. |
 
 ## End-to-end flow: index → graph → tools
 
-1. **Ingestion** — `analyze.ts` → `runFullAnalysis` (`run-analyze.ts`) → `runPipelineFromRepo` (`pipeline.ts`). DAG of 12 phases builds a `KnowledgeGraph` in memory, then loads into LadybugDB under `.gitnexus/`. Repo registered in `~/.gitnexus/registry.json` for MCP discovery.
+1. **Ingestion** (`gitnexus analyze`)  
+   - Entry: `gitnexus/src/cli/analyze.ts` → `runPipelineFromRepo` in `gitnexus/src/core/ingestion/pipeline.ts`.  
+   - The pipeline is structured as a **DAG (Directed Acyclic Graph)** of named phases (see [Pipeline Phase DAG](#pipeline-phase-dag) below).  
+   - Output is loaded into **LadybugDB** under **`.gitnexus/`** at the repo root (`lbug/`, `meta.json`, etc.). Optional **FTS** indexes and **embeddings** attach to the same store.  
+   - The repo is registered in **`~/.gitnexus/registry.json`** so MCP can find it from any working directory.
 
-2. **Persistence** — `repo-manager.ts` (paths, registry, KuzuDB cleanup). `lbug-adapter.ts` (graph load, queries, embedding batches).
+2. **Persistence & metadata**  
+   - `gitnexus/src/storage/repo-manager.ts` — paths, registry, cleanup of legacy Kuzu artifacts.  
+   - `gitnexus/src/core/lbug/lbug-adapter.ts` — graph load, queries, embedding restore batches.
 
-3. **Query layer** — three interfaces to the same backend:
-   - **MCP (stdio):** `mcp.ts` → `LocalBackend` → tools (`tools.ts`) + resources (`resources.ts`)
-   - **HTTP bridge:** `serve.ts` → Express (`api.ts`, `mcp-http.ts`) for web UI
-   - **CLI direct:** `gitnexus query|context|impact|cypher` in `tool.ts`
+3. **Query & agents**  
+   - **MCP (stdio):** `gitnexus/src/cli/mcp.ts` → `startMCPServer` → `LocalBackend` (`gitnexus/src/mcp/local/local-backend.ts`) opens registered repos and serves **tools** from `gitnexus/src/mcp/tools.ts` and **resources** from `gitnexus/src/mcp/resources.ts`.  
+   - **Bridge HTTP:** `gitnexus/src/cli/serve.ts` → Express app in `gitnexus/src/server/api.ts` (CORS-limited) exposes REST + MCP-over-HTTP for the web UI.  
+   - **CLI tools (no MCP):** `gitnexus query`, `context`, `impact`, `cypher` in `gitnexus/src/cli/tool.ts` call the same backend for scripts and CI.
 
-4. **Staleness** — `staleness.ts` compares indexed `lastCommit` to `HEAD`, surfaces hints.
+4. **Staleness**  
+   - `gitnexus/src/mcp/staleness.ts` compares indexed `lastCommit` to `HEAD` and surfaces hints when the graph is behind git.
 
-## MCP tools
+## MCP tools (summary)
 
 | Tool | Purpose |
 |------|---------|
-| `list_repos` | Discover indexed repos |
-| `query` | Hybrid BM25 + vector search over the graph |
-| `cypher` | Ad hoc Cypher against the schema |
-| `context` | Callers, callees, processes for one symbol |
-| `impact` | Blast radius (upstream/downstream) with risk summary |
-| `detect_changes` | Map git diffs to affected symbols and processes |
-| `rename` | Graph-assisted multi-file rename with `dry_run` preview |
-| `api_impact` | Pre-change impact report for an API route handler |
-| `route_map` | API route → handler → consumer mappings |
-| `tool_map` | MCP/RPC tool definitions and handlers |
-| `shape_check` | Response shape vs consumer property access mismatches |
-| `group_list` | List repo groups or details for one group |
-| `group_sync` | Rebuild group Contract Registry (`contracts.json`) and bridge graph |
-
-`query`, `context`, and `impact` are group-aware: pass `repo: "@<groupName>"` (or `"@<groupName>/<memberPath>"` to scope to one member) plus optional `service: "<monorepo/path>"`. Group-mode `query` merges per-repo results via Reciprocal Rank Fusion; group-mode `impact` runs the local walk in the chosen member and fans out across boundaries via the Contract Bridge (`gitnexus/src/core/group/cross-impact.ts`). The previously-planned `group_query`, `group_context`, `group_impact`, `group_contracts`, `group_status` MCP tools are intentionally not introduced — group-level state is exposed via resources instead:
-
-| Resource URI | Purpose |
-|--------------|---------|
-| `gitnexus://group/{name}/contracts` | Contract Registry (provider/consumer rows + cross-links) |
-| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness |
+| `list_repos` | Discover indexed repositories when more than one is registered. |
+| `query` | Natural-language / keyword search over the graph (hybrid BM25 + optional vectors). |
+| `cypher` | Ad hoc **Cypher** against the schema (see resource `gitnexus://repo/{name}/schema`). |
+| `context` | Callers, callees, processes for one symbol (with disambiguation). |
+| `impact` | Blast radius (upstream/downstream) with depth and risk summary. |
+| `detect_changes` | Map git diffs to affected symbols and processes. |
+| `rename` | Graph-assisted rename with `dry_run` preview (`graph` vs `text_search` confidence). |
 
 ## Where to change what
 
-| Concern | Start in |
-|---------|----------|
-| CLI commands/flags | `src/cli/` (`index.ts`, per-command modules) |
-| Parsing/graph construction | `src/core/ingestion/pipeline-phases/` + `pipeline.ts` |
-| Graph schema/DB | `src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`) |
-| MCP tools/resources | `src/mcp/server.ts`, `tools.ts`, `resources.ts` |
-| Cross-repo groups (sync, contracts, `@<group>` routing) | `src/core/group/` (`service.ts`, `cross-impact.ts`, `sync.ts`, `bridge-db.ts`) |
-| Search ranking | `src/core/search/` (BM25, hybrid fusion) |
-| Embeddings | `src/core/embeddings/` + `src/core/run-analyze.ts` |
-| Wiki generation | `src/core/wiki/` |
-| Language support | `src/core/ingestion/languages/` + `tree-sitter-queries.ts` + `gitnexus-shared/src/languages.ts` |
-| Import resolution | `src/core/ingestion/import-processor.ts` + `import-resolvers/configs/` + `model/resolution-context.ts` |
-| Call resolution/MRO | `src/core/ingestion/call-processor.ts` + `model/resolve.ts` |
-| Type extraction | `src/core/ingestion/type-extractors/` |
-| Worker pool | `src/core/ingestion/workers/` |
-| Web UI | `gitnexus-web/src/` |
-| CI | `.github/workflows/*.yml`, `.github/actions/` |
-
-> Paths above are relative to `gitnexus/` unless they start with `gitnexus-web/` or `.github/`.
-
----
+| If you are changing… | Start in… |
+|----------------------|-----------|
+| CLI commands / flags | `gitnexus/src/cli/` (`index.ts`, per-command modules). |
+| Parsing or graph construction | `gitnexus/src/core/ingestion/pipeline-phases/` (individual phase files), `pipeline.ts` (orchestrator). |
+| Graph schema / DB access | `gitnexus/src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`), `gitnexus/src/mcp/core/lbug-adapter.ts` if MCP-specific. |
+| MCP protocol, tools, resources | `gitnexus/src/mcp/server.ts`, `tools.ts`, `resources.ts`. |
+| Search ranking | `gitnexus/src/core/search/` (BM25, hybrid fusion). |
+| Embeddings | `gitnexus/src/core/embeddings/`, phases in `analyze.ts`. |
+| Wiki generation | `gitnexus/src/core/wiki/`. |
+| Web UI behavior | `gitnexus-web/src/` (components, workers, graph client). |
+| CI | `.github/workflows/*.yml`, `.github/actions/setup-gitnexus/`. |
 
 ## Pipeline Phase DAG
 
-12 phases defined in `gitnexus/src/core/ingestion/pipeline-phases/`, each with explicit `deps` and typed output.
+The ingestion pipeline is a DAG of named phases. Each phase is defined in its own file under `gitnexus/src/core/ingestion/pipeline-phases/` with explicit dependencies, typed inputs, and typed outputs.
 
 ```
 scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
   → crossFile → mro → communities → processes
 ```
 
-| Phase | File | Deps | Output |
-|-------|------|------|--------|
-| `scan` | `scan.ts` | (root) | File paths + sizes |
-| `structure` | `structure.ts` | `scan` | File/Folder nodes, CONTAINS edges, `allPathSet` |
-| `markdown` | `markdown.ts` | `structure` | Section nodes, cross-link edges from .md/.mdx |
-| `cobol` | `cobol.ts` | `structure` | COBOL program/paragraph/section nodes (regex, no tree-sitter) |
-| `parse` | `parse.ts` + `parse-impl.ts` | `structure`, `markdown`, `cobol` | Symbol nodes, IMPORTS/CALLS/EXTENDS edges, extracted routes/tools/ORM queries |
-| `routes` | `routes.ts` | `parse` | Route nodes + HANDLES_ROUTE edges (Next.js, Expo, PHP, decorators) |
-| `tools` | `tools.ts` | `parse` | Tool nodes + HANDLES_TOOL edges |
-| `orm` | `orm.ts` | `parse` | QUERIES edges (Prisma, Supabase) |
-| `crossFile` | `cross-file.ts` + `cross-file-impl.ts` | `parse`, `routes`, `tools`, `orm` | Cross-file type propagation in topological import order |
-| `mro` | `mro.ts` | `crossFile`, `structure` | METHOD_OVERRIDES + METHOD_IMPLEMENTS edges |
-| `communities` | `communities.ts` | `mro`, `structure` | Community nodes + MEMBER_OF edges (Leiden algorithm) |
-| `processes` | `processes.ts` | `communities`, `routes`, `tools`, `structure` | Process nodes + STEP_IN_PROCESS edges |
+### Phase files
 
-**Non-phase files in the same directory:** `parse-impl.ts`, `cross-file-impl.ts` (implementation), `wildcard-synthesis.ts` (whole-module import expansion), `orm-extraction.ts` (sequential ORM fallback), `types.ts`, `runner.ts`, `index.ts`.
-
-### DAG runner
-
-`runner.ts` — static phase graph, no plugins, compile-time type safety.
-
-1. **Validation** — Kahn's topological sort. Rejects on: duplicate names, missing deps, cycles (DFS traces the concrete cycle path, e.g., `A -> B -> C -> A`, plus count of transitively blocked dependents).
-
-2. **Execution** — sequential in topological order. Each phase receives:
-   - `ctx: PipelineContext` — shared mutable `KnowledgeGraph`, `repoPath`, progress callback, options
-   - `deps: ReadonlyMap<string, PhaseResult>` — **declared deps only** (runner filters the results map to prevent hidden coupling)
-
-3. **Error handling** — wraps phase errors with the phase name, emits terminal `error` progress event, swallows progress handler errors to preserve the original cause.
-
-4. **Timing** — per-phase `durationMs` in `PhaseResult`, dev-mode console logging.
-
-**Design patterns:**
-- **Single graph accumulator** — all phases mutate the same `KnowledgeGraph` in `ctx`; the graph is the primary output.
-- **Typed phase access** — `getPhaseOutput<T>(deps, 'name')` for type-safe upstream results.
-- **Binding accumulator lifecycle** — created in `parse`, disposed by `crossFile` (in `finally`). No other phase should take ownership.
-- **Skippable phases** — `skipGraphPhases` omits MRO/communities/processes (faster tests). `skipWorkers` forces sequential parsing.
+| Phase | File | Dependencies | What it does |
+|-------|------|-------------|--------------|
+| `scan` | `scan.ts` | (root) | Walk repo filesystem, collect paths + sizes |
+| `structure` | `structure.ts` | `scan` | Build File/Folder nodes + CONTAINS edges |
+| `markdown` | `markdown.ts` | `structure` | Extract headings and cross-links from .md/.mdx |
+| `cobol` | `cobol.ts` | `structure` | Regex-based COBOL/JCL extraction |
+| `parse` | `parse.ts` + `parse-impl.ts` | `structure`, `markdown`, `cobol` | Chunked tree-sitter parse, import/call/heritage resolution |
+| `routes` | `routes.ts` | `parse` | Route registry (Next.js, Expo, PHP, decorator-based) |
+| `tools` | `tools.ts` | `parse` | MCP/RPC tool detection |
+| `orm` | `orm.ts` | `parse` | Prisma/Supabase ORM query edges |
+| `crossFile` | `cross-file.ts` + `cross-file-impl.ts` | `parse`, `routes`, `tools`, `orm` | Cross-file type propagation in topological order |
+| `mro` | `mro.ts` | `crossFile` | Method Resolution Order, METHOD_OVERRIDES edges |
+| `communities` | `communities.ts` | `mro` | Leiden community detection |
+| `processes` | `processes.ts` | `communities`, `routes`, `tools` | Execution flow detection, Route/Tool → Process links |
 
 ### How to add a new phase
 
-1. Create `pipeline-phases/my-phase.ts` with a `PipelinePhase<MyOutput>` (name, deps, execute)
-2. Export from `pipeline-phases/index.ts`
-3. Add to `buildPhaseList()` in `pipeline.ts`
+1. Create a new file in `pipeline-phases/` (e.g. `my-phase.ts`)
+2. Define a `PipelinePhase<MyOutput>` object with `name`, `deps`, and `execute(ctx, deps)`
+3. Export it from `pipeline-phases/index.ts`
+4. Add it to the `buildPhaseList()` function in `pipeline.ts`
 
 ```typescript
-import type { PipelinePhase, PhaseResult } from './types.js';
+// pipeline-phases/my-phase.ts
+import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
 import { getPhaseOutput } from './types.js';
 import type { ParseOutput } from './parse.js';
 
@@ -136,367 +101,81 @@ export interface MyPhaseOutput { /* ... */ }
 
 export const myPhase: PipelinePhase<MyPhaseOutput> = {
   name: 'myPhase',
-  deps: ['parse'],
+  deps: ['parse'],   // runs after parse completes
   async execute(ctx, deps) {
     const { allPaths } = getPhaseOutput<ParseOutput>(deps, 'parse');
-    // ... write to ctx.graph ...
+    // ... do work, write to ctx.graph ...
     return { /* typed output */ };
   },
 };
 ```
 
----
+### DAG runner
 
-## Call-Resolution DAG
-
-Typed 6-stage pipeline in `call-processor.ts` (inside the `parse` phase) that resolves method/function calls and emits CALLS edges. Language behavior plugs in at two `LanguageProvider` hook points (stages 3–4); shared code names no languages. Scope: call resolution only — import resolution, type extraction, heritage, and symbol-table population live in other phases.
-
-### Stages
-
-```
-extract-call ──▶ classify-form ──▶ infer-receiver ──▶ select-dispatch ──▶ resolve-target ──▶ emit-edge
-     (1)              (2)            (3)  [hook]       (4)  [hook]         (5)                 (6)
-```
-
-| Stage | Produces | Location |
-|-------|----------|----------|
-| **extract-call** | `ExtractedCallSite` (name, form, receiver, argCount) | `call-extractors/` (per-language); runs in worker |
-| **classify-form** | callForm (`free`/`member`/`constructor`) + arity | `call-analysis.ts` → `inferCallForm`; shared, runs in worker |
-| **infer-receiver** | `ReceiverEnriched` (receiver type finalized) | `call-processor.ts`; shared default chain, then `inferImplicitReceiver` hook |
-| **select-dispatch** | `DispatchDecision` (primary, fallback, ancestryView) | `selectDispatch` hook, falls back to shared default |
-| **resolve-target** | `TieredCandidates` | `model/resolve.ts` → `lookupMethodByOwnerWithMRO` (MRO walk) |
-| **emit-edge** | CALLS edge in graph | `call-processor.ts`; writes edge with confidence tier |
-
-### Provider hooks
-
-Both hooks are optional on `LanguageProvider`. Ruby is the only current implementer.
-
-**`inferImplicitReceiver`** — called after shared infer-receiver defaults. Returns `ImplicitReceiverOverride | null`.
-
-| | |
-|---|---|
-| Inputs | `calledName`, `callForm`, `receiverName`, `receiverTypeName`, `callNode` (AST), `filePath` |
-| Non-null fields | `callForm`, `receiverName`, `receiverTypeName` (required); `receiverSource: 'implicit-self'` (fixed); `hint?` (opaque, passed to `selectDispatch`) |
-| Null | Keep existing `ReceiverEnriched` state |
-
-**`selectDispatch`** — called after infer-receiver (including hook). Returns `DispatchDecision | null`; null uses shared default (constructor → `primary:'constructor'`; typed receiver → `primary:'owner-scoped'`; else → `primary:'free'`).
-
-| | |
-|---|---|
-| Inputs | `calledName`, `callForm`, `receiverName`, `receiverTypeName`, `receiverSource`, `hint` |
-| Non-null fields | `primary: 'owner-scoped' \| 'free' \| 'constructor'`; `fallback?: 'free-arity-narrowed'`; `ancestryView?: 'instance' \| 'singleton'`; `hint?` |
-
-**`DispatchDecision` field semantics:**
-- `primary: 'owner-scoped'` — MRO walk from receiver's type; used when receiver type is known.
-- `fallback: 'free-arity-narrowed'` — after owner-scoped miss, search free-call candidates by arity only (Ruby uses this for implicit-self calls that miss their owner's MRO).
-- `ancestryView: 'singleton'` — walk singleton/class ancestry instead of instance ancestry (Ruby `def self.foo` bodies, so `extend`-ed methods are found).
-
-### Adding language behavior
-
-1. **Implicit receivers** — implement `inferImplicitReceiver`: return null if call already has a receiver; otherwise use `findEnclosingClassInfo` (`ast-helpers.ts`) to find the enclosing context, return `ImplicitReceiverOverride` with `receiverSource: 'implicit-self'`, and optionally set `hint` for `selectDispatch`.
-2. **Custom dispatch** — implement `selectDispatch`: inspect `receiverSource` and `hint`, return `DispatchDecision` with `primary`, optional `fallback`, optional `ancestryView`; return null to keep shared defaults.
-3. **MRO strategy** — confirm `mroStrategy` is `'first-wins'`, `'c3'`, `'ruby-mixin'`, or `'none'`; consumed by `lookupMethodByOwnerWithMRO`.
-
-**Ruby example** (`languages/ruby.ts` + `utils/ruby-self-call.ts`): `inferImplicitReceiver` rewrites bare-identifier calls to `self.method` and sets `hint` to `'instance'`/`'singleton'`; `selectDispatch` uses hint for `ancestryView` and adds `fallback: 'free-arity-narrowed'` for implicit-self calls.
-
-### Code references
-
-| Module | Purpose |
-|--------|---------|
-| `core/ingestion/call-types.ts` | DAG types: `ReceiverEnriched`, `DispatchDecision`, `ImplicitReceiverOverride` |
-| `core/ingestion/language-provider.ts` | Hook signatures: `inferImplicitReceiver`, `selectDispatch` |
-| `core/ingestion/call-processor.ts` | `processCalls`: stages 3–6 |
-| `core/ingestion/model/resolve.ts` | `lookupMethodByOwnerWithMRO`: stage 5 MRO walk |
-| `core/ingestion/languages/ruby.ts` | Both hooks + `mroStrategy: 'ruby-mixin'` |
-| `core/ingestion/utils/ruby-self-call.ts` | Bare-call rewrite for `inferImplicitReceiver` |
-
-### Coexistence with the scope-resolution pipeline
-
-The Call-Resolution DAG is the **legacy path**. RFC #909 Ring 3 introduces a parallel **scope-resolution pipeline** (next section) that replaces stages 1–6 with a scope-indexed registry lookup. Both paths ship side-by-side and are gated per-language via `MIGRATED_LANGUAGES` + the `REGISTRY_PRIMARY_<LANG>` env var.
-
-- **Unmigrated language** → Call-Resolution DAG runs; scope-resolution phase is a no-op.
-- **Migrated language** (currently: Python, C#) → scope-resolution owns CALLS/ACCESSES/USES emission; the legacy DAG gates off for that language via `isRegistryPrimary(lang)` checks in `call-processor.ts` and `import-processor.ts`.
-- `import-processor` still populates `importMap` for migrated languages — heritage's `ctx.resolve` reads it to disambiguate parent classes. Only edge emission is gated.
-- CI runs BOTH paths for every migrated language on every PR (`.github/workflows/ci-scope-parity.yml`); both must pass.
-
-#### Same-graph guarantee
-
-Edges emitted by the scope-resolution pipeline and edges emitted by the legacy DAG are indistinguishable to downstream consumers (MCP tools, HTTP API, embeddings, group bridge):
-
-- **Node identity** — both paths use `generateId(...)` from `lib/utils.ts`, the same qualified-name keyspace, and the same node labels (`File`, `Folder`, `Class`, `Method`, `Function`, …). Overload disambiguation suffixes `parameterTypes` into the id consistently — see `scope-resolution/graph-bridge/ids.ts` and the legacy emitter in `call-processor.ts`.
-- **Edge vocabulary** — both paths emit the same reasons: `'import-resolved' | 'global' | 'local-call' | 'same-file' | 'interface-dispatch' | 'read' | 'write'`. Migrating a language must not change which reasons consumers see for previously-resolved edges.
-- **Confidence tier** — both paths attach a numeric `confidence` to each edge using the same scale.
-
-The CI parity workflow (`.github/workflows/ci-scope-parity.yml`) runs both paths against every migrated language's fixture corpus and fails on any divergence.
-
-#### Semantic-model source of truth
-
-Two independent invariants.
-
-**ParsedFile = the AST-level truth.** `ParsedFile` (`gitnexus-shared/src/scope-resolution/parsed-file.ts`) is the single per-file artifact both resolution paths consume. Scope-resolution passes MUST NOT build a parallel parse representation. If a per-language hook needs AST-level facts that `ParsedFile` doesn't expose, it should reuse the orchestrator's `treeCache` (`RunScopeResolutionInput.treeCache`) rather than re-invoking `parser.parse(...)` on its own — the C# `populateNamespaceSiblings` hook is the reference implementation of this pattern.
-
-**SemanticModel = the symbol-level truth.** `SemanticModel` (`gitnexus/src/core/ingestion/model/semantic-model.ts`) is the authoritative store for every symbol-indexed lookup (by `nodeId`, `simpleName`, `qualifiedName`, or `filePath`). Both paths read from here:
-
-- Legacy Call-Resolution DAG → `call-processor` Tier 1/2/3 via `model.symbols.lookupExactAll`, `model.methods.lookupMethodByName`, `model.types.lookupClassByName`, `lookupMethodByOwnerWithMRO`.
-- Scope-resolution pipeline → `findOwnedMember`, `pickOverload`, `findExportedDefByName` all consult `model.methods` / `model.fields` / `model.symbols`.
-
-The scope-resolution pipeline additionally carries `WorkspaceResolutionIndex` for `Scope`-valued lookups (`classScopeByDefId`, `moduleScopeByFile`) that `SemanticModel` structurally cannot hold. No symbol-indexed duplicates exist outside `SemanticModel`.
-
-**Write / read phase contract.** The model is mutable during three ordered phases and read-only afterward:
-
-```
- Phase 1: legacy parse     ──► symbolTable.add fans into types/methods/fields
- Phase 2: scope-resolution ──► reconcileOwnership() registers corrected ownerIds
- Phase 3: finalize         ──► model.attachScopeIndexes(bundle) — one-shot freeze
- ─────────────────────────── phase boundary ───────────────────────────
- Read phase: all resolution passes + MCP + HTTP + embeddings see
-             SemanticModel (read-only handle); writes are type-errors.
-```
-
-`runScopeResolution` narrows `MutableSemanticModel` → `SemanticModel` at the phase boundary so downstream passes physically cannot mutate the model even accidentally.
-
-**Transitional: reconciliation pass.** `reconcileOwnership` (`scope-resolution/pipeline/reconcile-ownership.ts`) is a shim for languages whose legacy extractor doesn't resolve `enclosingClassId` at parse time (Python class-body methods are the canonical case). It walks `parsed.localDefs[i].ownerId` after `populateOwners` and registers any missed methods/fields into the model. Idempotent — safe to re-run, safe alongside languages whose legacy extractor already carries `ownerId` (C#).
-
-The architectural end state is for every language's parse-time extractor to emit the correct `ownerId` directly, making reconciliation a no-op (tracked as a follow-up refactor). The dev-mode validator `validateOwnershipParity` surfaces any drift via `onWarn` under `NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`.
-
-References: `semantic-model.ts` file-head (full write/read contract); `contract/scope-resolver.ts` Contract Invariant I9 (scope-resolution-side rule).
-
----
-
-## Scope-Resolution Pipeline (RFC #909 Ring 3)
-
-Language-agnostic registry-primary resolver. Replaces the Call-Resolution DAG for migrated languages. Adding a language is one interface implementation (`ScopeResolver`) plus two registrations — no changes to shared code, no new pipeline phase.
-
-### Pipeline stages
-
-```
- ParsedFile[]  (extractParsedFile per file)
-    │  finalizeScopeModel (+ provider hooks)
-    ▼
- ScopeResolutionIndexes
-    │  resolveReferenceSites  (via MethodRegistry.lookup)
-    ▼
- ReferenceIndex
-    │  emitReceiverBoundCalls  ── FIRST
-    │  emitFreeCallFallback    ── THEN
-    │  emitReferencesViaLookup ── LAST (uses handledSites)
-    │  emitImportEdges
-    ▼
- KnowledgeGraph  (IMPORTS / CALLS / ACCESSES / INHERITS / USES)
-```
-
-Orchestrator: `runScopeResolution(input, provider)` in `scope-resolution/pipeline/run.ts`.
-Pipeline phase: `scopeResolutionPhase` in `scope-resolution/pipeline/phase.ts` — iterates `SCOPE_RESOLVERS ∩ MIGRATED_LANGUAGES`, reads per-file Trees from the parse phase's `scopeTreeCache`, disposes the cache at the end.
-
-### `ScopeResolver` contract
-
-Single interface a language implements to plug into the pipeline. Contract fully documented in `scope-resolution/contract/scope-resolver.ts`.
-
-| Hook | Purpose |
-|------|---------|
-| `languageProvider` | Base `LanguageProvider` (tree-sitter query, `emitScopeCaptures`, import/binding interpreters, hooks) |
-| `populateOwners(parsed)` | Fill deferred `ownerId` fields on method defs (captures can't always know the owning class at parse time) |
-| `buildMro(graph, parsed, nodeLookup)` | Produce `mroByClassDefId: Map<DefId, DefId[]>` — C3, Ruby-mixin, or first-wins per language |
-| `resolveImportTarget(target, fromFile, allFiles)` | `(rawImportPath, sourceFile) → targetFilePath` (PEP-328 for Python, etc.) |
-| `mergeBindings(existing, incoming, scopeId)` | Shadowing / LEGB precedence |
-| `arityCompatibility` | Provider consumed by registry during `MethodRegistry.lookup` Step 2 |
-| `importEdgeReason` | Confidence-tier string for IMPORTS edge reason field |
-| `propagatesReturnTypesAcrossImports?` | Opt out of cross-file return-type propagation (default on) |
-| `fieldFallbackOnMethodLookup?` | Statically-typed languages turn this OFF — the heuristic over-connects (default on) |
-| `unwrapCollectionAccessor?` | Property-style collection views (`data.Values` on Dictionary-like receivers) — default off |
-| `collapseMemberCallsByCallerTarget?` | One CALLS edge per (caller, target) instead of per-site — default off |
-| `populateNamespaceSiblings?` | Cross-file implicit visibility (compiler-implicit namespace sharing) — default off; ctx carries `treeCache` |
-| `hoistTypeBindingsToModule?` | Walk up to Module scope when looking up a method's return-type typeBinding — default off; enable only when bindings are stored at module level |
-
-### Per-language registration
-
-1. Implement `ScopeResolver` in `languages/<lang>/scope-resolver.ts`.
-2. Add entry to `SCOPE_RESOLVERS` in `scope-resolution/pipeline/registry.ts`.
-3. Add the language to `MIGRATED_LANGUAGES` in `registry-primary-flag.ts` when the shadow-harness corpus parity ≥ 99% fixtures / ≥ 98% corpus.
-
-CI auto-discovers the set via `tsx`. No workflow edit required.
-
-### Code references
-
-| Module | Purpose |
-|--------|---------|
-| `scope-resolution/contract/scope-resolver.ts` | `ScopeResolver` interface + shared types |
-| `scope-resolution/pipeline/run.ts` | Generic orchestrator |
-| `scope-resolution/pipeline/phase.ts` | Pipeline-phase wrapper (deps: `parse`, `structure`) |
-| `scope-resolution/pipeline/registry.ts` | `SCOPE_RESOLVERS` map |
-| `scope-resolution/passes/*.ts` | Reference-resolution passes (receiver-bound, free-call fallback, compound-receiver, MRO, cross-file return-type propagation) |
-| `scope-resolution/graph-bridge/*.ts` | CLI-local translation from resolved references → `KnowledgeGraph` edges |
-| `scope-resolution/scope/*.ts` | Generic scope-chain walkers + namespace targets |
-| `scope-resolution/workspace-index.ts` | Build-once O(1) lookup index |
-| `registry-primary-flag.ts` | `MIGRATED_LANGUAGES` set + `isRegistryPrimary(lang)` |
-| `languages/python/index.ts` | Python `ScopeResolver` hooks + known-limitation docs |
-| `languages/python/captures.ts` | `emitPythonScopeCaptures` (honors cross-phase Tree cache) |
-| `languages/csharp/index.ts` | C# `ScopeResolver` hooks + known-limitation docs |
-| `languages/csharp/captures.ts` | `emitCsharpScopeCaptures` (honors cross-phase Tree cache) |
-| `languages/csharp/namespace-siblings.ts` | Cross-file implicit-namespace visibility hook (reads `treeCache`) |
-
-### Performance notes
-
-- **Cross-phase Tree cache**: parse phase writes Trees into `scopeTreeCache` (separate from the chunk-local `astCache`) ONLY for languages with `emitScopeCaptures`. Scope-resolution reads from it to skip the second parse. Cleared at end of the phase. Workers leave the cache empty — Trees can't cross MessageChannels; cache miss = fresh parse. `PROF_SCOPE_RESOLUTION=1` emits hit/miss counters and a worker-engaged warning.
-- **Typed relationship iteration**: heritage + MRO walk only the EXTENDS / IMPLEMENTS / HAS_METHOD edges via `iterRelationshipsByType`, not the full relationship map.
-- **Workspace-resolution-index**: O(1) `findOwnedMember` / `findExportedDef` / `classScopeByDefId` built once per run.
-- **SCC-ordered cross-file return-type propagation** (PR #1050): `propagateImportedReturnTypes` walks `indexes.sccs` in reverse-topological order (leaves first), so multi-hop alias chains like `models.User → service.user → app.user` collapse to the terminal class in a single linear pass. Within each importer, the source module's `typeBindings` is chain-followed BEFORE mirroring (so we mirror terminal types, not intermediate refs), and the importer's own `typeBindings` is chain-followed AFTER mirroring (so local `const x = importedFn()` resolves before downstream importers run). Cyclic SCCs reach a partial fixpoint within a single pass without iterating to convergence — see the `ts-circular` cross-file-binding fixture which only asserts pipeline-no-throw. PROF output (`PROF_SCOPE_RESOLUTION=1`) splits `finalize` from `propagate` so quadratic regressions in the chain-follow surface independently.
-
----
-
-## Language-agnostic graph feeding
-
-16 languages → single unified graph. Four abstraction layers:
-
-```
- Unified Graph Schema (44 node types, 21 relationship types)
-           ↑
- Unified Resolution (3-tier name lookup + MRO walk)
-           ↑
- Language Providers (import semantics, type config, export checker, MRO strategy)
-           ↑
- Tree-Sitter Queries (per-language S-expressions, unified capture tags)
-```
-
-### Language providers
-
-Each language implements `LanguageProvider` (`language-provider.ts`). Key fields:
-
-| Field | Purpose |
-|-------|---------|
-| `id`, `extensions` | Language identity and file matching |
-| `treeSitterQueries` | S-expression queries for AST extraction |
-| `importSemantics` | `named` / `wildcard-leaf` / `wildcard-transitive` / `namespace` |
-| `importResolver` | Language-specific path → file resolution |
-| `exportChecker` | Public/exported symbol detection |
-| `typeConfig` | Type annotation extraction rules |
-| `mroStrategy` | `first-wins` / `c3` / `none` |
-
-16 providers in `languages/index.ts` via `satisfies Record<SupportedLanguages, LanguageProvider>` — missing a language is a compile error.
-
-### Unified capture tags
-
-Per-language tree-sitter queries use different AST node names but produce the **same semantic capture tags**: `@definition.class`, `@definition.function`, `@call.name`, `@import.source`, `@heritage.extends`. Downstream extraction needs no language branching. Defined in `tree-sitter-queries.ts`.
-
-### Import resolution
-
-Per-language import resolution uses the **configs + factory** pattern (like call/method/class extractors). Each language declares an `ImportResolutionConfig` in `import-resolvers/configs/`, listing an ordered chain of `ImportResolverStrategy` functions. `createImportResolver()` (in `resolver-factory.ts`) composes them: first non-null result wins. Low-level helpers shared across strategies live alongside the configs in `import-resolvers/` (e.g. `go.ts`, `rust.ts`, `python.ts`).
-
-Unified 3-tier algorithm (`model/resolution-context.ts`), per-language `importSemantics` controls which tier activates:
-
-| Tier | Confidence | Mechanism |
-|------|-----------|-----------|
-| 1 — same-file | 0.95 | Symbol table for caller's file |
-| 2 — import-scoped | 0.9 | `NamedImportMap` chains (named) or all files in `importMap` (wildcard) |
-| 3 — global | 0.5 | O(1) index lookups: class, impl, callable. Fallback only |
-
-| Import strategy | Languages | Behavior |
-|----------------|-----------|----------|
-| `named` | TS, JS, Java, C#, Rust, PHP, Kotlin | Only explicitly imported names visible |
-| `wildcard-leaf` | Go, Ruby, Swift, Dart | Whole-package import, no transitive re-exports |
-| `wildcard-transitive` | C, C++ | `#include` closure chains through re-exports |
-| `namespace` | Python | Module aliases resolved at call site |
-
-### Chunked parse-and-resolve
-
-`parse` processes files in ~20 MB byte-budget chunks to bound memory. Per chunk:
-1. Worker pool dispatches files (or sequential fallback via `skipWorkers`)
-2. Each worker: detect language → load grammar → run queries → return unified `ParseWorkerResult`
-3. Synthesize wildcard bindings (`wildcard-synthesis.ts`)
-4. Resolve imports and heritage
-5. Collect `BindingAccumulator` entries for cross-file propagation
-
-Workers: `workers/worker-pool.ts`, `workers/parse-worker.ts`.
-
-### Heritage and MRO
-
-All languages emit unified `ExtractedHeritage` (child, parent, `EXTENDS`/`IMPLEMENTS`). MRO phase walks the heritage graph using per-language strategy:
-- **`first-wins`** — Java, C#, C++, TS, Ruby, Go
-- **`c3`** — Python (C3 linearization)
-- **`none`** — single-inheritance languages
-
-Unified walk: `lookupMethodByOwnerWithMRO()` in `model/resolve.ts`.
-
----
-
-## Full analysis flow
-
-`runFullAnalysis` in `run-analyze.ts` orchestrates everything around the pipeline:
-
-```
-CLI (analyze.ts) → runFullAnalysis(repoPath, options, callbacks)
-  1. Early exit if lastCommit == HEAD (unless --force)     [0%]
-  2. Cache existing embeddings from prior index             [0%]
-  3. runPipelineFromRepo() → KnowledgeGraph                [0-60%]
-  4. Clean up legacy KuzuDB files                          [60%]
-  5. initLbug() → loadGraphToLbug() via CSV streaming      [60-85%]
-  6. Create FTS indexes (File, Function, Class, Method...) [85-90%]
-  7. Restore cached embeddings (batch insert)              [88%]
-  8. Generate new embeddings if --embeddings               [90-98%]
-  9. Save metadata + register repo + update .gitignore     [98-100%]
- 10. Generate AI context files (AGENTS.md, CLAUDE.md)      [100%]
-```
-
-**Options:** `--force` (rebuild regardless), `--embeddings` (opt-in, skipped if >50k nodes), `--skipGit`, `--noStats`.
-
-## Storage
-
-```
-<repo>/.gitnexus/
-  ├── lbug           # LadybugDB database
-  ├── lbug.wal       # Write-ahead log
-  ├── lbug.lock      # Single-writer lock
-  └── meta.json      # lastCommit, indexedAt, stats
-
-~/.gitnexus/
-  └── registry.json  # Global repo registry (MCP discovery)
-```
-
-Managed by `repo-manager.ts`.
-
-## LadybugDB schema
-
-Defined in `lbug/schema.ts`. Separate node tables per type, single `CodeRelation` table.
-
-**Node tables:** File, Folder, Function, Class, Interface, Method, Constructor, CodeElement, Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Property, Record, Delegate, Annotation, Template, Module, Community, Process, Route, Tool, Section, Embedding.
-
-**Relation types** (`CodeRelation.type`): CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF.
-
-## Embeddings and search
-
-**Embeddings** (`src/core/embeddings/`): Snowflake arctic-embed-xs (384D). Embeddable: File, Function, Class, Method, Interface. Incremental via SHA1 content hash. Separate `Embedding` table.
-
-**Search** (`src/core/search/`): Hybrid BM25 + semantic vector, merged via Reciprocal Rank Fusion (K=60).
+The runner (`pipeline-phases/runner.ts`) validates the DAG at startup (detects cycles and missing deps via topological sort), then executes phases in dependency order. Each phase receives:
+- `ctx: PipelineContext` — shared graph, repoPath, progress callback
+- `deps: Map<string, PhaseResult>` — outputs from all upstream phases
 
 ## Known limitations
 
 ### Overloaded method resolution
 
-Node IDs use arity suffix (`#<paramCount>`): `Method:file:Class.method#1` vs `#2`.
+Method and Constructor node IDs include an arity suffix (`#<paramCount>`) to
+disambiguate overloaded methods. Two overloads with different parameter counts
+produce distinct graph nodes: `Method:file:Class.method#1` vs
+`Method:file:Class.method#2`.
 
-**Same-arity disambiguation:** type-hash suffix `~type1,type2` when collision detected and type annotations present. Languages without types (Python, Ruby, JS) use arity-only. TS/JS overload signatures excluded (collapse to implementation body). See #651.
+**Same-arity overload disambiguation:** When two overloads share the same
+parameter count but differ in types (e.g. `save(int)` vs `save(String)`), a
+type-hash suffix `~type1,type2` is appended to produce distinct node IDs:
+`Method:file:Class.save#1~int` vs `Method:file:Class.save#1~String`. The suffix
+is only added when a same-arity collision is detected within a class and all
+parameters have non-null type annotations. Languages without type info (Python,
+Ruby, JS) fall back to arity-only IDs. TypeScript/JavaScript overload signatures
+are intentionally excluded from type-hashing because they are declaration-only
+contracts that should collapse to the implementation body's node ID. See issue
+\#651.
 
-**C++ const-qualified:** `$const` suffix after type-hash when non-const collision exists: `Method:file:Container.begin#0$const`.
+**C++ const-qualified overload disambiguation:** Methods overloaded by const
+qualification (e.g. `begin()` vs `begin() const`) are disambiguated via an
+`isConst` property and a `$const` ID suffix appended to the const-qualified
+variant when a non-const collision exists. The `$const` suffix appears after the
+type-hash suffix: e.g. `Method:file:Container.begin#0$const`.
 
-**Generic/template types:** type-hash uses `rawType` (full AST text including generics): `~vector<int>` vs `~vector<std::string>`.
+**Generic/template type preservation in type-hash:** The type-hash suffix uses
+`rawType` (full AST text including generic/template args) rather than the
+simplified `type` from `extractSimpleTypeName`. This means C++ template overloads
+like `process(vector<int>)` vs `process(vector<string>)` produce distinct IDs:
+`~vector<int>` vs `~vector<std::string>`. Java generic overloads like
+`process(List<String>)` vs `process(List<Integer>)` are a compile error due to
+type erasure, so this gap is theoretical for Java.
 
-**ID stability:** collision-only tags mean IDs change when overloads are added. `save#1` becomes `save#1~int` when `save(String)` is added.
+**ID stability on first overload:** Type and const tags are collision-only. When
+a class has `save(int)` as its only `save` method, the ID is `save#1` (no tag).
+Adding `save(String)` changes the original to `save#1~int`. This is correct for
+fresh analysis but means IDs are not stable across overload additions. Future
+incremental re-analysis should account for this.
 
-**Variadic matching:** confidence 0.7 when one side is variadic and the other has fixed count.
+**Variadic method matching:** When one side is variadic (`parameterCount`
+undefined) and the other has a fixed count, `METHOD_IMPLEMENTS` edges are
+emitted with confidence 0.7 instead of 1.0. Variadic methods like
+`foo(String... args)` may superficially match `foo(String s)` by type but
+are not guaranteed to be interchangeable across all languages (Java/Kotlin
+accept this via varargs sugar; TypeScript, C#, Rust do not).
 
-**METHOD_IMPLEMENTS confidence tiering:**
+**Confidence tiering** for `METHOD_IMPLEMENTS` edges:
 
-| Match quality | Confidence |
-|---|---|
-| Exact parameter types match | 1.0 |
-| Arity match, types unavailable | 1.0 |
-| Variadic vs fixed | 0.7 |
-| Insufficient info | 0.7 |
+| Match quality | Confidence | When |
+|---|---|---|
+| Exact parameter types match | 1.0 | Both sides have `parameterTypes` arrays and they match |
+| Arity (count) matches | 1.0 | Both sides have `parameterCount`, types unavailable |
+| Variadic vs fixed | 0.7 | One side is variadic, other has fixed count |
+| Lenient (insufficient info) | 0.7 | One or both sides lack type and count data |
 
 ## Related docs
 
-- [MIGRATION.md](MIGRATION.md) — breaking changes and migration guidance
-- [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery
-- [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents
-- [TESTING.md](TESTING.md) — how to run tests
-- `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage
+- [MIGRATION.md](MIGRATION.md) — breaking changes and migration guidance.
+- [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery.  
+- [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents.  
+- [TESTING.md](TESTING.md) — how to run tests.  
+- `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage expectations for **this** repo when indexed by GitNexus.

CLAUDE.md

@@ -35,7 +35,6 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 ## Reference Documentation
 
 - **This repository:** [AGENTS.md](AGENTS.md) (Cursor + monorepo notes), [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md), [GUARDRAILS.md](GUARDRAILS.md).
-- **Call-resolution DAG:** See ARCHITECTURE.md § Call-Resolution DAG. Shared pipeline code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` hooks instead (see AGENTS.md).
 - **GitNexus:** `.claude/skills/gitnexus/`; MCP and indexed-repo rules live only in [AGENTS.md](AGENTS.md) (`gitnexus:start` … `gitnexus:end`). See **GitNexus rules** below.
 
 ## Changelog
@@ -51,4 +50,206 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 
 ## GitNexus rules
 
-See the `<!-- gitnexus:start --> … <!-- gitnexus:end -->` block in **[AGENTS.md](AGENTS.md)** for the canonical MCP tools, impact analysis rules, and index instructions.
+GitNexus MCP rules are in the `<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/GitNexus/clusters` | All functional areas |
+| `gitnexus://repo/GitNexus/processes` | All execution flows |
+| `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->`  block in **[AGENTS.md](AGENTS.md)** — load that section when working with MCP tools or the graph index.
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (3298 symbols, 7954 relationships, 185 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/GitNexus/clusters` | All functional areas |
+| `gitnexus://repo/GitNexus/processes` | All execution flows |
+| `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

CONTRIBUTING.md

@@ -21,188 +21,30 @@ This project uses the [PolyForm Noncommercial License 1.0.0](https://polyformpro
 ## Branch and pull requests
 
 - Use short-lived branches off the default branch of the repo you are targeting.
-- **PR titles MUST follow the conventional-commit format** — `pr-labeler.yml` enforces this on every PR and auto-applies the matching label so release notes group the change correctly.
+- Prefer **conventional commits** (short prefix + description), for example:
+
+  ```text
+  feat: add graph export option
+  fix: correct MCP tool schema for query
+  test: cover cluster merge edge case
+  docs: clarify analyze flags
+  ```
+
+- **PR title:** `[area] Short description` (e.g. `[cli] Fix index refresh race`).
 - **PR description:** what changed, why, how to verify (commands), and any risk or rollback notes.
 
-### Pull request titles
-
-Format: `<type>[(scope)][!]: <subject>`
-
-Allowed types and the release-notes section each one lands in (defined in `.github/release.yml`):
-
-| Type               | Label applied   | Release-notes section                                        |
-| ------------------ | --------------- | ------------------------------------------------------------ |
-| `feat`             | `enhancement`   | 🚀 Features                                                  |
-| `fix`              | `bug`           | 🐛 Bug Fixes                                                 |
-| `perf`             | `performance`   | 🏎️ Performance                                               |
-| `refactor`         | `refactor`      | 🔄 Refactoring                                               |
-| `test`             | `test`          | 🧪 Tests                                                     |
-| `ci`               | `ci`            | 👷 CI/CD                                                     |
-| `build` / `deps`   | `dependencies`  | 📦 Dependencies                                              |
-| `docs`             | `documentation` | (grouped under Other Changes unless a Docs section is added) |
-| `chore` / `revert` | `chore`         | (excluded from release notes)                                |
-
-Append `!` to the type (e.g. `feat(api)!: drop /v1 endpoint`) or include `BREAKING CHANGE:` in the PR body to flag a breaking change — the labeler then adds the `breaking` label and the 💥 Breaking Changes section is rendered first.
-
-Examples:
-
-```text
-feat(web): add smart chat scroll
-fix(extractors): resolve silent contract mis-resolution
-perf: avoid O(n²) traversal in heritage walker
-chore(deps): bump vitest to 3.0.0
-ci: standardize workflow concurrency
-```
-
-Commits within a PR may use any style — only the **merged PR title** shows up in release notes, so that's the one the convention applies to.
-
 ## Before you open a PR
 
 - [ ] Tests pass for the packages you touched (`gitnexus` and/or `gitnexus-web`).
 - [ ] Typecheck passes: `npx tsc --noEmit` in `gitnexus/` and `npx tsc -b --noEmit` in `gitnexus-web/`.
 - [ ] No secrets, tokens, or machine-specific paths committed.
 - [ ] Documentation updated if behavior or public CLI/MCP contract changes.
-- [ ] Pre-commit hook runs clean (`.husky/pre-commit` — formatting via lint-staged + typecheck for staged packages; tests run in CI only).
+- [ ] Pre-commit hook runs clean (`.husky/pre-commit` — typecheck + unit tests for staged packages).
 
 ## Code review
 
 Maintainers may request changes for correctness, tests, performance, or consistency with existing patterns. Keeping diffs focused makes review faster.
 
-## GitHub Actions — Concurrency Convention
-
-Every workflow under `.github/workflows/` MUST declare a top-level `concurrency:` block using this convention:
-
-- **Group key** starts with `${{ github.workflow }}` so no two workflows can collide on the same group name. The discriminator that follows is chosen per event shape:
-  - Branch/tag scope: `${{ github.workflow }}-${{ github.ref }}`
-  - Per-PR scope (for `issue_comment`, `pull_request_review*`, `pull_request` meta events): `${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}`
-  - `workflow_run` scope (e.g. `ci-report.yml`): `${{ github.workflow }}-${{ github.event.workflow_run.pull_requests[0].number || format('{0}/{1}', github.event.workflow_run.head_repository.full_name, github.event.workflow_run.head_branch) }}` — the fork fallback must be stable across reruns (never `workflow_run.id`, which is per-run-unique and defeats serialization).
-  - Global single-slot (manual dispatch utilities): `${{ github.workflow }}`
-  - **Reusable workflows invoked via `workflow_call`:** do NOT use `${{ github.workflow }}` in the group key — in called-workflow context its evaluation is ambiguous and can resolve to the caller's name, which would deadlock against the caller's own group. Use a hardcoded literal prefix and a `github.event_name`-aware expression that falls through to `github.run_id` for reusable invocations (see `ci.yml` for the canonical form). Approved literal prefixes: `CI-` (`ci.yml`) and `docker-build-push-` (`docker.yml`). The `check-workflow-concurrency.py` validation script must be updated whenever a new approved literal prefix is added.
-  - **Merge queue (`merge_group`)**: when this event is added, use `${{ github.workflow }}-${{ github.event.merge_group.head_ref }}` with `cancel-in-progress: false` (every queue entry is a distinct ref; never cancel).
-- **`cancel-in-progress` policy:**
-
-  | Event                                    | `cancel-in-progress` | Why                              |
-  | ---------------------------------------- | -------------------- | -------------------------------- |
-  | `pull_request` CI run                    | `true`               | New push supersedes old run      |
-  | `push` to `main`                         | `false`              | Every main commit gets validated |
-  | Tag push (`v*` publish)                  | `false`              | Never cancel mid-publish         |
-  | `push` to `main` for release-candidate   | `false`              | Never cancel mid-RC publish      |
-  | `workflow_dispatch` (release/publish)    | `false`              | Manual runs are intentional      |
-  | `workflow_run` (sticky-comment reports)  | `false`              | Serialize, don't race            |
-  | Per-PR bot workflows (`@claude`, review) | `false`              | Serialize comments per PR        |
-  | PR-meta re-checks (pr-description-check) | `true`               | Cheap, latest wins               |
-  | Single-slot utilities (triage sweep)     | `true`               | Latest dispatch supersedes       |
-
-- For workflows that serve multiple events at once (e.g. `ci.yml` handles `pull_request`, `push`, and `workflow_call`), make `cancel-in-progress` event-aware:
-
-  ```yaml
-  concurrency:
-    group: ${{ github.workflow }}-${{ github.ref }}
-    cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-  ```
-
-- When adding a new workflow, copy the concurrency block from an existing workflow of the same event shape.
-
-## CI automation contracts
-
-Two workflows produce machine-readable signals on every PR. Coding agents and humans alike can rely on the names and shapes below — change them with intent.
-
-### `gitnexus/autofix`
-
-`pr-autofix.yml` (untrusted) + `pr-autofix-publish.yml` (trusted) run `prettier --write` and `eslint --fix` against the PR head and surface a single ChatOps button on the PR. Three signals are emitted:
-
-| Surface           | Where                                                                                                                                                                                                                                                                                                   | Notes                                                                  |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Sticky PR comment | Top-level comment with the HTML marker `<!-- gitnexus:pr-autofix-summary -->` and heading `## :sparkles: PR Autofix`. Only posted when there is something to fix; clean PRs stay silent.                                                                                                                | Edit-in-place via marker; one comment per PR.                          |
-| Fenced JSON block | Inside the sticky, fenced as `gitnexus-autofix`. Schema `gitnexus.pr-autofix/v2` with fields `state` (`fixes-available`), `pr_number`, `head_sha`, `changed_lines`, `run_id`, and `apply_command` (literal `/autofix`). | Parseable signal — preferred over regexing prose. v1 fields preserved as a superset. |
-| Check Run         | Stable name `gitnexus/autofix` on the PR head SHA. Conclusion: `success` (clean) or `neutral` (`fixes-available`). The neutral title is `Autofix available — comment /autofix to apply`.                                                                                                                | Surfaced under PR Checks; readable via `gh pr checks <pr>`.            |
-
-To detect outcome from an agent: `gh pr checks <pr> --json name,conclusion,output | jq '.[] | select(.name == "gitnexus/autofix")'`.
-
-Forks are supported. The untrusted half runs fork code with `permissions: {}` and ships the diff as an artifact; the trusted publish job consumes only the diff (data, not code) and posts the comment + check run.
-
-#### Applying autofix
-
-Comment `/autofix` on the PR (whole-line, no arguments). The `pr-autofix-apply.yml` workflow:
-
-1. Validates the comment body matches `^/autofix\s*$` exactly. Quoted or inline mentions are silently ignored.
-2. Validates the commenter has `admin`, `write`, or `maintain` permission on the repo, OR is the PR author. Other commenters get a 👎 reaction and a refusal reply.
-3. Locates the most recent successful `pr-autofix.yml` run for the PR's current head SHA, downloads its `autofix` artifact, applies the patch, and pushes a `chore(autofix): ...` commit back to the PR head branch.
-4. Reacts ✅ on success, 👎 on stale-patch / push-failure, and posts a short reply with the apply-run URL in either case.
-
-The apply workflow runs from the default branch's copy of the file regardless of where the comment originates — that's the trust anchor. There is no diff-size cap (the apply workflow uses `git apply` + push, not the GitHub review-comment API).
-
-For fork PRs, the push succeeds only when the contributor has **Allow edits by maintainers** enabled on the PR (the default). When they have disabled it, the workflow fails loud with a 👎 reaction and an explanation comment.
-
-Re-invoking `/autofix` after a successful apply is a safe no-op — the workflow detects the already-applied state via `git apply --check --reverse` and reacts ✅ without pushing.
-
-**Sensitive paths.** The apply workflow refuses any patch that touches `.github/` (workflow files, CODEOWNERS, dependabot config). A malicious PR could ship a custom prettier or ESLint config that reformats workflow YAML; if accepted, those edits would be pushed under `contents: write` without human review. Apply formatter changes to files under `.github/` manually in a normal commit so they get the same review every other workflow change gets.
-
 ## AI-assisted contributions
 
 If you use coding agents, follow project context files (e.g. `AGENTS.md`, `CLAUDE.md`) and avoid drive-by refactors unrelated to the issue. Prefer incremental, test-backed changes.
-
-## Releases
-
-Two publish workflows ship `gitnexus` to npm:
-
-- **Stable** (`.github/workflows/publish.yml`) — triggered by pushing any `v*`
-  tag. Publishes to the `latest` dist-tag with a changelog-backed GitHub
-  release. Maintainers are expected to tag from `main` as a convention; the
-  workflow itself does not enforce branch reachability.
-- **Release Candidate** (`.github/workflows/release-candidate.yml`) — runs on
-  every push to `main` (typically a merged PR) plus manual dispatch. Docs-only
-  changes are skipped via `paths-ignore`. Publishes to the `rc` dist-tag with
-  version `X.Y.Z-rc.N` and a GitHub prerelease, where:
-  - `X.Y.Z` is selected automatically. On push (and on dispatch with
-    `bump: auto`, the default) the workflow **continues the active rc cycle**:
-    if the registry already has `X.Y.Z-rc.*` versions with `X.Y.Z` > current
-    `latest`, it reuses the highest such base; otherwise it patch-bumps
-    from `latest`. Dispatching with `bump: patch|minor|major` **resets**
-    the cycle from `latest`.
-  - `N` is auto-incremented against existing `X.Y.Z-rc.*` entries on the
-    registry. First rc for a given base is `rc.1`.
-  - After the npm publish succeeds, the workflow calls `docker.yml` as a
-    reusable workflow to build and push the corresponding RC Docker images
-    (e.g. `ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1`, mirrored to
-    `docker.io/akonlabs/gitnexus:1.7.0-rc.1`). The images are signed
-    with Cosign; the OIDC identity is `docker.yml@refs/heads/main` (the
-    caller's ref — see README.md § Docker for the verify command).
-
-  Idempotency: the workflow pushes an `rc/<HEAD_SHA>` marker tag and a
-  `v<RC>` release tag **atomically, before** calling `npm publish`. The guard
-  refuses to re-run once the marker exists, so a post-publish failure will
-  not mint a duplicate rc for the same commit. The `v<RC>` tag points at a
-  detached release commit whose `package.json` matches the npm tarball
-  exactly (traceable releases). Recovery after a partial failure:
-
-  ```bash
-  git push --delete origin rc/<HEAD_SHA> v<RC>
-  # then redispatch the workflow with force: true
-  ```
-
-  **Docker-only partial failure:** if `publish` succeeds (npm tarball + tags
-  are live) but the `docker` job subsequently fails (e.g. GHCR flakiness),
-  the npm RC is already published and the `rc/<HEAD_SHA>` marker is in place.
-  Re-running `release-candidate.yml` with `force: true` will abort at the
-  "Version already exists on npm" guard. To recover without cutting a new RC:
-
-  ```bash
-  # 1. Manually trigger only the docker workflow, passing the existing RC tag:
-  gh workflow run docker.yml --ref main -f tag=v<RC_VERSION>
-  # (requires a workflow_dispatch trigger on docker.yml — see note below)
-  ```
-
-  Because `docker.yml` intentionally has no `workflow_dispatch` (images are
-  tag-driven by design), the practical recovery options are:
-  - Wait for the next commit on `main`, which will cut a new RC that includes
-    the Docker build.
-  - Manually run `docker build` + `docker push` locally and sign with Cosign
-    against the same digest.
-  - Delete `rc/<HEAD_SHA>` and `v<RC>` tags, then redispatch with `force: true` to re-run the full RC pipeline (cuts a new RC number).
-
-The rc workflow never moves `latest`. To verify after a change, inspect dist-tags:
-
-```bash
-npm view gitnexus dist-tags
-```

DoD.md

@@ -1,209 +0,0 @@
-# Definition of Done — GitNexus
-
-Last reviewed: 2026-04-23 · Version: 2.0.0
-
-This document defines the repo-wide completion bar for production-ready changes in GitNexus. It is the stable baseline. Implementation prompts, agent behavior, and review workflows may add task-specific checks, but they must never weaken this bar.
-
-Use it together with:
-
-- `AGENTS.md` — agent-facing rules of engagement
-- `GUARDRAILS.md` — hard safety constraints
-- `CONTRIBUTING.md` — contributor workflow
-- `TESTING.md` — test strategy and coverage expectations
-- `ARCHITECTURE.md` — pipeline boundaries, Call-Resolution DAG, LanguageProvider contract
-
-## 1. Scope and Intent
-
-A change is **Done** when it is correct, safely integrated, appropriately tested, operationally sound, and a net improvement to the codebase — not merely "the code compiles and a test passes."
-
-This DoD applies to:
-
-- CLI, MCP, and HTTP-bridge behavior in `gitnexus/`
-- Browser UI in `gitnexus-web/`
-- Shared contracts in `gitnexus-shared/`
-- CI workflows, release pipelines, and repo-level docs
-
-Out of scope: full agent personas, step-by-step implementation prompts, verbose review formatting rules, repo walkthroughs already covered elsewhere, temporary task-specific acceptance criteria. Those belong in prompts, PR templates, or other repo docs.
-
-## 2. Core Definition of Done
-
-Every change must satisfy **every relevant item** below. If an item does not apply, say so explicitly in the PR description.
-
-### 2.1 Correctness and Completeness
-
-- [ ] The requested behavior is implemented end-to-end in the **real runtime path** for the affected surface — no dead code, partial wiring, test-only shims, or "works in isolation but not in production" seams.
-- [ ] Edge cases relevant to the changed surface are handled or explicitly documented as out of scope.
-- [ ] Error handling is proportionate: inputs at system boundaries (user input, external APIs, filesystem, process spawn) are validated; internal, framework-guaranteed paths are trusted.
-- [ ] The change produces the same result on re-run (idempotent where expected) and does not rely on accidental ordering.
-
-### 2.2 Architecture and Placement
-
-- [ ] The change is placed in the correct package and layer:
-  - `gitnexus/` for CLI, MCP, HTTP bridge, ingestion, graph, and runtime logic
-  - `gitnexus-web/` for browser UI (thin client — no WASM workers, all queries via HTTP API)
-  - `gitnexus-shared/` for shared contracts, types, and constants
-- [ ] Pipeline and architecture boundaries remain explicit. Shared ingestion code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` hooks (see `AGENTS.md` and `ARCHITECTURE.md` § Call-Resolution DAG).
-- [ ] No hidden cross-phase coupling; no leaking of language-specific logic into shared infrastructure without a documented architectural reason.
-- [ ] Runtime and graph behavior are consistent — the real source of truth is fixed at the source, not symptom-patched in a downstream layer.
-- [ ] Direct imports from `gitnexus-shared` are used. No barrel re-exports introduced to paper over drift between packages.
-
-### 2.3 Design and Readability
-
-- [ ] The implementation is the **smallest correct solution** for the requirement. No speculative abstraction, unnecessary indirection, clever but hard-to-follow control flow, or unrelated cleanup.
-- [ ] Naming, control flow, ownership, and extension points are clear enough that the next contributor can extend the code without archaeology.
-- [ ] Comments are minimal and useful — they explain intent, invariants, contracts, or non-obvious constraints. No stale comments, placeholder comments, narrated code, commented-out code, or "what" comments where a good name would do.
-- [ ] No copy-paste duplication created for convenience; no premature deduplication of three similar lines.
-
-### 2.4 Contracts and Compatibility
-
-- [ ] Existing contracts (types in `gitnexus-shared/`, CLI flags, MCP tools/resources, HTTP routes, graph node/edge shapes, persisted IDs) are preserved unless the task explicitly requires a contract change.
-- [ ] Any contract change is intentional, explicit, and reflected in **every direct consumer** in the same change, with types aligned end-to-end.
-- [ ] Persisted data changes (graph schema, IDs, embeddings) are backward-compatible or accompanied by a documented migration / reindex path.
-- [ ] If user-visible behavior, public usage, CLI help, or README examples change, the relevant docs, examples, help text, or migration notes are updated in the same change.
-
-### 2.5 Security
-
-- [ ] No new injection surfaces (command, path, SQL/Cypher-style, prompt) introduced on paths that consume untrusted input.
-- [ ] No secrets, tokens, or credentials committed to the repo, to logs, or to error messages.
-- [ ] Filesystem access honors the repo-scope and indexed-repo boundaries documented in `AGENTS.md` and `GUARDRAILS.md`.
-- [ ] Third-party dependencies added or bumped are justified, from reputable sources, and do not regress the supply-chain posture.
-
-### 2.6 Performance and Resource Use
-
-- [ ] No repeated avoidable work, unnecessary scans, unnecessary round-trips, unbounded caches, or obvious hot-path regressions.
-- [ ] Tree-sitter buffer sizing follows the adaptive 512KB–32MB convention (`getTreeSitterBufferSize`) — do not hard-code new buffer sizes.
-- [ ] Memory and handle lifecycles are explicit: database handles (LadybugDB) close cleanly, no dangling process watchers, no leaked tree-sitter parsers.
-- [ ] Long-running or large-graph paths remain bounded or are measurably streamed; degradation on large real repos is considered, not assumed benign.
-
-### 2.7 Tests
-
-- [ ] Tests cover the **real changed path** — they would fail if behavior, wiring, or contracts were broken, not only if a mock were misconfigured.
-- [ ] Integration tests hit a real database where the production path does; do not introduce mocks that hide migration or schema drift.
-- [ ] Assertions are meaningful. Use `toBe` / `toEqual` for exact expectations; avoid `toBeGreaterThanOrEqual` and other bounds-only assertions that mask regressions.
-- [ ] Fixtures are realistic enough for the risk of the change — a one-file fixture is not sufficient for a pipeline-wide behavior change.
-- [ ] New tests are deterministic and do not depend on network, clock, or host-specific paths without explicit isolation.
-
-### 2.8 Observability and Operability
-
-- [ ] Errors surfaced to users or callers are actionable: they name what failed, what input was involved (without leaking secrets), and how to recover where possible.
-- [ ] Logging is proportionate — no noisy debug logs left in hot paths, no silent catches that swallow diagnostics.
-- [ ] CLI exit codes and MCP tool responses are correct for each outcome (success, user error, internal error).
-- [ ] Progress reporting (`PipelineProgress` and similar shared contracts) remains accurate after the change.
-
-### 2.9 Reversibility and Risk
-
-- [ ] The change has a clear rollback story: revert is safe, or migration is accompanied by a documented rollback / reindex procedure.
-- [ ] Residual risks, compatibility impacts, and operational concerns are either resolved or **clearly stated** in the PR description.
-- [ ] Destructive or hard-to-reverse operations (graph rebuild, schema change, `git` state manipulation) are opt-in or guarded.
-
-## 3. Agent-Assisted Workflow Guardrails
-
-When the change is produced with or reviewed by an AI agent, the following additional gates apply:
-
-- [ ] **Scope match.** The final diff matches the intended symbols, files, and processes — no speculative refactors, unrelated formatting churn, or collateral edits outside the task scope.
-- [ ] **Evidence-based edits.** Claims about repo state are verified against the current code, not trusted from memory or stale documentation.
-- [ ] **Impact analysis.** Where GitNexus graph tooling is available and relevant, impact of non-trivial symbol, contract, or runtime-path changes is checked **before** editing.
-- [ ] **Embeddings preserved.** If an indexed repo already has embeddings and re-analysis is required, embeddings are preserved — not accidentally dropped by a destructive reindex.
-- [ ] **No false-done.** "Done" is claimed only after the Validation Baseline below has been run or any gap is explicitly named. Green tests on an unrelated path do not constitute validation.
-- [ ] **Five-axis self-review** before handing off: correctness, readability, architecture, security, performance.
-
-## 4. Validation Baseline
-
-Run the commands relevant to the touched area. If something cannot be run in the current environment, state it explicitly in the handoff.
-
-### 4.1 Build ordering
-
-- [ ] `gitnexus-shared/` dist is built before consuming packages are typechecked or tested (CI uses the `setup-gitnexus` action for this — local runs must match).
-
-### 4.2 If `gitnexus/` changed
-
-- [ ] `cd gitnexus && npx tsc --noEmit`
-- [ ] `cd gitnexus && npm test`
-- [ ] `cd gitnexus && npx prettier --check .` for files in the diff (pre-commit runs the affected-tests subset; do not expand scope)
-
-### 4.3 If `gitnexus-web/` changed
-
-- [ ] `cd gitnexus-web && npx tsc -b --noEmit`
-- [ ] `cd gitnexus-web && npm test`
-- [ ] `cd gitnexus-web && npm run test:e2e` when browser flows or user-facing UI behavior changed
-
-### 4.4 If `gitnexus-shared/` changed
-
-- [ ] Shared package builds cleanly (`npm run build` in `gitnexus-shared/`)
-- [ ] Dependent packages still typecheck and test after the shared change — verify both CLI and web consumers together
-
-### 4.5 If CI workflows or release pipelines changed
-
-- [ ] The workflow passes a dry-run or triggered run before merge; concurrency (`cancel-in-progress`) and the `setup-gitnexus` action remain wired correctly.
-- [ ] `CHANGELOG.md` is **not** edited here — it is owned by the release process.
-
-## 5. Review Gates
-
-A reviewer (human or agent) should be able to answer **yes** to each of the following before approving:
-
-1. **Correctness** — Does the change do what it claims on the real runtime path?
-2. **Readability** — Will the next contributor understand this in six months without asking?
-3. **Architecture** — Is it in the right package, layer, and phase? Are boundaries respected?
-4. **Security** — No new injection, leak, or trust-boundary violation?
-5. **Performance** — No obvious regression on realistic inputs?
-6. **Tests** — Would a regression in the changed behavior fail loudly?
-7. **Scope** — Does the diff match the intended change, with no unrelated churn?
-
-## 6. "Not Done" Signals
-
-A change is **not** Done if any of the following is true, even if CI is green:
-
-- The runtime path is not actually exercised by the tests.
-- A contract drifted between `gitnexus/`, `gitnexus-web/`, and `gitnexus-shared/` and only one side was updated.
-- A language-specific concern leaked into shared ingestion code.
-- The diff contains unrelated reformatting, refactors, or cleanup beyond the stated task.
-- Logs, comments, or TODOs were added as placeholders for work not done.
-- The change depends on a manual step that is not documented.
-- `CHANGELOG.md` was edited during PR work.
-- Pre-commit, prettier, or typecheck was bypassed without explicit justification.
-
-## 7. Task-Specific DoD Template
-
-Use this in implementation and review prompts. Keep it short and tailor it to the actual change:
-
-```md
-# Definition of Done for this implementation
-
-- [ ] Runtime wiring is complete for the affected path.
-- [ ] Requested behavior is correct and relevant contracts are preserved or explicitly updated.
-- [ ] The design stays scoped, readable, and proportionate to the task.
-- [ ] Tests prove the changed behavior and catch broken wiring.
-- [ ] Required validation for touched packages has been run, or any gap is explicitly noted.
-- [ ] Repo boundaries, security, performance, and operational safety are respected.
-- [ ] The diff contains only the intended change — no unrelated churn.
-```
-
-## 8. How to Use This File in Claude Review
-
-Reference this file as the repo-wide completion bar. Add a task-specific review instruction such as:
-
-```md
-Review this change against `DoD.md` and the repo docs (`AGENTS.md`, `GUARDRAILS.md`,
-`CONTRIBUTING.md`, `TESTING.md`, `ARCHITECTURE.md`). Treat `DoD.md` as the minimum
-bar for production readiness. Flag anything that is partially wired, contract-unsafe,
-under-tested, architecturally misplaced, scope-creeping, or harder to maintain than
-necessary. Apply the five-axis review gate: correctness, readability, architecture,
-security, performance.
-```
-
-## 9. Evolution
-
-This DoD is living. Revisit it when:
-
-- A class of incident slips past it (add a gate).
-- A gate becomes consistently ceremonial without catching issues (remove or merge it).
-- The architecture evolves in a way that changes what "done" means (update placement, validation, or contracts sections).
-
-Track material updates in the changelog below. Keep the file tight — if it grows past a single read-in-one-sitting, something has drifted into the wrong place.
-
-## Changelog
-
-| Date       | Version | Change                                                                                                                                                        |
-| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 2026-04-23 | 2.0.0   | Restructured into numbered sections; added Security, Observability, Reversibility, Agent-Assisted Guardrails, Review Gates, Not-Done Signals; expanded validation baseline (shared-first build, prettier, CI workflow checks). |
-| 2026-04-13 | 1.0.0   | Initial repo-wide Definition of Done.                                                                                                                         |

Dockerfile.cli

@@ -1,71 +0,0 @@
-ARG BUILDPLATFORM
-ARG TARGETPLATFORM
-# Pinned npm version used to replace the bundled npm in the upstream Node
-# image. Bumping requires a coordinated update in Dockerfile.web and
-# gitnexus/Dockerfile.test so all images bootstrap the same npm.
-ARG NPM_VERSION=11.14.1
-
-# -- Builder -----------------------------------------------------------
-# Native modules (tree-sitter-*, onnxruntime-node, node-gyp builds for
-# tree-sitter-proto / tree-sitter-swift) require python3 + a C/C++ toolchain.
-# node:22-bookworm-slim
-FROM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS builder
-ARG NPM_VERSION
-
-WORKDIR /app
-
-RUN npx --yes npm@${NPM_VERSION} install -g npm@${NPM_VERSION}
-
-# Toolchain for node-gyp / native builds.
-RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ git && rm -rf /var/lib/apt/lists/*
-
-# Build gitnexus-shared first - gitnexus depends on it as a workspace.
-COPY gitnexus-shared/package.json gitnexus-shared/package-lock.json ./gitnexus-shared/
-RUN npm ci --prefix gitnexus-shared
-COPY gitnexus-shared ./gitnexus-shared
-RUN rm -f gitnexus-shared/tsconfig.tsbuildinfo
-RUN npm run build --prefix gitnexus-shared
-
-# Copy the full gitnexus package before installing - `npm ci` triggers
-# `postinstall` (patches tree-sitter-swift, builds the vendored
-# tree-sitter-proto) and `prepare` (compiles TypeScript via scripts/build.js),
-# both of which need the source tree.
-COPY gitnexus ./gitnexus
-RUN npm ci --prefix gitnexus
-
-# Drop dev dependencies for a smaller runtime layer.
-RUN npm prune --omit=dev --prefix gitnexus
-
-# -- Runtime -----------------------------------------------------------
-# node:22-bookworm-slim
-FROM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS runtime
-
-# curl for the healthcheck; git so `gitnexus` can clone repos at runtime.
-RUN apt-get update && apt-get install -y --no-install-recommends curl git && rm -rf /var/lib/apt/lists/* \
-    && rm -rf /usr/local/lib/node_modules/npm \
-    && rm -rf /usr/local/lib/node_modules/corepack \
-    && rm -f /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack
-
-WORKDIR /app
-
-# Pre-create the data directory and hand it to the unprivileged `node` user
-# so the bind-mounted volume is writable without root.
-RUN mkdir -p /data/gitnexus && chown -R node:node /data
-
-COPY --from=builder --chown=node:node /app/gitnexus/dist ./gitnexus/dist
-COPY --from=builder --chown=node:node /app/gitnexus/node_modules ./gitnexus/node_modules
-COPY --from=builder --chown=node:node /app/gitnexus/package.json ./gitnexus/package.json
-COPY --from=builder --chown=node:node /app/gitnexus/scripts/install-duckdb-extension.mjs ./gitnexus/scripts/install-duckdb-extension.mjs
-COPY --from=builder --chown=node:node /app/gitnexus/vendor ./gitnexus/vendor
-
-USER node
-
-# The web UI defaults to http://localhost:4747 - keep that contract.
-ENV GITNEXUS_HOME=/data/gitnexus \
-    NODE_ENV=production \
-    PORT=4747
-
-EXPOSE 4747
-
-# Bind to 0.0.0.0 so the server is reachable from the host's mapped port.
-CMD ["node", "gitnexus/dist/cli/index.js", "serve", "--host", "0.0.0.0", "--port", "4747"]

Dockerfile.web

@@ -1,48 +0,0 @@
-ARG BUILDPLATFORM
-ARG TARGETPLATFORM
-# Pinned npm version — keep in sync with Dockerfile.cli and
-# gitnexus/Dockerfile.test.
-ARG NPM_VERSION=11.14.1
-
-# node:22-bookworm-slim
-FROM --platform=$BUILDPLATFORM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS builder
-ARG NPM_VERSION
-
-WORKDIR /app
-
-RUN npx --yes npm@${NPM_VERSION} install -g npm@${NPM_VERSION}
-
-COPY gitnexus-shared/package.json gitnexus-shared/package-lock.json ./gitnexus-shared/
-RUN npm ci --prefix gitnexus-shared
-
-COPY gitnexus-shared ./gitnexus-shared
-RUN npm run build --prefix gitnexus-shared
-
-COPY gitnexus/package.json ./gitnexus/
-
-COPY gitnexus-web/package.json gitnexus-web/package-lock.json ./gitnexus-web/
-RUN npm ci --prefix gitnexus-web
-
-COPY gitnexus-web ./gitnexus-web
-RUN npm run build --prefix gitnexus-web
-
-# node:22-bookworm-slim
-FROM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS runtime
-
-RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/* \
-    && rm -rf /usr/local/lib/node_modules/npm \
-    && rm -rf /usr/local/lib/node_modules/corepack \
-    && rm -f /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack
-
-WORKDIR /app
-
-COPY --from=builder /app/gitnexus-web/dist ./dist
-COPY docker-server.mjs ./docker-server.mjs
-
-RUN chown -R node:node /app
-
-USER node
-
-EXPOSE 4173
-
-CMD ["node", "docker-server.mjs"]

GUARDRAILS.md

@@ -1,75 +1,72 @@
-# Guardrails — GitNexus
+# Guardrails — GitNexus (repo + agents)
 
-Rules for **human contributors** and **AI agents**. Complements `AGENTS.md` (workflows) and `CONTRIBUTING.md` (PR process).
+Rules for **human contributors** and **AI agents** working on this codebase or publishing artifacts. These complement `AGENTS.md` / `CLAUDE.md` (which focus on GitNexus-in-GitNexus workflows).
 
-## Scope (least privilege)
+## Scope (typical agent session)
 
-- **Read:** Source, tests, docs, public config as needed.
-- **Write:** Only files required for the fix or feature; no unrelated formatting or refactors.
-- **Execute:** Tests, typecheck, documented CLI commands. No destructive commands on user data without approval.
-- **Off-limits:** Other people's machines, production deployments you don't own, credentials you lack permission to use.
+When automating changes in this repository, treat scope as **least privilege**:
 
-Maintainer may widen scope per task.
+- **Read:** Source, tests, docs, public config as needed for the task.  
+- **Write:** Only files required for the requested fix or feature; avoid unrelated formatting or refactors.  
+- **Execute:** Tests, typecheck, and documented CLI commands; do not run destructive commands on user data outside the repo without explicit approval.  
+- **Off-limits:** Other people’s machines, production deployments you don’t own, and credentials you didn’t receive permission to use.
+
+Adjust explicitly if the maintainer defines a different scope for a task.
 
 ---
 
 ## Non-negotiables
 
-1. **Never commit secrets** — API keys, tokens, real `.env` values, private URLs, session cookies. Use `.env.example` with placeholders.
-2. **Never rename with find-and-replace** in GitNexus-indexed projects — use `rename` MCP tool with `dry_run: true` first, review `graph` vs `text_search` edits. No separate `gitnexus rename` CLI exists.
-3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
-4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
-5. **Preserve embeddings** — plain `npx gitnexus analyze` now preserves any embeddings recorded in `.gitnexus/meta.json` (the previous behavior wiped them). Use `--embeddings` to also generate vectors for new/changed nodes; use `--drop-embeddings` only when an explicit wipe is intended (e.g., model swap).
+1. **Never commit secrets** — API keys, tokens, `.env` with real values, private URLs, or session cookies. Use `.env.example` with placeholders only.  
+2. **Never rename symbols with blind find-and-replace** when working in a GitNexus-indexed project — use the **`rename` MCP tool** with **`dry_run: true` first**, then review `graph` vs `text_search` edits. (There is no separate `gitnexus rename` CLI; renaming goes through MCP or editor integration.)  
+3. **Run impact analysis before editing shared symbols** — use **`impact`** (upstream) for functions/classes/methods others call; do not ignore **HIGH** / **CRITICAL** risk without maintainer sign-off.  
+4. **Prefer `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.  
+5. **Preserve embeddings** — if `.gitnexus/meta.json` shows embeddings, run `npx gitnexus analyze --embeddings` when refreshing the index; plain `analyze` can drop them.
 
 ---
 
 ## Signs (recurring failure patterns)
 
-Format: **Trigger → Instruction → Reason**. Append new Signs when the same mistake repeats.
+Use this format: **Trigger → Instruction → Reason**.  
+Append new Signs here when the same mistake repeats (e.g. CI broken twice the same way).
 
-### Stale graph after edits
+### Sign: Stale graph after edits
 
-- **Trigger:** MCP warns index is behind `HEAD`, or search doesn't match latest commit.
-- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used). Runs incrementally by default — the pipeline parses every file every run (cross-file resolution requires it), but tree-sitter dispatch is skipped for unchanged file chunks via the content-addressed cache, and only changed-file rows (plus their importers, transitively) are rewritten in LadybugDB.
-- **Why:** Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.
+- **Trigger:** MCP or resources warn the index is behind `HEAD`, or code search doesn’t match latest commit.  
+- **Instruction:** Run `npx gitnexus analyze` from the repo root (plus `--embeddings` if the project used them).  
+- **Reason:** Tools query LadybugDB built at last analyze; git changes are invisible until re-indexed.
 
-### Index seems corrupt or "incremental" is misbehaving
+### Sign: Embeddings vanished after analyze
 
-- **Trigger:** `analyze` produces unexpected results, or `meta.json.incrementalInProgress` is set, or the index is in a half-state after a crash.
-- **Do:** `npx gitnexus analyze --force` to rebuild from scratch. The dirty-flag check forces this automatically when a previous incremental run didn't complete cleanly, but `--force` is the manual escape hatch. Safe to delete `.gitnexus/parse-cache.json` at any time — content-addressed, will be regenerated.
-- **Why:** Incremental writeback is selective DB row replacement; if the on-disk state is inconsistent for any reason, a full rebuild is the cheapest path back to a known-good index.
+- **Trigger:** Semantic search quality drops; `stats.embeddings` in `.gitnexus/meta.json` is 0 after a refresh.  
+- **Instruction:** Re-run `npx gitnexus analyze --embeddings` and confirm `meta.json` reflects stored embeddings.  
+- **Reason:** Embedding generation is opt-in; analyze without the flag does not preserve prior vectors.
 
-### Embeddings vanished after analyze
+### Sign: MCP lists no repos
 
-- **Trigger:** Semantic search quality drops; `stats.embeddings` in `meta.json` is 0 after refresh.
-- **Do:** Re-run `npx gitnexus analyze --embeddings` to regenerate. Check the analyze log for a `Warning: could not load cached embeddings` line — if present, the cache restore failed (corrupt DB / schema mismatch) and the rebuild had nothing to preserve. If you intentionally passed `--drop-embeddings`, this is expected.
-- **Why:** Plain `analyze` preserves prior vectors by re-inserting them after the rebuild; the only ways to end up at zero are an explicit `--drop-embeddings`, a cache-load failure (now logged), or a model/dimension change that invalidates the cache.
+- **Trigger:** MCP stderr says no indexed repos.  
+- **Instruction:** Run `npx gitnexus analyze` in the target repository; verify `npx gitnexus list` shows it.  
+- **Reason:** The MCP server discovers repos via `~/.gitnexus/registry.json`, populated by analyze.
 
-### MCP lists no repos
+### Sign: Wrong repo in multi-repo setups
 
-- **Trigger:** MCP stderr says no indexed repos.
-- **Do:** `npx gitnexus analyze` in the target repo; verify `npx gitnexus list` shows it.
-- **Why:** MCP discovers repos via `~/.gitnexus/registry.json`, populated by analyze.
+- **Trigger:** Query/impact results clearly belong to another project.  
+- **Instruction:** Call `list_repos`, then pass **`repo`** on subsequent tools (or use per-workspace MCP config).  
+- **Reason:** Default target may be ambiguous when multiple repos are registered.
 
-### Wrong repo in multi-repo setups
+### Sign: LadybugDB lock / “database busy”
 
-- **Trigger:** Query/impact results belong to another project.
-- **Do:** Call `list_repos`, then pass `repo` on subsequent tools.
-- **Why:** Default target is ambiguous when multiple repos are registered.
-
-### LadybugDB lock / "database busy"
-
-- **Trigger:** Errors opening `.gitnexus/lbug` while MCP and analyze both run.
-- **Do:** Stop overlapping processes (one writer at a time). Retry analyze or restart MCP.
-- **Why:** Embedded DB expects single-process ownership.
+- **Trigger:** Errors opening `.gitnexus/lbug` while MCP and analyze both run.  
+- **Instruction:** Stop overlapping processes; one writer at a time. Retry analyze or restart MCP.  
+- **Reason:** Embedded DB expects single-process ownership of the store.
 
 ---
 
 ## Publishing & supply chain
 
-- **npm:** Do not publish from unreviewed automation. Bump version intentionally; tag releases to match `package.json`.
-- **Dependencies:** Minimal, auditable `package.json` changes; run tests and CI after lockfile updates.
-- **License:** PolyForm Noncommercial 1.0.0 — do not relicense without maintainer approval.
+- **npm:** Do not publish from unreviewed automation; follow maintainer release process. Bump version intentionally; tag releases to match `package.json`.  
+- **Dependencies:** Prefer minimal, auditable changes to `package.json`; run tests and CI after lockfile updates.  
+- **License:** This project ships under **PolyForm Noncommercial 1.0.0** — do not relicense or imply a different license in docs or metadata without maintainer approval.
 
 ---
 
@@ -77,15 +74,15 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
 
 Stop and ask a **human maintainer** when:
 
-- Impact analysis shows HIGH/CRITICAL risk and the task still requires the change.
-- You need to alter CI, release, or security-sensitive config.
-- Requirements conflict (e.g. "speed up analyze" vs "must keep all embeddings on huge repo").
+- Impact analysis shows **HIGH** / **CRITICAL** risk and the task still requires the change.  
+- You need to alter **CI**, **release**, or **security-sensitive** config.  
+- Requirements conflict (e.g. “speed up analyze” vs “must keep all embeddings on huge repo”).  
 - You are unsure whether data loss is acceptable (`clean`, forced migrations, schema changes).
 
 ---
 
 ## Related docs
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow
-- [RUNBOOK.md](RUNBOOK.md) — commands for recovery
-- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations
+- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow.  
+- [RUNBOOK.md](RUNBOOK.md) — commands for recovery.  
+- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations.

MIGRATION.md

@@ -1,49 +1,5 @@
 # Migration Guide
 
-## `impact` tool may now return `{ status: 'ambiguous' }` (PR #888, issue #470)
-
-Before this change the `impact` MCP tool silently picked the first match
-when the `target` name hit multiple symbols (Class → Interface → Function
-→ Method → Constructor priority UNION). This often produced analysis for
-the wrong symbol with no signal back to the caller.
-
-After this change, when the resolver finds more than one viable match
-and the caller supplied none of `target_uid` / `file_path` / `kind`,
-`impact` returns a disambiguation response shaped like:
-
-```json
-{
-  "status": "ambiguous",
-  "message": "Found N symbols matching '<target>'. Use target_uid, file_path, or kind to disambiguate.",
-  "target": { "name": "<target>" },
-  "direction": "upstream",
-  "impactedCount": 0,
-  "risk": "UNKNOWN",
-  "candidates": [
-    { "uid": "...", "name": "...", "kind": "Function", "filePath": "...", "line": 42, "score": 0.76 }
-  ]
-}
-```
-
-### Do I need to migrate?
-
-**Probably not, but check for assumptions.** Callers that unconditionally
-read `result.byDepth` / `result.summary` / `result.affected_processes`
-without first checking `result.status` will now see `undefined` in the
-ambiguous case. The fix is to branch on `result.status === 'ambiguous'`
-first and follow up with `target_uid` (preferred) or `file_path` / `kind`.
-
-The `context` tool's ambiguous response is a strict superset of the
-existing shape — every candidate gains a `score` field, no existing field
-has changed. No migration required for `context` callers.
-
-### What happens on re-index?
-
-Nothing — this is an MCP-surface change only. The graph schema, indexer,
-and stored data are untouched.
-
----
-
 ## OVERRIDES → METHOD_OVERRIDES (PR #642)
 
 The `OVERRIDES` relationship type has been renamed to `METHOD_OVERRIDES` for

README.md

@@ -1,5 +1,5 @@
 # GitNexus
-**⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
+⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
 
 <div align="center">
 
@@ -9,7 +9,7 @@
 
   <h2>Join the official Discord to discuss ideas, issues etc!</h2>
 
-  <a href="https://discord.gg/MgJrmsqr62">
+  <a href="https://discord.gg/AAsRVT6fGb">
     <img src="https://img.shields.io/discord/1477255801545429032?color=5865F2&logo=discord&logoColor=white" alt="Discord"/>
   </a>
   <a href="https://www.npmjs.com/package/gitnexus">
@@ -18,9 +18,6 @@
   <a href="https://polyformproject.org/licenses/noncommercial/1.0.0/">
     <img src="https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg" alt="License: PolyForm Noncommercial"/>
   </a>
-  <a href="https://securityscorecards.dev/viewer/?uri=github.com/abhigyanpatwari/GitNexus">
-    <img src="https://api.securityscorecards.dev/projects/github.com/abhigyanpatwari/GitNexus/badge" alt="OpenSSF Scorecard"/>
-  </a>
 
   <p><strong>Enterprise (SaaS & Self-hosted)</strong> - <a href="https://akonlabs.com">akonlabs.com</a></p>
 
@@ -39,7 +36,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
 > *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.
 
-**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with Goliath models.
+**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with goliath models.
 
 ---
 
@@ -109,8 +106,6 @@ That's it. This indexes the codebase, installs agent skills, registers Claude Co
 
 To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-> **Faster install (no C++ toolchain needed):** set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before `npm install -g gitnexus` to skip the native `tree-sitter-dart` and `tree-sitter-proto` builds. Dart/Proto files won't be parsed, but install completes in seconds without `python3`/`make`/`g++`. Strict `=1` only — any other value falls through to the rebuild.
-
 ### MCP Setup
 
 `gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
@@ -120,12 +115,12 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | Editor                | MCP | Skills | Hooks (auto-augment) | Support        |
 | --------------------- | --- | ------ | -------------------- | -------------- |
 | **Claude Code** | Yes | Yes    | Yes (PreToolUse + PostToolUse) | **Full** |
-| **Cursor**      | Yes | Yes    | Yes (postToolUse, [manual install](gitnexus-cursor-integration/README.md#hook-install)) | **Full** |
+| **Cursor**      | Yes | Yes    | —                   | MCP + Skills   |
 | **Codex**       | Yes | Yes    | —                   | MCP + Skills   |
 | **Windsurf**    | Yes | —     | —                   | MCP            |
 | **OpenCode**    | Yes | Yes    | —                   | MCP + Skills   |
 
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that auto-reindex after commits.
 
 ## Community Integrations
 
@@ -140,8 +135,6 @@ Built by the community — not officially maintained, but worth checking out.
 
 If you prefer manual configuration:
 
-> **Recommended for fastest startup:** install gitnexus globally (`npm i -g gitnexus`) and run `gitnexus setup` — this writes an absolute-path MCP config that bypasses `npx` entirely. The pinned-`npx` snippets below are a quickstart fallback; on a cold cache the `npx` install can exceed Claude Code's `MCP_TIMEOUT` default (~30s).
-
 **Claude Code** (full support — MCP + skills + hooks):
 
 ```bash
@@ -201,10 +194,8 @@ gitnexus analyze --force         # Force full re-index
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
-gitnexus analyze --skip-git        # Index folders that are not Git repositories
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
-gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
 gitnexus list                    # List all indexed repositories
@@ -214,27 +205,18 @@ gitnexus clean --all --force     # Delete all indexes
 gitnexus wiki [path]             # Generate repository wiki from knowledge graph
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
 gitnexus wiki --base-url <url>   # Wiki with custom LLM API base URL
-gitnexus publish                 # Notify the understand-quickly registry (opt-in, see below)
 
 # Repository groups (multi-repo / monorepo service tracking)
-gitnexus group create <name>                                   # Create a repository group
-gitnexus group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `gitnexus list`)
-gitnexus group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
-gitnexus group list [name]                                     # List groups, or show one group's config
-gitnexus group sync <name>                                     # Extract contracts and match across repos/services
+gitnexus group create <name>     # Create a repository group
+gitnexus group add <name> <repo> # Add a repo to a group
+gitnexus group remove <name> <repo> # Remove a repo from a group
+gitnexus group list [name]       # List groups, or show one group's config
+gitnexus group sync <name>       # Extract contracts and match across repos/services
 gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
 gitnexus group query <name> <q>  # Search execution flows across all repos in a group
 gitnexus group status <name>     # Check staleness of repos in a group
 ```
 
-If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `gitnexus analyze --worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget.
-
-#### Publishing to understand-quickly (opt-in)
-
-[`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly) is a public registry of code-knowledge graphs that lists `gitnexus@1` as a first-class format. After registering your repo once (`npx @understand-quickly/cli add` or the [wizard](https://looptech-ai.github.io/understand-quickly/add.html)), `gitnexus publish` fires a single `repository_dispatch` event so the registry resyncs your entry on demand instead of waiting for the nightly job.
-
-It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained GitHub PAT with `Repository dispatches: write` on the registry repo. Nothing else happens; no graph file is uploaded. See the [protocol spec](https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md) for the full contract.
-
 ### What Your AI Agent Gets
 
 **16 tools** exposed via MCP (11 per-repo + 5 group):
@@ -338,182 +320,21 @@ flowchart TD
 
 ## Web UI (browser-based)
 
-A client-side graph explorer and AI chat — your code never leaves your machine.
+A fully client-side graph explorer and AI chat. No server, no install — your code never leaves the browser.
 
-**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — run `npx gitnexus@latest serve` locally and the page auto-connects to your local backend.
+**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — drag & drop a ZIP and start exploring.
 
 <img width="2550" height="1343" alt="gitnexus_img" src="https://github.com/user-attachments/assets/cc5d637d-e0e5-48e6-93ff-5bcfdb929285" />
 
-Or run the frontend locally:
+Or run locally:
 
 ```bash
 git clone https://github.com/abhigyanpatwari/gitnexus.git
 cd gitnexus/gitnexus-shared && npm install && npm run build
 cd ../gitnexus-web && npm install
 npm run dev
-# Then in another terminal, start the backend the frontend connects to:
-npx gitnexus@latest serve
 ```
 
-## Docker
-
-The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`. Each image is published to both **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature — so pick whichever registry you prefer:
-
-| Purpose                                                                | GHCR (default in `docker-compose.yaml`)       | Docker Hub mirror                           |
-| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- |
-| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest`     | `akonlabs/gitnexus:latest`                  |
-| Static web UI (port `4173`)                                            | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest`              |
-
-> **Heads-up — image rename.** Earlier releases published the web UI under
-> `ghcr.io/abhigyanpatwari/gitnexus`. Starting with the introduction of the
-> bundled backend, that slug now hosts the CLI/server image and the UI moved
-> to `ghcr.io/abhigyanpatwari/gitnexus-web`. The previous tags remain
-> available for pulling, but new versions are only published under the new
-> slugs. Update your `docker run` / compose files accordingly (or just adopt
-> the bundled compose).
-
-### One-command setup
-
-```bash
-docker compose up -d
-```
-
-This starts the server on `http://localhost:4747` and the web UI on
-`http://localhost:4173`. The UI auto-detects the server because the browser
-runs on the host and reaches the container via the mapped port.
-
-A named volume (`gitnexus-data`) persists the global registry, indexes, and
-cloned repos at `/data/gitnexus` inside the server container. To make repos on
-your host machine indexable, set `WORKSPACE_DIR` before bringing the stack up:
-
-```bash
-WORKSPACE_DIR=$HOME/code docker compose up -d
-# Inside the server container the directory is mounted read-only at /workspace.
-docker compose exec gitnexus-server gitnexus index /workspace/my-repo
-```
-
-### Direct `docker run`
-
-```bash
-# Server
-docker run --rm -d \
-  --name gitnexus-server \
-  -p 4747:4747 \
-  -v gitnexus-data:/data/gitnexus \
-  ghcr.io/abhigyanpatwari/gitnexus:latest
-
-# Web UI
-docker run --rm -d \
-  --name gitnexus-web \
-  -p 4173:4173 \
-  ghcr.io/abhigyanpatwari/gitnexus-web:latest
-```
-
-Optional env file (override image tags, container names, ports, workspace dir):
-
-```bash
-cp .env.example .env
-docker compose --env-file .env up -d
-```
-
-### Versioning & supply-chain protection
-
-The Docker images are version-locked to the npm package:
-
-- Stable images are **only published from `vX.Y.Z` git tags** (via `docker.yml`
-  triggered directly by the tag push), and the workflow refuses to build unless
-  the tag exactly matches `gitnexus/package.json`'s version. So
-  `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` (and its Docker Hub mirror
-  `akonlabs/gitnexus:1.6.2`) is byte-for-byte the same release as
-  `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`.
-  Both registries receive the same digest from a single build step, so you can
-  pull from either and the signature verifies identically.
-- Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each
-  RC npm release. They are built by `release-candidate.yml` calling `docker.yml`
-  as a reusable workflow after the RC tag is created and pushed.
-- `:latest` is auto-promoted only from non-prerelease tags by the Docker
-  metadata action, so it always points at a real, npm-published version.
-
-Both images are signed with [Cosign keyless signing][cosign-keyless] using the
-workflow's GitHub OIDC identity, and shipped with build provenance and SBOM
-attestations. **This is your protection against supply-chain attacks**: even if
-an attacker republishes a same-named image elsewhere (or somehow pushes to a
-typo-squatted registry), they cannot forge a Cosign signature tied to
-`abhigyanpatwari/GitNexus`'s `docker.yml`. Always verify before pulling into
-sensitive environments:
-
-**Stable releases** — signed from the `v*` tag ref:
-
-```bash
-cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
-  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
-  --certificate-oidc-issuer https://token.actions.githubusercontent.com
-
-# Same signature verifies the Docker Hub mirror (identical digest):
-cosign verify docker.io/akonlabs/gitnexus:1.6.2 \
-  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
-  --certificate-oidc-issuer https://token.actions.githubusercontent.com
-```
-
-The regex pins the certificate identity to this repo's `docker.yml` workflow
-**run from a `v*` tag** — rejecting unsigned images, images signed by other
-workflows, and images signed from unprotected refs. It is identical for both
-registries because both sets of tags were signed at the same digest in one
-workflow run.
-
-**Release candidates** — signed from `refs/heads/main` (the caller's ref when
-`release-candidate.yml` invokes `docker.yml` as a reusable workflow):
-
-```bash
-cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
-  --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
-  --certificate-oidc-issuer https://token.actions.githubusercontent.com
-```
-
-You can also inspect the build provenance and SBOM:
-
-```bash
-cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
-  --predicate-type https://slsa.dev/provenance/v1
-```
-
-#### Kubernetes: enforce signatures at admission
-
-For Kubernetes deployments, ship the bundled
-[`ClusterImagePolicy`](deploy/kubernetes/cluster-image-policy.yaml) so the
-[Sigstore policy-controller][policy-controller] rejects any GitNexus pod whose
-image is not signed by this repo's `docker.yml` running from a `vX.Y.Z` tag —
-the same identity the `cosign verify` snippet above pins.
-
-```bash
-# 1. Install the controller (one-time, cluster-wide)
-helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
-helm install policy-controller -n cosign-system --create-namespace \
-  sigstore/policy-controller
-
-# 2. Opt your namespace in
-kubectl label namespace <your-ns> policy.sigstore.dev/include=true
-
-# 3. Apply the policy
-kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml
-```
-
-After this, attempting to deploy an unsigned image — or one signed by anything
-other than `abhigyanpatwari/GitNexus`'s `docker.yml` at a `v*` tag — fails the
-admission webhook before a pod is ever created. This turns the verifiable
-signature into an enforced policy, which is the supply-chain control most
-clusters actually need.
-
-[cosign-keyless]: https://docs.sigstore.dev/cosign/signing/overview/
-[policy-controller]: https://docs.sigstore.dev/policy-controller/overview/
-
-### Files
-
-- [Dockerfile.web](Dockerfile.web) — builds `gitnexus-shared` and `gitnexus-web`, then serves the production frontend.
-- [Dockerfile.cli](Dockerfile.cli) — builds the CLI/server (with its native deps) and runs `gitnexus serve --host 0.0.0.0`.
-- [docker-compose.yaml](docker-compose.yaml) — starts both signed images side by side.
-- [.env.example](.env.example) — overrides for image names, container names, ports, and the workspace mount.
-
 The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, LadybugDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos.
 
 **Local Backend Mode:** Run `gitnexus serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.

SECURITY.md

@@ -1,67 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-GitNexus is developed on `main`. Security fixes are applied to the latest released minor on npm (`gitnexus`) and to the published Docker images (`Dockerfile.cli`, `Dockerfile.web`). Older minors are not back-patched.
-
-## Reporting a Vulnerability
-
-**Please do not open a public GitHub issue for security reports.**
-
-Use **GitHub Private Vulnerability Reporting** for this repository:
-
-→ https://github.com/abhigyanpatwari/GitNexus/security/advisories/new
-
-Please include:
-
-- A description of the issue and its potential impact
-- Steps to reproduce (a minimal repro repo or commit hash if possible)
-- The affected version(s) — `npm view gitnexus version`, image digest, or commit SHA
-- Any suggested mitigation
-
-### What to expect
-
-- **Acknowledgement:** best-effort within 5 business days, subject to maintainer capacity.
-- **Triage:** we will confirm whether the report is in scope, request clarifications if needed, and propose a fix timeline.
-- **Disclosure:** coordinated. We will agree on a disclosure date with you before publishing an advisory.
-
-### Scope
-
-In scope:
-
-- The `gitnexus` CLI and MCP server (`gitnexus/`)
-- The `gitnexus-web` thin client (`gitnexus-web/`)
-- The `gitnexus-shared` types package (`gitnexus-shared/`)
-- The published Docker images (`Dockerfile.cli`, `Dockerfile.web`)
-- GitHub Actions workflows in `.github/workflows/`
-
-Out of scope:
-
-- Vulnerabilities in third-party dependencies that we have no influence over (please report upstream; if a viable mitigation exists at the GitNexus layer, that's in scope).
-- Issues requiring physical access to a developer machine or a compromised local environment.
-- Theoretical attacks without a practical exploit against a default GitNexus deployment.
-
-## Recommended Hardening for Forks and Self-Hosted Deployments
-
-If you fork GitNexus or self-host it, we recommend enabling the following in your repository's **Settings → Code security and analysis**:
-
-- **Private vulnerability reporting** — the channel described above.
-- **Dependabot alerts** — alerts on advisories affecting your dependencies.
-- **Dependabot security updates** — automated PRs for security patches (this repo's `.github/dependabot.yml` already covers version updates).
-- **Secret scanning** and **Push protection** — blocks pushes that introduce known secret patterns. Defense-in-depth on top of the in-CI Gitleaks scan documented below.
-- **Code scanning** — surfaces SARIF results from CodeQL, Trivy, Scorecard, and zizmor in one place.
-
-## Automated Scans Running in CI
-
-This repository runs the following scans automatically. Findings appear under the repository's **Security → Code scanning** tab.
-
-| Scan | Tool | Trigger | Action on finding |
-|------|------|---------|-------------------|
-| Static analysis (JS/TS, Python) | [CodeQL](https://github.com/github/codeql-action) | PR, `main` push, weekly | Advisory (Security tab) |
-| Dependency vulnerabilities (PR diff) | [`dependency-review-action`](https://github.com/actions/dependency-review-action) | PR | **Blocks PR** at `high+` severity |
-| Secret scanning | [Gitleaks](https://github.com/gitleaks/gitleaks-action) | PR, `main` push | **Blocks PR** on default rules |
-| Supply-chain posture | [OpenSSF Scorecard](https://github.com/ossf/scorecard-action) | Weekly, `main` push | Advisory (Security tab + public badge) |
-| Workflow lint | [zizmor](https://github.com/woodruffw/zizmor) | PR (touching `.github/**`) | **Blocks PR** at `high+` severity |
-| Container image scan | [Trivy](https://github.com/aquasecurity/trivy-action) | Weekly, `main` push | Advisory (Security tab) |
-
-Dependency version updates are managed separately by Dependabot — see `.github/dependabot.yml`.

TESTING.md

@@ -20,9 +20,9 @@ From repository root, unless noted:
 cd gitnexus
 npm install
 npm run build
-npm test                    # full suite: vitest run
-npm run test:unit           # unit only: vitest run test/unit
+npm test                    # unit: vitest run test/unit
 npm run test:integration    # integration suite
+npm run test:all
 npm run test:coverage
 npx tsc --noEmit            # typecheck (matches CI)
 ```
@@ -42,11 +42,8 @@ npm run test:e2e            # Playwright (requires gitnexus serve + npm run dev)
 
 A husky pre-commit hook (`.husky/pre-commit`) runs automatically on every `git commit`:
 
-1. **Formatting** — `lint-staged` runs prettier on staged files
-2. **`gitnexus-web/` files staged** → `tsc -b --noEmit`
-3. **`gitnexus/` files staged** → `tsc --noEmit`
-
-Tests do **not** run in the pre-commit hook — they run in CI (`ci-tests.yml`) only.
+- **`gitnexus-web/` files staged** → `tsc -b --noEmit` + `vitest run`
+- **`gitnexus/` files staged** → `tsc --noEmit` + `vitest run --project default`
 
 Skip with `git commit --no-verify` (use sparingly).
 
@@ -80,7 +77,7 @@ Re-run the full relevant suite when:
 
 GitHub Actions (`.github/workflows/ci.yml`) orchestrate:
 
-- **`ci-quality.yml`** — prettier format check, eslint lint, `tsc --noEmit` for `gitnexus/`, `tsc -b --noEmit` for `gitnexus-web/`
+- **`ci-quality.yml`** — `tsc --noEmit` for `gitnexus/` + `tsc -b --noEmit` for `gitnexus-web/`
 - **`ci-tests.yml`** — `vitest run` with coverage (ubuntu) + cross-platform (macOS, Windows)
 - **`ci-e2e.yml`** — Playwright E2E tests, gated on `gitnexus-web/**` changes
 

deploy/kubernetes/cluster-image-policy.yaml

@@ -1,76 +0,0 @@
-# Sigstore policy-controller ClusterImagePolicy for GitNexus container images.
-#
-# This enforces — at admission time — that every Pod pulling a
-# `ghcr.io/abhigyanpatwari/gitnexus` or `gitnexus-web` image is using a build
-# that was Cosign-keyless-signed by this repository's `docker.yml` workflow
-# running from a `vX.Y.Z` git tag. Unsigned images, images signed by other
-# workflows, and images signed from unprotected refs (e.g. `main`, PR branches)
-# are rejected.
-#
-# Prerequisites
-# -------------
-# 1. Install the Sigstore policy-controller in your cluster (Helm):
-#
-#      helm repo add sigstore https://sigstore.github.io/helm-charts
-#      helm repo update
-#      helm install policy-controller -n cosign-system --create-namespace \
-#        sigstore/policy-controller
-#
-# 2. Opt namespaces in to verification:
-#
-#      kubectl label namespace <your-ns> policy.sigstore.dev/include=true
-#
-# 3. Apply this policy:
-#
-#      kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml
-#
-# After this, `kubectl run --image=ghcr.io/abhigyanpatwari/gitnexus:<tag>` in
-# any opted-in namespace will only succeed if the image carries a valid
-# Sigstore signature with the pinned identity.
-#
-# References
-# - https://docs.sigstore.dev/policy-controller/overview/
-# - https://github.com/sigstore/policy-controller
-apiVersion: policy.sigstore.dev/v1beta1
-kind: ClusterImagePolicy
-metadata:
-  name: gitnexus-signed-images
-spec:
-  # Apply to both published GitNexus images on both registries. Image
-  # references always carry a tag or digest at admission time, so these globs
-  # cover every `gitnexus:<tag>`, `gitnexus@sha256:...`, `gitnexus-web:<tag>`,
-  # and `gitnexus-web@sha256:...` reference on either GHCR or Docker Hub.
-  # The Docker Hub images are byte-for-byte mirrors of the GHCR images (same
-  # build, same digest, same Cosign signature), so the same keyless identity
-  # authority verifies both.
-  images:
-    - glob: 'ghcr.io/abhigyanpatwari/gitnexus*'
-    # Docker Hub references can appear in three forms at admission time
-    # (`docker.io/...`, `index.docker.io/...`, and bare `akonlabs/...` with
-    # the default registry implied). List all three so the policy cannot be
-    # sidestepped by the choice of registry prefix. The Docker Hub namespace
-    # is `akonlabs` rather than `abhigyanpatwari` because the Docker Hub org
-    # differs from the GitHub org.
-    - glob: 'docker.io/akonlabs/gitnexus*'
-    - glob: 'index.docker.io/akonlabs/gitnexus*'
-    - glob: 'akonlabs/gitnexus*'
-  authorities:
-    - name: gitnexus-cosign-keyless
-      keyless:
-        # Public-good Sigstore Fulcio root.
-        url: https://fulcio.sigstore.dev
-        identities:
-          # Pin both the OIDC issuer (GitHub Actions) AND the exact workflow
-          # path running from a `vX.Y.Z` (or `vX.Y.Z-prerelease`) tag. Same
-          # regex the README's `cosign verify` example uses; it rejects:
-          #   * unsigned images
-          #   * signatures from any other repo / workflow
-          #   * signatures from non-tag refs (main, PRs, release branches)
-          #   * signatures from arbitrary non-semver tags
-          - issuer: https://token.actions.githubusercontent.com
-            subjectRegExp: ^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$
-      # Cross-check the signature against the public Rekor transparency log,
-      # so an attacker who briefly compromised Fulcio cannot retroactively
-      # mint a signature without leaving a public, append-only audit record.
-      ctlog:
-        url: https://rekor.sigstore.dev

docker-compose.yaml

@@ -1,45 +0,0 @@
-services:
-  gitnexus-server:
-    image: ${SERVER_IMAGE:-ghcr.io/abhigyanpatwari/gitnexus:latest}
-    container_name: ${SERVER_CONTAINER_NAME:-gitnexus-server}
-    # Map the server to the same host port the web UI expects by default
-    # (http://localhost:4747). The browser runs on the host, so the UI's
-    # built-in default works without any reconfiguration.
-    ports:
-      - '${SERVER_HOST_PORT:-4747}:4747'
-    volumes:
-      # Persist the global registry, indexes, and cloned repos across runs.
-      - gitnexus-data:/data/gitnexus
-      # Optional: mount a host workspace so `gitnexus index <path>` can see
-      # repos you already have on disk. The default points at an empty
-      # `./workspace/` sibling that compose will create on first start —
-      # it intentionally does NOT bind-mount the repo root, which would
-      # expose `.git`, `.env`, and CI secrets to the container.
-      # Override with `WORKSPACE_DIR=/abs/path/to/your/repos`.
-      - ${WORKSPACE_DIR:-./workspace}:/workspace:ro
-    restart: unless-stopped
-    healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost:4747/api/health']
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 15s
-
-  gitnexus-web:
-    image: ${WEB_IMAGE:-ghcr.io/abhigyanpatwari/gitnexus-web:latest}
-    container_name: ${WEB_CONTAINER_NAME:-gitnexus-web}
-    ports:
-      - '${WEB_HOST_PORT:-4173}:4173'
-    depends_on:
-      gitnexus-server:
-        condition: service_healthy
-    restart: unless-stopped
-    healthcheck:
-      test: ['CMD', 'curl', '-f', 'http://localhost:4173/']
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 10s
-
-volumes:
-  gitnexus-data:

docker-server.mjs

@@ -1,120 +0,0 @@
-import { createReadStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
-import { createServer } from 'node:http';
-import { extname, isAbsolute, normalize, relative, resolve } from 'node:path';
-
-const host = '0.0.0.0';
-const port = Number(process.env.PORT || '4173');
-const root = resolve(process.cwd(), 'dist');
-
-const contentTypes = {
-  '.css': 'text/css; charset=utf-8',
-  '.html': 'text/html; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.map': 'application/json; charset=utf-8',
-  '.png': 'image/png',
-  '.svg': 'image/svg+xml',
-  '.txt': 'text/plain; charset=utf-8',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-};
-
-// Static asset server for the gitnexus-web Docker image.
-//
-// Path-injection containment: the request handler is intentionally a single
-// inline pipeline with no helper functions on the path-data flow. Each
-// filesystem sink (stat, createReadStream) is immediately preceded by the
-// canonical `path.relative` containment check that CodeQL's
-// `js/path-injection` query recognizes as a sanitizer barrier:
-//
-//     const rel = relative(root, candidate);
-//     if (rel.startsWith('..') || isAbsolute(rel)) reject;
-//     // candidate is now proven inside `root`
-//
-// Earlier iterations of this file used a helper (`resolveWithinRoot`) and a
-// `startsWith(root + sep)` check. Both were semantically correct but neither
-// was recognized by CodeQL: `startsWith(root + sep)` is not in the analyzer's
-// barrier-pattern set, and helper-based sanitization is not followed across
-// the request handler's reassignment paths in vanilla JS. The inline-at-sink
-// shape below is the documented analyzer-friendly idiom.
-const server = createServer(async (req, res) => {
-  const urlPath = req.url?.split('?')[0] || '/';
-
-  let decoded;
-  try {
-    decoded = decodeURIComponent(urlPath);
-  } catch {
-    res.writeHead(400);
-    res.end('Bad request');
-    return;
-  }
-  if (decoded.includes('\0')) {
-    res.writeHead(400);
-    res.end('Bad request');
-    return;
-  }
-
-  const cleanPath = normalize(decoded.replace(/^\/+/, ''));
-  const initialPath = resolve(root, cleanPath);
-
-  // Sanitizer barrier #1 — guards the first stat() sink.
-  const initialRel = relative(root, initialPath);
-  if (initialRel.startsWith('..') || isAbsolute(initialRel)) {
-    res.writeHead(400);
-    res.end('Bad request');
-    return;
-  }
-
-  try {
-    const initialStat = await stat(initialPath).catch(() => null);
-
-    // Pick the path we actually serve. Note: any branch reassigns to a
-    // freshly-resolved path; the next sanitizer barrier re-validates.
-    let finalPath;
-    if (initialStat?.isDirectory()) {
-      finalPath = resolve(initialPath, 'index.html');
-    } else if (!initialStat?.isFile()) {
-      finalPath = resolve(root, 'index.html');
-    } else {
-      finalPath = initialPath;
-    }
-
-    // Sanitizer barrier #2 — guards both the second stat() and the
-    // createReadStream() sinks. No reassignment of finalPath happens
-    // between this guard and either sink, so the analyzer can prove
-    // containment for both.
-    const finalRel = relative(root, finalPath);
-    if (finalRel.startsWith('..') || isAbsolute(finalRel)) {
-      res.writeHead(400);
-      res.end('Bad request');
-      return;
-    }
-
-    const finalStat = await stat(finalPath).catch(() => null);
-    if (!finalStat?.isFile()) {
-      res.writeHead(404);
-      res.end('Not found');
-      return;
-    }
-
-    res.writeHead(200, {
-      'Cache-Control': finalPath.includes('/assets/')
-        ? 'public, max-age=31536000, immutable'
-        : 'no-cache',
-      'Content-Type': contentTypes[extname(finalPath)] || 'application/octet-stream',
-      'Cross-Origin-Opener-Policy': 'same-origin',
-      'Cross-Origin-Embedder-Policy': 'require-corp',
-    });
-    const stream = createReadStream(finalPath);
-    stream.on('error', () => res.destroy());
-    stream.pipe(res);
-  } catch (error) {
-    res.writeHead(500);
-    res.end(error instanceof Error ? error.message : 'Internal server error');
-  }
-});
-
-server.listen(port, host, () => {
-  console.log(`gitnexus-web listening on http://${host}:${port}`);
-});

docker-server.test.mjs

@@ -1,124 +0,0 @@
-import { mkdir, mkdtemp, rm, unlink, writeFile } from 'node:fs/promises';
-import http, { createServer } from 'node:http';
-import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { after, before, it } from 'node:test';
-import assert from 'node:assert/strict';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const serverScript = join(__dirname, 'docker-server.mjs');
-
-function getFreePort() {
-  return new Promise((resolve) => {
-    const s = createServer();
-    s.listen(0, '127.0.0.1', () => {
-      const { port } = s.address();
-      s.close(() => resolve(port));
-    });
-  });
-}
-
-function rawGet(port, path) {
-  return new Promise((resolve, reject) => {
-    const req = http.request({ host: '127.0.0.1', port, path }, (res) => {
-      let body = '';
-      res.setEncoding('utf8');
-      res.on('data', (chunk) => {
-        body += chunk;
-      });
-      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body }));
-    });
-    req.on('error', reject);
-    req.end();
-  });
-}
-
-async function waitForServer(port, retries = 30) {
-  for (let i = 0; i < retries; i++) {
-    try {
-      await rawGet(port, '/');
-      return;
-    } catch {
-      await new Promise((r) => setTimeout(r, 100));
-    }
-  }
-  throw new Error('Server did not start in time');
-}
-
-let tmpDir, serverPort, child;
-
-before(async () => {
-  tmpDir = await mkdtemp(join(tmpdir(), 'gitnexus-docker-test-'));
-  const distDir = join(tmpDir, 'dist');
-  const assetsDir = join(distDir, 'assets');
-  await mkdir(assetsDir, { recursive: true });
-  await writeFile(join(distDir, 'index.html'), '<html><body>spa</body></html>');
-  await writeFile(join(assetsDir, 'app.abc123.js'), 'console.log("app")');
-
-  serverPort = await getFreePort();
-  child = spawn(process.execPath, [serverScript], {
-    cwd: tmpDir,
-    env: { ...process.env, PORT: String(serverPort) },
-    stdio: 'pipe',
-  });
-  child.on('error', (err) => {
-    throw err;
-  });
-
-  await waitForServer(serverPort);
-});
-
-after(async () => {
-  child?.kill();
-  if (tmpDir) await rm(tmpDir, { recursive: true, force: true });
-});
-
-it('serves a valid asset with immutable cache header', async () => {
-  const res = await rawGet(serverPort, '/assets/app.abc123.js');
-  assert.equal(res.status, 200);
-  assert.match(res.headers['cache-control'], /immutable/);
-  assert.equal(res.headers['cross-origin-opener-policy'], 'same-origin');
-  assert.equal(res.headers['cross-origin-embedder-policy'], 'require-corp');
-});
-
-it('serves SPA fallback for unknown routes', async () => {
-  const res = await rawGet(serverPort, '/some/unknown/route');
-  assert.equal(res.status, 200);
-  assert.match(res.body, /spa/);
-  assert.match(res.headers['cache-control'], /no-cache/);
-});
-
-it('rejects path traversal with 400', async () => {
-  const res = await rawGet(serverPort, '/../../../etc/passwd');
-  assert.equal(res.status, 400);
-});
-
-it('rejects percent-encoded null bytes with 400', async () => {
-  const res = await rawGet(serverPort, '/foo%00bar');
-  assert.equal(res.status, 400);
-});
-
-it('rejects percent-encoded path traversal with 400', async () => {
-  // %2e%2e%2f decodes to '../'. Without the path.relative inline barrier,
-  // a naive string check on the raw URL would let this through and only
-  // the lexical-decoded path.resolve would catch it. Confirm the barrier
-  // does its job after decodeURIComponent.
-  const res = await rawGet(serverPort, '/%2e%2e%2f%2e%2e%2fetc%2fpasswd');
-  assert.equal(res.status, 400);
-});
-
-it('rejects malformed percent-encoding with 400', async () => {
-  // %GG is not a valid percent-encoded sequence — decodeURIComponent throws.
-  // The handler's try/catch around decode must convert this to a 400 rather
-  // than an unhandled rejection.
-  const res = await rawGet(serverPort, '/foo%GGbar');
-  assert.equal(res.status, 400);
-});
-
-it('returns 404 when dist/index.html is missing', async () => {
-  await unlink(join(tmpDir, 'dist', 'index.html'));
-  const res = await rawGet(serverPort, '/nonexistent-page');
-  assert.equal(res.status, 404);
-});

docs/guides/microservices-grpc.md

@@ -1,300 +0,0 @@
-# Using GitNexus across gRPC microservices
-
-## When to use this guide
-
-This guide is for teams whose product lives in **several separate Git repositories** — one per service — and whose services talk to each other over **gRPC** (possibly alongside HTTP and message topics). GitNexus indexes each repo independently, then a _group_ stitches the per-repo indexes into a single cross-repo view that the `impact`, `query`, and `context` tools can traverse. If your services live in one monorepo, much of this still applies — set each service as a member of a group and use the `service` prefix to scope queries — but the walkthrough assumes the harder multi-repo case.
-
-## Mental model
-
-- Each repository has its own `.gitnexus/` index (a LadybugDB graph of symbols, relationships, processes). `gitnexus analyze` in each repo produces that index completely independently.
-- A **group** is a higher-level construct stored at `~/.gitnexus/groups/<group>/` that references the per-repo indexes by their registry name.
-- Sync-time extractors walk each member repo and emit **contracts** — provider or consumer records keyed by a canonical `contractId` (`grpc::auth.AuthService/Login`, `http::GET::/orders`, etc.).
-- The sync step matches providers and consumers that share a `contractId` and writes **cross-links** to `<groupDir>/contracts.json`. Those cross-links are what lets `impact({repo: "@<group>", target: "X"})` hop from one repo into another.
-- Contracts come from three places: automatic contract extractors (`grpc-extractor`, `http-route-extractor`, `topic-extractor`), a manifest escape hatch (`config.links` in `group.yaml`), and — for same-name symbol matches where no contract is declared — the exact-match matching cascade in [`matching.ts`](../../gitnexus/src/core/group/matching.ts).
-- Each repo stays editable and re-indexable on its own. Re-run `gitnexus analyze` in a repo when it changes, then `gitnexus group sync <group>` to refresh `contracts.json`. `gitnexus group status` reports which members are stale.
-
-## Prerequisites
-
-- GitNexus installed and runnable as `gitnexus` or `npx gitnexus` (see the root [README.md](../../README.md)).
-- Each service repository checked out locally. No requirement that they share a parent directory — the group references them by registry name.
-- Write access to `~/.gitnexus/` (the default gitnexus home; see `getDefaultGitnexusDir` in [`storage.ts`](../../gitnexus/src/core/group/storage.ts)).
-
-## Step-by-step walkthrough
-
-The example uses three services — a TypeScript API gateway, a Go orders service, and a Python inventory service — with gRPC between them. The gateway is an `orders` consumer; the orders service is both an `orders` provider and an `inventory` consumer; the inventory service is an `inventory` provider.
-
-### 1. Index each repository
-
-Run `analyze` from inside each service repo (or pass the path). The CLI surface lives in [`gitnexus/src/cli/analyze.ts`](../../gitnexus/src/cli/analyze.ts) and is wired in [`gitnexus/src/cli/index.ts`](../../gitnexus/src/cli/index.ts).
-
-```bash
-cd ~/code/gateway && npx gitnexus analyze
-cd ~/code/orders  && npx gitnexus analyze
-cd ~/code/inventory && npx gitnexus analyze
-```
-
-Useful flags:
-
-- `--force` — reindex even if up to date.
-- `--embeddings` — generate embedding vectors (needed only if you want semantic search; the exact-match cross-repo cascade does **not** need them).
-- `--name <alias>` — register the repo under a specific alias when two repos share a basename (e.g. two `api/` folders).
-- `--skip-git` — index a checkout that isn't a git repo.
-
-Each run writes a `.gitnexus/` folder in the repo and registers the repo in `~/.gitnexus/registry.json`. Confirm with `npx gitnexus list`.
-
-### 2. Author `group.yaml`
-
-Create the group directory and edit the config. Either use the CLI scaffolder or write the file directly — both produce the same shape consumed by [`config-parser.ts`](../../gitnexus/src/core/group/config-parser.ts).
-
-```bash
-npx gitnexus group create payments-platform
-# or manually:
-mkdir -p ~/.gitnexus/groups/payments-platform
-$EDITOR   ~/.gitnexus/groups/payments-platform/group.yaml
-```
-
-Minimal working `group.yaml`:
-
-```yaml
-version: 1
-name: payments-platform
-description: Gateway + orders + inventory (gRPC)
-
-repos:
-  gateway: gateway
-  orders: orders
-  inventory: inventory
-
-# Only add explicit links when the automatic extractors miss something —
-# see "When automatic extraction isn't enough" below.
-links: []
-
-packages: {}
-
-detect:
-  http: true
-  grpc: true
-  topics: true
-  shared_libs: true
-  embedding_fallback: false
-
-matching:
-  bm25_threshold: 0.7
-  embedding_threshold: 0.65
-  max_candidates_per_step: 3
-  # Exclude noisy paths from cross-link matching (contracts are still extracted)
-  exclude_links_paths: [/ping, /health, /healthcheck]
-  exclude_links_param_only_paths: true
-```
-
-Field notes (schema in [`types.ts`](../../gitnexus/src/core/group/types.ts)):
-
-- `version` — must be `1`. The parser rejects anything else.
-- `name` — required; used for the group directory name and all CLI / MCP calls.
-- `repos` — a mapping from **group path** (a logical name you choose; can be a hierarchy like `backend/orders`) to **registry name** (the name shown by `npx gitnexus list`). Both sides appear throughout the tooling: contract rows use the group path; `@<group>/<groupPath>` routes tools to a single member.
-- `links` — optional manifest escape hatch, one entry per explicit cross-repo contract. Validated by the parser: `from` and `to` must be known repo paths, `type` must be one of `http | grpc | topic | lib | custom`, and `role` must be `provider | consumer`.
-- `detect` — toggles per extractor family. Defaults (set in `config-parser.ts`) turn `http`, `grpc`, `topics`, and `shared_libs` on; disable the ones you don't use to speed up sync.
-- `matching` — thresholds for the matching cascade. The exact match is always run; other strategies depend on indexer state. Two optional fields reduce false-positive cross-links in large groups:
-  - `exclude_links_paths` — list of HTTP paths to exclude from cross-link matching (default `[]`). Contracts at these paths are still extracted and visible in the registry, but they don't produce cross-repo links. Useful for health-check endpoints (`/ping`, `/health`) that every service exposes. Trailing slashes are normalized.
-  - `exclude_links_param_only_paths` — when `true`, exclude routes where every segment is `{param}` (e.g. `/{param}`, `/{param}/{param}`) from cross-link matching (default `false`). Mixed routes like `/users/{param}` are not affected.
-
-### 3. Sync the group
-
-```bash
-npx gitnexus group sync payments-platform --verbose
-```
-
-What this does (see [`sync.ts`](../../gitnexus/src/core/group/sync.ts)):
-
-1. Opens each member's per-repo LadybugDB.
-2. Runs the HTTP, gRPC, and topic extractors against the source files.
-3. Applies manifest `links` through [`manifest-extractor.ts`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts).
-4. Runs the exact-match cascade, joining providers and consumers that share a normalized `contractId`.
-5. Writes `contracts.json` in the group directory.
-
-Flags:
-
-- `--exact-only` — stop after the exact cascade; skip BM25 and embedding fallback.
-- `--skip-embeddings` — run exact plus BM25 but not embedding-based matching.
-- `--allow-stale` — don't warn if a member's index is stale.
-- `--json` — machine-readable output.
-
-The same operation is available over MCP as `group_sync({ name: "payments-platform" })` — see [`tools.ts`](../../gitnexus/src/mcp/tools.ts).
-
-### 4. Inspect the registry
-
-Use `gitnexus group contracts` for the CLI view or read the `gitnexus://group/<name>/contracts` MCP resource for the same data.
-
-```bash
-npx gitnexus group contracts payments-platform --type grpc --json
-```
-
-A shortened response:
-
-```json
-{
-  "contracts": [
-    {
-      "contractId": "grpc::orders.OrderService/PlaceOrder",
-      "type": "grpc",
-      "role": "provider",
-      "repo": "orders",
-      "symbolRef": { "filePath": "internal/grpc/order_server.go", "name": "RegisterOrderServiceServer" },
-      "confidence": 0.8,
-      "meta": { "service": "OrderService", "method": "PlaceOrder", "source": "go_register" }
-    },
-    {
-      "contractId": "grpc::orders.OrderService/PlaceOrder",
-      "type": "grpc",
-      "role": "consumer",
-      "repo": "gateway",
-      "symbolRef": { "filePath": "src/clients/orders.ts", "name": "OrderServiceClient" },
-      "confidence": 0.75,
-      "meta": { "service": "OrderService", "source": "ts_generated_client" }
-    }
-  ],
-  "crossLinks": [
-    {
-      "from": { "repo": "gateway", "symbolUid": "…", "symbolRef": { "filePath": "src/clients/orders.ts", "name": "OrderServiceClient" } },
-      "to":   { "repo": "orders",  "symbolUid": "…", "symbolRef": { "filePath": "internal/grpc/order_server.go", "name": "RegisterOrderServiceServer" } },
-      "type": "grpc",
-      "contractId": "grpc::orders.OrderService/PlaceOrder",
-      "matchType": "exact",
-      "confidence": 1.0
-    }
-  ]
-}
-```
-
-Staleness of the underlying indexes shows up in `npx gitnexus group status payments-platform` or the `gitnexus://group/<name>/status` resource.
-
-### 5. Run cross-repo impact with `@<group>` routing
-
-From any shell (you do **not** have to `cd` into a member repo), the normal `impact` / `query` / `context` tools accept `repo: "@<group>"` to fan out across all members, or `repo: "@<group>/<memberPath>"` to target one member. Routing is implemented in [`resolve-at-member.ts`](../../gitnexus/src/core/group/resolve-at-member.ts) and described in [`tools.ts`](../../gitnexus/src/mcp/tools.ts).
-
-Example MCP calls:
-
-```json
-{"tool": "impact", "arguments": {
-  "repo": "@payments-platform/orders",
-  "target": "PlaceOrder",
-  "direction": "upstream",
-  "crossDepth": 2
-}}
-```
-
-```json
-{"tool": "query", "arguments": {
-  "repo": "@payments-platform",
-  "query": "retry logic around PlaceOrder"
-}}
-```
-
-The CLI equivalents still exist for scripting:
-
-```bash
-npx gitnexus group impact payments-platform \
-  --repo orders --target PlaceOrder --direction upstream --cross-depth 2
-```
-
-Phase 1 walks within the anchor member; Phase 2 hops across the Contract Bridge wherever a cross-link endpoint matches an impacted symbol. See [`cross-impact.ts`](../../gitnexus/src/core/group/cross-impact.ts) for the bridge query.
-
-## How gRPC extraction works
-
-`GrpcExtractor` ([`grpc-extractor.ts`](../../gitnexus/src/core/group/extractors/grpc-extractor.ts)) runs two passes per member repo:
-
-1. **Proto map.** Every `**/*.proto` file is parsed to enumerate `service Foo { rpc Bar(...) }` blocks and (transitively) resolve the package name. Each RPC method becomes a provider contract with `contractId = grpc::<package>.<Service>/<Method>` and `confidence = 0.85`. Parsing uses the vendored `tree-sitter-proto` grammar when available and falls back to a length-preserving manual parser (`extractServiceBlocks`) otherwise, so `.proto` extraction works on platforms where the grammar fails to build.
-2. **Source scan.** Every source file whose extension matches [`GRPC_SCAN_GLOB`](../../gitnexus/src/core/group/extractors/grpc-patterns/index.ts) is parsed by its language plugin:
-
-| Language | Provider signal | Consumer signal |
-|----------|-----------------|-----------------|
-| Go ([`go.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/go.ts)) | `pb.RegisterXxxServer(...)`, `pb.UnimplementedXxxServer` embedded in struct | `pb.NewXxxClient(conn)` |
-| Java ([`java.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/java.ts)) | `extends XxxServiceGrpc.XxxServiceImplBase` (with or without `@GrpcService`) | `XxxServiceGrpc.newBlockingStub(...)`, `newStub(...)` |
-| Python ([`python.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/python.ts)) | `add_XxxServicer_to_server(...)` (bare or `_pb2_grpc.` attribute form) | `XxxStub(channel)` (ignores `Mock`/`Test`/`Fake`/`Stub`) |
-| Node / TS ([`node.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/node.ts)) | NestJS `@GrpcMethod('Service','Method')` | `@GrpcClient` field typed `XxxServiceClient`, `client.getService<X>('Service')`, `new XxxServiceClient(...)`, `new foo.bar.XxxService(...)` in files that call `loadPackageDefinition` |
-
-For each source-scan detection the extractor looks up the short service name in the proto map and picks:
-
-- `grpc::<package>.<Service>/<Method>` when a method is named and the service resolves against the proto map,
-- `grpc::<package>.<Service>/*` (wildcard) when only the service is known, or
-- `grpc::<ServiceName>/*` when no `.proto` is available at all.
-
-Provider detections land at confidence 0.8 (with proto) or 0.65 (without); consumers at 0.75 or 0.55. NestJS `@GrpcMethod` is fixed at 0.8 because the decorator is self-describing.
-
-### Matching
-
-`matching.ts` lowercases the package/service segment before comparing contract ids, so bindings that capitalize names differently (`auth.AuthService` vs `auth.authservice`) still match. Method names are compared case-sensitively because gRPC's wire path is case-sensitive. Service-only wildcards (`grpc::pkg.Svc/*`) match any method on the same service during cross-linking.
-
-### Known limitations
-
-- **Ambiguous proto resolution.** If a short service name exists in more than one `.proto` file and the source-scan hit can't be narrowed down by shared directory segments (`resolveProtoConflict` refuses to guess), the extractor skips contract emission and logs a warning.
-- **Proto packages must be resolvable locally.** Transitive imports that point outside the repo produce an empty package segment, which means the contract id collapses to `grpc::<Service>/<Method>`. Cross-repo matches still work as long as both sides agree on the empty package.
-- **Rewrite rules are not implemented.** If the provider repo writes `grpc::orders.OrderService/PlaceOrder` and the consumer repo writes `grpc::orderspb.OrderService/PlaceOrder`, they won't cross-link automatically. Use `config.links` to declare the correspondence (see below).
-- **One sync = one snapshot.** Contracts are extracted against the indexed snapshot of each repo. Re-index first, then re-sync; the `status` command and resource surface staleness.
-
-## When automatic extraction isn't enough
-
-The escape hatch is the `links` list in `group.yaml`, handled by [`ManifestExtractor`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts). Each entry is a **one-directional** provider/consumer declaration:
-
-```yaml
-version: 1
-name: payments-platform
-repos:
-  gateway: gateway
-  orders: orders
-  inventory: inventory
-
-links:
-  # Explicit gRPC method: use when naming mismatches stop the
-  # automatic matcher from cross-linking.
-  - from: gateway
-    to: orders
-    type: grpc
-    contract: OrderService/PlaceOrder
-    role: consumer
-
-  # Service-level link when you don't want to enumerate methods.
-  - from: orders
-    to: inventory
-    type: grpc
-    contract: InventoryService
-    role: consumer
-
-  # Works for HTTP too — use `METHOD::/path` form for the exact
-  # handler, or just `/path` for a method-agnostic wildcard.
-  - from: gateway
-    to: orders
-    type: http
-    contract: POST::/orders
-    role: consumer
-```
-
-What the manifest extractor does (see [`manifest-extractor.ts`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts)):
-
-1. Builds a canonical `contractId` with `buildContractId` — the same canonicalization used by the automatic extractors, so manifest links cross-match automatic contracts on the other side.
-2. Tries to resolve each side to a real graph symbol (the `Route` node for HTTP, a `Function|Method` / `Class|Interface` for gRPC, a `Package|Module` for `lib`).
-3. If resolution fails, falls back to a deterministic synthetic uid (`manifest::<repo>::<contractId>`) so both sides still line up in cross-impact — name-only links still work when the symbol isn't in the graph.
-4. Emits both a provider and a consumer `StoredContract` (confidence `1.0`, `source: "manifest"`) and a `CrossLink` with `matchType: "manifest"`.
-
-Use `links` for exactly the cases the extractor can't infer: different package names across repos (see #701), hand-rolled transports, cases where the provider repo isn't checked out locally but you still want a record, or any contract whose provider and consumer simply don't share a surface the extractors know how to pattern-match.
-
-History: the manifest extractor used to be silently skipped by the sync pipeline; that was fixed in [#827](https://github.com/abhigyanpatwari/GitNexus/pull/827) (tracking issue #826). If you ever see `config.links` with zero cross-links in `contracts.json`, make sure you're on a build that includes that fix, then re-run `group sync`.
-
-## Troubleshooting
-
-1. **`contracts.json` is empty after a sync.** Either no member repo contained a recognizable gRPC pattern, or the extractors are disabled in `detect`. Confirm `detect.grpc: true` and re-run with `--verbose`.
-2. **A known provider/consumer pair doesn't cross-link.** Most common cause: the package segment differs. Check the raw contract ids with `gitnexus group contracts <name> --unmatched` — if you see two same-method contracts with different package prefixes, add a manifest `links:` entry to bridge them (no automatic rewrite rules yet).
-3. **`matchType: "manifest"` is missing entirely.** The extractor needs `config.links` to be non-empty and the sync pipeline to actually call it — verify you're on a post-#827 build. Empty contract rows for manifest links usually mean `resolveSymbol` couldn't find a graph match; the synthetic uid still lets cross-impact work, it just won't carry a file path.
-4. **Ambiguous proto warnings.** Look for `[grpc-extractor] Ambiguous proto resolution` in the sync logs; that means a service name exists in multiple `.proto` files under the same repo and the path-distance heuristic couldn't pick a winner. Resolve by renaming the service or declaring the intended pairing in `config.links`.
-5. **Cross-impact says "stale".** Both sides need a fresh per-repo index _and_ a fresh group sync. Order matters: `gitnexus analyze` in each changed repo, then `gitnexus group sync <name>`. Use `gitnexus group status <name>` to see which side is behind.
-
-## Related docs and references
-
-- [AGENTS.md](../../AGENTS.md) — authoritative list of MCP tools and resources, including group-mode routing and the `gitnexus://group/…` resources.
-- [ARCHITECTURE.md](../../ARCHITECTURE.md) — overall data flow and the call-resolution DAG that the per-repo indexer uses.
-- [`gitnexus/src/core/group/`](../../gitnexus/src/core/group/) — `service.ts`, `sync.ts`, `config-parser.ts`, `matching.ts`.
-- [`gitnexus/src/core/group/extractors/grpc-extractor.ts`](../../gitnexus/src/core/group/extractors/grpc-extractor.ts) and [`grpc-patterns/`](../../gitnexus/src/core/group/extractors/grpc-patterns/) — gRPC detection.
-- [`gitnexus/src/core/group/extractors/manifest-extractor.ts`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts) — the `config.links` escape hatch.
-- [`gitnexus/src/mcp/tools.ts`](../../gitnexus/src/mcp/tools.ts) — MCP tool schemas (`group_list`, `group_sync`, plus `@<group>` routing on `impact` / `query` / `context`).
-- [`gitnexus/src/cli/group.ts`](../../gitnexus/src/cli/group.ts) — CLI command definitions and flags.
-- Upstream issues: [#701](https://github.com/abhigyanpatwari/GitNexus/issues/701), [#826](https://github.com/abhigyanpatwari/GitNexus/issues/826), [#906](https://github.com/abhigyanpatwari/GitNexus/issues/906).

docs/guides/microservices-thrift.md

@@ -1,185 +0,0 @@
-# Using GitNexus across Apache Thrift microservices
-
-## When to use this guide
-
-Use this guide when several repositories communicate through Apache Thrift and you want GitNexus to trace impact across provider and consumer boundaries. The walkthrough assumes each service is indexed on its own, then joined through a GitNexus group.
-
-This is not a framework integration guide. GitNexus reads portable Thrift IDL and common Java generated-code shapes. Framework-specific wiring, service discovery, deployment metadata, and private annotations belong outside the open-source core.
-
-## Mental model
-
-- `.thrift` files define the canonical service contract. A method in an IDL service becomes a stable contract id in the form `thrift::<namespace>.<Service>/<Method>`.
-- Service wildcard ids in the form `thrift::<namespace>.<Service>/*` are supported as manifest and matching fallback forms when a service-level link is needed.
-- Java generated-code usage points GitNexus toward implementation and call sites. Providers commonly implement generated `Service.Iface`; consumers commonly hold or construct generated service interfaces or clients.
-- Group sync matches provider and consumer contracts with the same id, then cross-repo impact can hop through those links.
-- Framework-specific wiring should be modeled by extractor plugins, manifest links, or downstream integrations rather than hard-coded into core Thrift support.
-
-## Fictional IDL
-
-```thrift
-namespace java billing.v1
-
-struct PlaceOrderRequest {
-  1: string orderId
-  2: double amount
-}
-
-struct PlaceOrderResponse {
-  1: bool accepted
-}
-
-struct GetOrderRequest {
-  1: string orderId
-}
-
-struct GetOrderResponse {
-  1: string orderId
-  2: string status
-}
-
-service OrderService {
-  PlaceOrderResponse PlaceOrder(1: PlaceOrderRequest request)
-  GetOrderResponse GetOrder(1: GetOrderRequest request)
-}
-```
-
-The service methods above produce canonical ids:
-
-- `thrift::billing.v1.OrderService/PlaceOrder`
-- `thrift::billing.v1.OrderService/GetOrder`
-- `thrift::billing.v1.OrderService/*` as a service-level manifest or matching fallback form
-
-## Java provider example
-
-Generated Java code usually exposes an `Iface` interface for the service. A provider implementation can be detected when it implements that generated interface.
-
-```java
-package example.billing;
-
-import billing.v1.GetOrderRequest;
-import billing.v1.GetOrderResponse;
-import billing.v1.OrderService;
-import billing.v1.PlaceOrderRequest;
-import billing.v1.PlaceOrderResponse;
-
-public final class OrderServiceHandler implements OrderService.Iface {
-  @Override
-  public PlaceOrderResponse PlaceOrder(PlaceOrderRequest request) {
-    return new PlaceOrderResponse(true);
-  }
-
-  @Override
-  public GetOrderResponse GetOrder(GetOrderRequest request) {
-    return new GetOrderResponse(request.getOrderId(), "CREATED");
-  }
-}
-```
-
-With the IDL available, GitNexus can connect the implementation to `thrift::billing.v1.OrderService/PlaceOrder` and `thrift::billing.v1.OrderService/GetOrder`.
-
-## Java consumer examples
-
-Consumers are strongest when Java usage can be tied back to the IDL namespace and service.
-
-```java
-package example.checkout;
-
-import billing.v1.OrderService;
-import billing.v1.PlaceOrderRequest;
-
-public final class CheckoutWorkflow {
-  private final OrderService.Iface orders;
-
-  public CheckoutWorkflow(OrderService.Iface orders) {
-    this.orders = orders;
-  }
-
-  public void submit(String orderId) throws Exception {
-    orders.PlaceOrder(new PlaceOrderRequest(orderId, 42.0));
-  }
-}
-```
-
-Some generated-code styles use the generated service type directly while keeping enough IDL context through imports and method calls.
-
-```java
-package example.reporting;
-
-import billing.v1.GetOrderRequest;
-import billing.v1.OrderService;
-
-public final class OrderLookup {
-  private final OrderService.Client client;
-
-  public OrderLookup(OrderService.Client client) {
-    this.client = client;
-  }
-
-  public String status(String orderId) throws Exception {
-    return client.GetOrder(new GetOrderRequest(orderId)).getStatus();
-  }
-}
-```
-
-When IDL context is missing, GitNexus may still emit a weaker consumer signal for generated `Iface` or `Client` shapes, but confidence is lower.
-
-## Group configuration
-
-New group configs enable Thrift contract detection by default. Keep `detect.thrift: true`
-when a group should scan for Thrift contracts, or set it to `false` to skip Thrift
-extraction for that group.
-
-```yaml
-version: 1
-name: billing-platform
-description: Fictional services connected by Apache Thrift
-
-repos:
-  checkout: checkout-service
-  billing: billing-service
-
-links: []
-
-detect:
-  http: true
-  grpc: false
-  thrift: true
-  topics: false
-  shared_libs: true
-```
-
-To disable Thrift extraction explicitly:
-
-```yaml
-detect:
-  thrift: false
-```
-
-After indexing each member repository, run group sync to extract contracts and write cross-repo links:
-
-```bash
-npx gitnexus group sync billing-platform
-```
-
-## Manifest escape hatch
-
-Use manifest links when automatic extraction cannot see a provider or consumer, or when generated code is wrapped behind an abstraction. Write the contract without the `thrift::` prefix; GitNexus canonicalizes it to the full Thrift contract id.
-
-```yaml
-links:
-  - from: checkout
-    to: billing
-    type: thrift
-    contract: billing.v1.OrderService/PlaceOrder
-    role: consumer
-```
-
-GitNexus canonicalizes that manifest entry to `thrift::billing.v1.OrderService/PlaceOrder` and uses it to connect the two repositories.
-
-## Known limitations
-
-- Java detection currently targets v1 generated-code patterns.
-- Maven and POM dependency coordinates are not used for inference.
-- Framework-specific annotations and service discovery metadata are ignored by open-source Thrift extraction.
-- Ambiguous same-name services are skipped instead of guessed.
-- Java consumers without IDL context are lower confidence and limited to generated `Iface` and `Client` shapes.

eslint-rules/require-safe-parse.mjs

@@ -1,95 +0,0 @@
-/**
- * Custom ESLint rule: require `parseSourceSafe(parser, content, ...)` instead
- * of direct `<parser>.parse(<content>, ...)` calls.
- *
- * Background: tree-sitter's Node.js native binding crashes with SIGSEGV on
- * Windows when handed a JS string longer than 32 767 chars. The crash happens
- * inside the binding's V8 string-to-buffer conversion and cannot be intercepted
- * by JavaScript `try/catch`. `parseSourceSafe` (in
- * `gitnexus/src/core/tree-sitter/safe-parse.ts`) routes large inputs through
- * the chunked-callback overload of `parser.parse(input, ...)` which bypasses
- * the broken conversion path. PR #1433 fixed every direct call site at the
- * time; this rule prevents new direct calls from creeping in.
- *
- * The rule is auto-fixable for the call-site rewrite. It does NOT auto-add the
- * import (computing the correct relative path per file is brittle); after the
- * call rewrite runs, the consumer file's `tsc` will complain about an
- * undefined identifier and the developer adds the import. This is the same
- * tradeoff `unused-imports/no-unused-imports` makes in the opposite direction.
- *
- * False-positive suppression:
- * - Skips calls whose receiver is a known non-tree-sitter library (`JSON`,
- *   `URL`, `marked`, `Number`).
- * - Skips calls whose first argument is a string-literal (grammar-load smoke
- *   tests like `_testParser.parse('service X { rpc Y (R) returns (R); }')`).
- * - Skips test files (`.test.ts`/`.test.tsx`/`.spec.ts`).
- * - Skips the `safe-parse.ts` helper itself.
- */
-
-const SKIPPED_RECEIVERS = new Set(['JSON', 'URL', 'marked', 'Number', 'Math']);
-
-export default {
-  meta: {
-    type: 'problem',
-    docs: {
-      description:
-        'Require parseSourceSafe instead of direct tree-sitter `<parser>.parse(content, ...)` calls (Windows SIGSEGV protection)',
-      recommended: true,
-    },
-    fixable: 'code',
-    schema: [],
-    messages: {
-      useSafeParse:
-        'Direct `{{receiver}}.parse(...)` can SIGSEGV on Windows for inputs > 32 767 chars (uncatchable from JS). Use `parseSourceSafe({{receiver}}, ...)` from `core/tree-sitter/safe-parse.js`. Auto-fix rewrites the call; add the missing import yourself.',
-    },
-  },
-  create(context) {
-    const filename = context.filename ?? context.getFilename();
-    // Don't lint the helper itself or test files.
-    if (filename.includes('safe-parse')) return {};
-    if (/[.](?:test|spec)\.tsx?$/.test(filename)) return {};
-
-    const sourceCode = context.sourceCode ?? context.getSourceCode();
-
-    return {
-      CallExpression(node) {
-        const callee = node.callee;
-        if (callee.type !== 'MemberExpression') return;
-        if (callee.computed) return;
-        if (callee.property.type !== 'Identifier') return;
-        if (callee.property.name !== 'parse') return;
-
-        // Skip known non-tree-sitter receivers.
-        if (callee.object.type === 'Identifier' && SKIPPED_RECEIVERS.has(callee.object.name)) {
-          return;
-        }
-
-        // Smoke tests pass a string literal directly; those are trivially safe.
-        const firstArg = node.arguments[0];
-        if (!firstArg) return;
-        if (firstArg.type === 'Literal' && typeof firstArg.value === 'string') return;
-        if (firstArg.type === 'TemplateLiteral' && firstArg.expressions.length === 0) return;
-
-        const receiverText = sourceCode.getText(callee.object);
-        // Receiver-text-shape skip: anything matching well-known JS APIs that
-        // happen to have a `.parse(<expr>)` shape but aren't tree-sitter.
-        if (
-          /^(JSON|URL|marked|Number|Math|Date|globalThis\.JSON)\b/.test(receiverText) ||
-          /\bjson\.parse\b/i.test(receiverText)
-        ) {
-          return;
-        }
-
-        context.report({
-          node,
-          messageId: 'useSafeParse',
-          data: { receiver: receiverText },
-          fix(fixer) {
-            const argsText = node.arguments.map((arg) => sourceCode.getText(arg)).join(', ');
-            return fixer.replaceText(node, `parseSourceSafe(${receiverText}, ${argsText})`);
-          },
-        });
-      },
-    };
-  },
-};

eslint.config.mjs

@@ -3,47 +3,6 @@ import tsParser from '@typescript-eslint/parser';
 import unusedImports from 'eslint-plugin-unused-imports';
 import reactHooks from 'eslint-plugin-react-hooks';
 import prettierConfig from 'eslint-config-prettier';
-import requireSafeParse from './eslint-rules/require-safe-parse.mjs';
-
-// Local plugin hosting custom rules that enforce GitNexus-specific invariants
-// (currently: the Windows-SIGSEGV-safe parser entrypoint).
-const gitnexusLocalPlugin = {
-  rules: {
-    'require-safe-parse': requireSafeParse,
-  },
-};
-
-// Selectors that protect MCP-reachable code from corrupting the JSON-RPC
-// stdio frame stream. The MCP-reachable block below uses these directly;
-// the lbug-adapter file-specific block must spread them in too because
-// ESLint flat config REPLACES (not merges) `no-restricted-syntax` when
-// multiple matching configs target the same file. Extracting to a const
-// makes the dependency mechanical instead of documentation-enforced.
-const mcpStdoutWriteSelectors = [
-  {
-    selector:
-      "MemberExpression[object.type='MemberExpression'][object.object.name='process'][object.property.name='stdout'][property.name='write']",
-    message:
-      'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
-  },
-  {
-    selector:
-      "CallExpression[callee.type='MemberExpression'][callee.object.type='MemberExpression'][callee.object.object.name='process'][callee.object.property.name='stdout'][callee.property.name='write']",
-    message:
-      'Direct process.stdout.write is forbidden in MCP-reachable code. Route diagnostics through console.error or process.stderr.write — the MCP stdio transport owns stdout for JSON-RPC frames.',
-  },
-  {
-    // Catches the canonical destructuring shape:
-    //   const { write } = process.stdout;
-    // (and any other ObjectPattern destructure rooted at process.stdout)
-    // which would otherwise capture a reference to the original write
-    // and bypass the sentinel.
-    selector:
-      "VariableDeclarator[init.type='MemberExpression'][init.object.name='process'][init.property.name='stdout'] > ObjectPattern",
-    message:
-      'Destructuring process.stdout is forbidden in MCP-reachable code — bypasses the sentinel. Use process.stderr.write for diagnostics.',
-  },
-];
 
 export default [
   // Global ignores
@@ -55,7 +14,6 @@ export default [
       'gitnexus/vendor/**',
       'gitnexus-web/src/vendor/**',
       'gitnexus/test/fixtures/**',
-      'gitnexus-web/test/fixtures/**',
       'gitnexus-web/playwright-report/**',
       'gitnexus-web/test-results/**',
       '**/*.d.ts',
@@ -100,64 +58,11 @@ export default [
     },
   },
 
-  // CLI/server packages — `console.log` IS the contract (CLI tool data output
-  // on stdout, e.g. `gitnexus query | jq`; server pretty-printed banners).
-  // Diagnostic logging (`warn`/`error`/`debug`/`info`) goes through pino like
-  // the rest of the codebase.
+  // CLI package — allow console.log (it's a CLI tool)
   {
     files: ['gitnexus/src/cli/**/*.ts', 'gitnexus/src/server/**/*.ts'],
     rules: {
-      'no-console': ['error', { allow: ['log'] }],
-    },
-  },
-
-  // Forcing function for the pino migration. Severity is `error` — the
-  // codebase-wide migration is complete; new `console.*` in core source
-  // must fail lint. CLI/server are exempt above (legitimate stdout output).
-  // Tests, bin scripts, and the logger module itself remain exempt.
-  {
-    files: ['gitnexus/src/**/*.ts'],
-    ignores: ['gitnexus/src/cli/**', 'gitnexus/src/server/**', 'gitnexus/src/core/logger.ts'],
-    rules: {
-      'no-console': 'error',
-    },
-  },
-
-  // MCP-reachable code: forbid stdout-corrupting writes. The MCP stdio
-  // transport writes JSON-RPC frames to stdout; per the spec, the server
-  // MUST NOT write anything to stdout that is not a valid MCP message.
-  // Diagnostics must go to stderr (console.error). Direct process.stdout.write
-  // bypasses the gate and is also forbidden in these dirs.
-  // cli/mcp.ts is included here even though it lives under cli/ — it is the
-  // MCP entrypoint and inherits stricter discipline than the rest of cli/.
-  {
-    files: [
-      'gitnexus/src/mcp/**/*.ts',
-      'gitnexus/src/core/lbug/**/*.ts',
-      'gitnexus/src/core/embeddings/**/*.ts',
-      'gitnexus/src/core/tree-sitter/**/*.ts',
-      'gitnexus/src/cli/mcp.ts',
-    ],
-    rules: {
-      'no-console': ['error', { allow: ['error'] }],
-      'no-restricted-syntax': ['error', ...mcpStdoutWriteSelectors],
-    },
-  },
-
-  // Windows SIGSEGV protection: every tree-sitter parse in `core/` must route
-  // through parseSourceSafe. Direct `<parser>.parse(content, ...)` crashes on
-  // Windows for inputs > 32 767 chars (V8 string-conversion bug, uncatchable
-  // from JS). The rule auto-fixes the call site; the developer adds the
-  // missing import after the fix runs. Out of scope: tests (skipped by the
-  // rule), the helper itself (`safe-parse.ts`), and the `grpc-patterns/proto.ts`
-  // grammar-load smoke test (filtered by string-literal-arg skip in the rule).
-  {
-    files: ['gitnexus/src/core/**/*.ts'],
-    plugins: {
-      gitnexus: gitnexusLocalPlugin,
-    },
-    rules: {
-      'gitnexus/require-safe-parse': 'error',
+      'no-console': 'off',
     },
   },
 
@@ -173,34 +78,6 @@ export default [
     },
   },
 
-  // Prevent direct conn.close() / db.close() in the LadybugDB adapter (#1376).
-  // All close operations must go through safeClose() so the WAL is always
-  // flushed before the connection is released. The sole authorised call site
-  // inside safeClose itself uses an eslint-disable-next-line override.
-  //
-  // ESLint flat config REPLACES (not merges) `no-restricted-syntax` when
-  // multiple matching configs target the same file. lbug-adapter.ts is also
-  // covered by the MCP-reachable block above, so we spread the shared
-  // mcpStdoutWriteSelectors here alongside the safeClose selectors. Without
-  // this, lbug-adapter would silently lose its MCP stdout-write protection.
-  {
-    files: ['gitnexus/src/core/lbug/lbug-adapter.ts'],
-    rules: {
-      'no-restricted-syntax': [
-        'error',
-        ...mcpStdoutWriteSelectors,
-        {
-          selector: "CallExpression[callee.object.name='conn'][callee.property.name='close']",
-          message: 'Use safeClose() instead of calling conn.close() directly (#1376).',
-        },
-        {
-          selector: "CallExpression[callee.object.name='db'][callee.property.name='close']",
-          message: 'Use safeClose() instead of calling db.close() directly (#1376).',
-        },
-      ],
-    },
-  },
-
   // Disable formatting rules (prettier handles those)
   prettierConfig,
 ];

eval/bridge/mcp_bridge.py

@@ -53,13 +53,13 @@ class MCPBridge:
 
         try:
             # Find gitnexus binary
-            gitnexus_cmd = self._find_gitnexus_command()
-            if not gitnexus_cmd:
+            gitnexus_bin = self._find_gitnexus()
+            if not gitnexus_bin:
                 logger.error("GitNexus not found. Install with: npm install -g gitnexus")
                 return False
 
             self.process = subprocess.Popen(
-                [*gitnexus_cmd, "mcp"],
+                [gitnexus_bin, "mcp"],
                 stdin=subprocess.PIPE,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,
@@ -152,34 +152,33 @@ class MCPBridge:
                 return contents[0].get("text", "")
         return None
 
-    def _find_gitnexus_command(self) -> list[str] | None:
-        """Find the gitnexus CLI command prefix."""
+    def _find_gitnexus(self) -> str | None:
+        """Find the gitnexus CLI binary."""
         # Check if npx is available (preferred - uses local install)
-        try:
-            result = subprocess.run(
-                ["npx", "gitnexus", "--version"],
-                stdin=subprocess.DEVNULL,
-                capture_output=True,
-                text=True,
-                timeout=MCP_FIND_GITNEXUS_TIMEOUT_SECONDS,
-                cwd=self.repo_path,
-            )
-            if result.returncode == 0:
-                return ["npx", "gitnexus"]
-        except Exception:
-            pass
+        for cmd in ["npx"]:
+            try:
+                result = subprocess.run(
+                    [cmd, "gitnexus", "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=MCP_FIND_GITNEXUS_TIMEOUT_SECONDS,
+                    cwd=self.repo_path,
+                )
+                if result.returncode == 0:
+                    return cmd  # Will use "npx gitnexus mcp"
+            except Exception:
+                continue
 
         # Check for global install
         try:
             result = subprocess.run(
                 ["gitnexus", "--version"],
-                stdin=subprocess.DEVNULL,
                 capture_output=True,
                 text=True,
                 timeout=MCP_FIND_GITNEXUS_FALLBACK_TIMEOUT_SECONDS,
             )
             if result.returncode == 0:
-                return ["gitnexus"]
+                return "gitnexus"
         except Exception:
             pass
 

eval/pyproject.toml

@@ -6,19 +6,19 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "mini-swe-agent>=2.0.0",
-    "litellm!=1.82.7,!=1.82.8,>=1.83.7",
+    "litellm>=1.50.0,!=1.82.7,!=1.82.8",
     "datasets>=3.0.0",
     "typer>=0.12.0",
     "rich>=13.0.0",
     "pyyaml>=6.0",
     "pandas>=2.0.0",
     "tabulate>=0.9.0",
-    "python-dotenv>=1.2.2",
+    "python-dotenv>=1.0.0",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=9.0.3",
+    "pytest>=8.0.0",
     "ruff>=0.5.0",
     "hypothesis>=6.88.0",
     "coverage>=7.6.0",

eval/tests/test_mcp_bridge.py

@@ -1,170 +0,0 @@
-"""Tests for MCPBridge._find_gitnexus_command() and subprocess spawn."""
-import subprocess
-import unittest
-from unittest.mock import MagicMock, call, patch
-
-
-class TestFindGitnexusCommand(unittest.TestCase):
-    """Verify _find_gitnexus_command() returns the correct command prefix."""
-
-    def _make_bridge(self):
-        from bridge.mcp_bridge import MCPBridge
-        return MCPBridge(repo_path="/fake/repo")
-
-    def _success(self):
-        r = MagicMock()
-        r.returncode = 0
-        return r
-
-    def _failure(self):
-        r = MagicMock()
-        r.returncode = 1
-        return r
-
-    def test_npx_path_returns_npx_gitnexus(self):
-        """When npx probe succeeds, command prefix is ['npx', 'gitnexus']."""
-        with patch("subprocess.run", return_value=self._success()) as mock_run:
-            bridge = self._make_bridge()
-            result = bridge._find_gitnexus_command()
-
-        self.assertEqual(result, ["npx", "gitnexus"])
-        mock_run.assert_called_once()
-        args = mock_run.call_args[0][0]
-        self.assertEqual(args, ["npx", "gitnexus", "--version"])
-
-    def test_global_path_returns_gitnexus(self):
-        """When npx probe fails but global install exists, prefix is ['gitnexus']."""
-        with patch("subprocess.run", side_effect=[self._failure(), self._success()]) as mock_run:
-            bridge = self._make_bridge()
-            result = bridge._find_gitnexus_command()
-
-        self.assertEqual(result, ["gitnexus"])
-        self.assertEqual(mock_run.call_count, 2)
-
-    def test_both_fail_returns_none(self):
-        """When both probes fail, returns None."""
-        with patch("subprocess.run", return_value=self._failure()):
-            bridge = self._make_bridge()
-            result = bridge._find_gitnexus_command()
-
-        self.assertIsNone(result)
-
-    def test_npx_exception_falls_back_to_global(self):
-        """When npx raises (not installed), falls back to global probe."""
-        with patch("subprocess.run", side_effect=[FileNotFoundError, self._success()]):
-            bridge = self._make_bridge()
-            result = bridge._find_gitnexus_command()
-
-        self.assertEqual(result, ["gitnexus"])
-
-    def test_both_raise_returns_none(self):
-        """When both probes raise exceptions, returns None."""
-        with patch("subprocess.run", side_effect=FileNotFoundError):
-            bridge = self._make_bridge()
-            result = bridge._find_gitnexus_command()
-
-        self.assertIsNone(result)
-
-    def test_stdin_devnull_on_npx_probe(self):
-        """npx probe must pass stdin=DEVNULL to prevent interactive blocking."""
-        with patch("subprocess.run", return_value=self._success()) as mock_run:
-            bridge = self._make_bridge()
-            bridge._find_gitnexus_command()
-
-        kwargs = mock_run.call_args[1]
-        self.assertEqual(kwargs.get("stdin"), subprocess.DEVNULL)
-
-    def test_stdin_devnull_on_global_probe(self):
-        """global probe must pass stdin=DEVNULL to prevent interactive blocking."""
-        with patch("subprocess.run", side_effect=[self._failure(), self._success()]) as mock_run:
-            bridge = self._make_bridge()
-            bridge._find_gitnexus_command()
-
-        global_call_kwargs = mock_run.call_args_list[1][1]
-        self.assertEqual(global_call_kwargs.get("stdin"), subprocess.DEVNULL)
-
-
-class TestStartSpawnCommand(unittest.TestCase):
-    """Verify start() spawns Popen with the correct argv."""
-
-    def _make_bridge(self):
-        from bridge.mcp_bridge import MCPBridge
-        return MCPBridge(repo_path="/fake/repo")
-
-    def test_npx_path_spawns_npx_gitnexus_mcp(self):
-        """When npx path found, Popen must receive ['npx', 'gitnexus', 'mcp']."""
-        bridge = self._make_bridge()
-
-        with patch.object(bridge, "_find_gitnexus_command", return_value=["npx", "gitnexus"]), \
-             patch("subprocess.Popen") as mock_popen, \
-             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
-             patch.object(bridge, "_send_notification"):
-
-            mock_proc = MagicMock()
-            mock_proc.stdin = MagicMock()
-            mock_proc.stdout = MagicMock()
-            mock_proc.stderr = MagicMock()
-            mock_popen.return_value = mock_proc
-
-            bridge.start()
-
-        mock_popen.assert_called_once()
-        argv = mock_popen.call_args[0][0]
-        self.assertEqual(argv, ["npx", "gitnexus", "mcp"])
-
-    def test_global_path_spawns_gitnexus_mcp(self):
-        """When global path found, Popen must receive ['gitnexus', 'mcp']."""
-        bridge = self._make_bridge()
-
-        with patch.object(bridge, "_find_gitnexus_command", return_value=["gitnexus"]), \
-             patch("subprocess.Popen") as mock_popen, \
-             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
-             patch.object(bridge, "_send_notification"):
-
-            mock_proc = MagicMock()
-            mock_proc.stdin = MagicMock()
-            mock_proc.stdout = MagicMock()
-            mock_proc.stderr = MagicMock()
-            mock_popen.return_value = mock_proc
-
-            bridge.start()
-
-        mock_popen.assert_called_once()
-        argv = mock_popen.call_args[0][0]
-        self.assertEqual(argv, ["gitnexus", "mcp"])
-
-    def test_no_shell_true(self):
-        """Popen must never be called with shell=True."""
-        bridge = self._make_bridge()
-
-        with patch.object(bridge, "_find_gitnexus_command", return_value=["npx", "gitnexus"]), \
-             patch("subprocess.Popen") as mock_popen, \
-             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
-             patch.object(bridge, "_send_notification"):
-
-            mock_proc = MagicMock()
-            mock_proc.stdin = MagicMock()
-            mock_proc.stdout = MagicMock()
-            mock_proc.stderr = MagicMock()
-            mock_popen.return_value = mock_proc
-
-            bridge.start()
-
-        kwargs = mock_popen.call_args[1]
-        self.assertNotEqual(kwargs.get("shell"), True)
-
-    def test_gitnexus_not_found_returns_false(self):
-        """start() returns False and does not call Popen when gitnexus not found."""
-        bridge = self._make_bridge()
-
-        with patch.object(bridge, "_find_gitnexus_command", return_value=None), \
-             patch("subprocess.Popen") as mock_popen:
-
-            result = bridge.start()
-
-        self.assertFalse(result)
-        mock_popen.assert_not_called()
-
-
-if __name__ == "__main__":
-    unittest.main()

eval/uv.lock

@@ -21,7 +21,7 @@ wheels = [
 
 [[package]]
 name = "aiohttp"
-version = "3.13.4"
+version = "3.13.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohappyeyeballs" },
@@ -32,93 +32,93 @@ dependencies = [
     { name = "propcache" },
     { name = "yarl" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/45/4a/064321452809dae953c1ed6e017504e72551a26b6f5708a5a80e4bf556ff/aiohttp-3.13.4.tar.gz", hash = "sha256:d97a6d09c66087890c2ab5d49069e1e570583f7ac0314ecf98294c1b6aaebd38", size = 7859748, upload-time = "2026-03-28T17:19:40.6Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/50/42/32cf8e7704ceb4481406eb87161349abb46a57fee3f008ba9cb610968646/aiohttp-3.13.3.tar.gz", hash = "sha256:a949eee43d3782f2daae4f4a2819b2cb9b0c5d3b7f7a927067cc84dafdbb9f88", size = 7844556, upload-time = "2026-01-03T17:33:05.204Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d4/7e/cb94129302d78c46662b47f9897d642fd0b33bdfef4b73b20c6ced35aa4c/aiohttp-3.13.4-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:8ea0c64d1bcbf201b285c2246c51a0c035ba3bbd306640007bc5844a3b4658c1", size = 760027, upload-time = "2026-03-28T17:15:33.022Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/cd/2db3c9397c3bd24216b203dd739945b04f8b87bb036c640da7ddb63c75ef/aiohttp-3.13.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6f742e1fa45c0ed522b00ede565e18f97e4cf8d1883a712ac42d0339dfb0cce7", size = 508325, upload-time = "2026-03-28T17:15:34.714Z" },
-    { url = "https://files.pythonhosted.org/packages/36/a3/d28b2722ec13107f2e37a86b8a169897308bab6a3b9e071ecead9d67bd9b/aiohttp-3.13.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:6dcfb50ee25b3b7a1222a9123be1f9f89e56e67636b561441f0b304e25aaef8f", size = 502402, upload-time = "2026-03-28T17:15:36.409Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/d6/acd47b5f17c4430e555590990a4746efbcb2079909bb865516892bf85f37/aiohttp-3.13.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3262386c4ff370849863ea93b9ea60fd59c6cf56bf8f93beac625cf4d677c04d", size = 1771224, upload-time = "2026-03-28T17:15:38.223Z" },
-    { url = "https://files.pythonhosted.org/packages/98/af/af6e20113ba6a48fd1cd9e5832c4851e7613ef50c7619acdaee6ec5f1aff/aiohttp-3.13.4-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:473bb5aa4218dd254e9ae4834f20e31f5a0083064ac0136a01a62ddbae2eaa42", size = 1731530, upload-time = "2026-03-28T17:15:39.988Z" },
-    { url = "https://files.pythonhosted.org/packages/81/16/78a2f5d9c124ad05d5ce59a9af94214b6466c3491a25fb70760e98e9f762/aiohttp-3.13.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e56423766399b4c77b965f6aaab6c9546617b8994a956821cc507d00b91d978c", size = 1827925, upload-time = "2026-03-28T17:15:41.944Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/1f/79acf0974ced805e0e70027389fccbb7d728e6f30fcac725fb1071e63075/aiohttp-3.13.4-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8af249343fafd5ad90366a16d230fc265cf1149f26075dc9fe93cfd7c7173942", size = 1923579, upload-time = "2026-03-28T17:15:44.071Z" },
-    { url = "https://files.pythonhosted.org/packages/af/53/29f9e2054ea6900413f3b4c3eb9d8331f60678ec855f13ba8714c47fd48d/aiohttp-3.13.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0bc0a5cf4f10ef5a2c94fdde488734b582a3a7a000b131263e27c9295bd682d9", size = 1767655, upload-time = "2026-03-28T17:15:45.911Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/57/462fe1d3da08109ba4aa8590e7aed57c059af2a7e80ec21f4bac5cfe1094/aiohttp-3.13.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5c7ff1028e3c9fc5123a865ce17df1cb6424d180c503b8517afbe89aa566e6be", size = 1630439, upload-time = "2026-03-28T17:15:48.11Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/4b/4813344aacdb8127263e3eec343d24e973421143826364fa9fc847f6283f/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:ba5cf98b5dcb9bddd857da6713a503fa6d341043258ca823f0f5ab7ab4a94ee8", size = 1745557, upload-time = "2026-03-28T17:15:50.13Z" },
-    { url = "https://files.pythonhosted.org/packages/d4/01/1ef1adae1454341ec50a789f03cfafe4c4ac9c003f6a64515ecd32fe4210/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:d85965d3ba21ee4999e83e992fecb86c4614d6920e40705501c0a1f80a583c12", size = 1741796, upload-time = "2026-03-28T17:15:52.351Z" },
-    { url = "https://files.pythonhosted.org/packages/22/04/8cdd99af988d2aa6922714d957d21383c559835cbd43fbf5a47ddf2e0f05/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:49f0b18a9b05d79f6f37ddd567695943fcefb834ef480f17a4211987302b2dc7", size = 1805312, upload-time = "2026-03-28T17:15:54.407Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/7f/b48d5577338d4b25bbdbae35c75dbfd0493cb8886dc586fbfb2e90862239/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:7f78cb080c86fbf765920e5f1ef35af3f24ec4314d6675d0a21eaf41f6f2679c", size = 1621751, upload-time = "2026-03-28T17:15:56.564Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/89/4eecad8c1858e6d0893c05929e22343e0ebe3aec29a8a399c65c3cc38311/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:67a3ec705534a614b68bbf1c70efa777a21c3da3895d1c44510a41f5a7ae0453", size = 1826073, upload-time = "2026-03-28T17:15:58.489Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/5c/9dc8293ed31b46c39c9c513ac7ca152b3c3d38e0ea111a530ad12001b827/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:d6630ec917e85c5356b2295744c8a97d40f007f96a1c76bf1928dc2e27465393", size = 1760083, upload-time = "2026-03-28T17:16:00.677Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/19/8bbf6a4994205d96831f97b7d21a0feed120136e6267b5b22d229c6dc4dc/aiohttp-3.13.4-cp311-cp311-win32.whl", hash = "sha256:54049021bc626f53a5394c29e8c444f726ee5a14b6e89e0ad118315b1f90f5e3", size = 439690, upload-time = "2026-03-28T17:16:02.902Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/f5/ac409ecd1007528d15c3e8c3a57d34f334c70d76cfb7128a28cffdebd4c1/aiohttp-3.13.4-cp311-cp311-win_amd64.whl", hash = "sha256:c033f2bc964156030772d31cbf7e5defea181238ce1f87b9455b786de7d30145", size = 463824, upload-time = "2026-03-28T17:16:05.058Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/bd/ede278648914cabbabfdf95e436679b5d4156e417896a9b9f4587169e376/aiohttp-3.13.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ee62d4471ce86b108b19c3364db4b91180d13fe3510144872d6bad5401957360", size = 752158, upload-time = "2026-03-28T17:16:06.901Z" },
-    { url = "https://files.pythonhosted.org/packages/90/de/581c053253c07b480b03785196ca5335e3c606a37dc73e95f6527f1591fe/aiohttp-3.13.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c0fd8f41b54b58636402eb493afd512c23580456f022c1ba2db0f810c959ed0d", size = 501037, upload-time = "2026-03-28T17:16:08.82Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/f9/a5ede193c08f13cc42c0a5b50d1e246ecee9115e4cf6e900d8dbd8fd6acb/aiohttp-3.13.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4baa48ce49efd82d6b1a0be12d6a36b35e5594d1dd42f8bfba96ea9f8678b88c", size = 501556, upload-time = "2026-03-28T17:16:10.63Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/10/88ff67cd48a6ec36335b63a640abe86135791544863e0cfe1f065d6cef7a/aiohttp-3.13.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d738ebab9f71ee652d9dbd0211057690022201b11197f9a7324fd4dba128aa97", size = 1757314, upload-time = "2026-03-28T17:16:12.498Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/15/fdb90a5cf5a1f52845c276e76298c75fbbcc0ac2b4a86551906d54529965/aiohttp-3.13.4-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0ce692c3468fa831af7dceed52edf51ac348cebfc8d3feb935927b63bd3e8576", size = 1731819, upload-time = "2026-03-28T17:16:14.558Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/df/28146785a007f7820416be05d4f28cc207493efd1e8c6c1068e9bdc29198/aiohttp-3.13.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8e08abcfe752a454d2cb89ff0c08f2d1ecd057ae3e8cc6d84638de853530ebab", size = 1793279, upload-time = "2026-03-28T17:16:16.594Z" },
-    { url = "https://files.pythonhosted.org/packages/10/47/689c743abf62ea7a77774d5722f220e2c912a77d65d368b884d9779ef41b/aiohttp-3.13.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5977f701b3fff36367a11087f30ea73c212e686d41cd363c50c022d48b011d8d", size = 1891082, upload-time = "2026-03-28T17:16:18.71Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/b6/f7f4f318c7e58c23b761c9b13b9a3c9b394e0f9d5d76fbc6622fa98509f6/aiohttp-3.13.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:54203e10405c06f8b6020bd1e076ae0fe6c194adcee12a5a78af3ffa3c57025e", size = 1773938, upload-time = "2026-03-28T17:16:21.125Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/06/f207cb3121852c989586a6fc16ff854c4fcc8651b86c5d3bd1fc83057650/aiohttp-3.13.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:358a6af0145bc4dda037f13167bef3cce54b132087acc4c295c739d05d16b1c3", size = 1579548, upload-time = "2026-03-28T17:16:23.588Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/58/e1289661a32161e24c1fe479711d783067210d266842523752869cc1d9c2/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:898ea1850656d7d61832ef06aa9846ab3ddb1621b74f46de78fbc5e1a586ba83", size = 1714669, upload-time = "2026-03-28T17:16:25.713Z" },
-    { url = "https://files.pythonhosted.org/packages/96/0a/3e86d039438a74a86e6a948a9119b22540bae037d6ba317a042ae3c22711/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:7bc30cceb710cf6a44e9617e43eebb6e3e43ad855a34da7b4b6a73537d8a6763", size = 1754175, upload-time = "2026-03-28T17:16:28.18Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/30/e717fc5df83133ba467a560b6d8ef20197037b4bb5d7075b90037de1018e/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:4a31c0c587a8a038f19a4c7e60654a6c899c9de9174593a13e7cc6e15ff271f9", size = 1762049, upload-time = "2026-03-28T17:16:30.941Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/28/8f7a2d4492e336e40005151bdd94baf344880a4707573378579f833a64c1/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:2062f675f3fe6e06d6113eb74a157fb9df58953ffed0cdb4182554b116545758", size = 1570861, upload-time = "2026-03-28T17:16:32.953Z" },
-    { url = "https://files.pythonhosted.org/packages/78/45/12e1a3d0645968b1c38de4b23fdf270b8637735ea057d4f84482ff918ad9/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:3d1ba8afb847ff80626d5e408c1fdc99f942acc877d0702fe137015903a220a9", size = 1790003, upload-time = "2026-03-28T17:16:35.468Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/0f/60374e18d590de16dcb39d6ff62f39c096c1b958e6f37727b5870026ea30/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b08149419994cdd4d5eecf7fd4bc5986b5a9380285bcd01ab4c0d6bfca47b79d", size = 1737289, upload-time = "2026-03-28T17:16:38.187Z" },
-    { url = "https://files.pythonhosted.org/packages/02/bf/535e58d886cfbc40a8b0013c974afad24ef7632d645bca0b678b70033a60/aiohttp-3.13.4-cp312-cp312-win32.whl", hash = "sha256:fc432f6a2c4f720180959bc19aa37259651c1a4ed8af8afc84dd41c60f15f791", size = 434185, upload-time = "2026-03-28T17:16:40.735Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/1a/d92e3325134ebfff6f4069f270d3aac770d63320bd1fcd0eca023e74d9a8/aiohttp-3.13.4-cp312-cp312-win_amd64.whl", hash = "sha256:6148c9ae97a3e8bff9a1fc9c757fa164116f86c100468339730e717590a3fb77", size = 461285, upload-time = "2026-03-28T17:16:42.713Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/ac/892f4162df9b115b4758d615f32ec63d00f3084c705ff5526630887b9b42/aiohttp-3.13.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:63dd5e5b1e43b8fb1e91b79b7ceba1feba588b317d1edff385084fcc7a0a4538", size = 745744, upload-time = "2026-03-28T17:16:44.67Z" },
-    { url = "https://files.pythonhosted.org/packages/97/a9/c5b87e4443a2f0ea88cb3000c93a8fdad1ee63bffc9ded8d8c8e0d66efc6/aiohttp-3.13.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:746ac3cc00b5baea424dacddea3ec2c2702f9590de27d837aa67004db1eebc6e", size = 498178, upload-time = "2026-03-28T17:16:46.766Z" },
-    { url = "https://files.pythonhosted.org/packages/94/42/07e1b543a61250783650df13da8ddcdc0d0a5538b2bd15cef6e042aefc61/aiohttp-3.13.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:bda8f16ea99d6a6705e5946732e48487a448be874e54a4f73d514660ff7c05d3", size = 498331, upload-time = "2026-03-28T17:16:48.9Z" },
-    { url = "https://files.pythonhosted.org/packages/20/d6/492f46bf0328534124772d0cf58570acae5b286ea25006900650f69dae0e/aiohttp-3.13.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4b061e7b5f840391e3f64d0ddf672973e45c4cfff7a0feea425ea24e51530fc2", size = 1744414, upload-time = "2026-03-28T17:16:50.968Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/4d/e02627b2683f68051246215d2d62b2d2f249ff7a285e7a858dc47d6b6a14/aiohttp-3.13.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:b252e8d5cd66184b570d0d010de742736e8a4fab22c58299772b0c5a466d4b21", size = 1719226, upload-time = "2026-03-28T17:16:53.173Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/6c/5d0a3394dd2b9f9aeba6e1b6065d0439e4b75d41f1fb09a3ec010b43552b/aiohttp-3.13.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:20af8aad61d1803ff11152a26146d8d81c266aa8c5aa9b4504432abb965c36a0", size = 1782110, upload-time = "2026-03-28T17:16:55.362Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/2d/c20791e3437700a7441a7edfb59731150322424f5aadf635602d1d326101/aiohttp-3.13.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:13a5cc924b59859ad2adb1478e31f410a7ed46e92a2a619d6d1dd1a63c1a855e", size = 1884809, upload-time = "2026-03-28T17:16:57.734Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/94/d99dbfbd1924a87ef643833932eb2a3d9e5eee87656efea7d78058539eff/aiohttp-3.13.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:534913dfb0a644d537aebb4123e7d466d94e3be5549205e6a31f72368980a81a", size = 1764938, upload-time = "2026-03-28T17:17:00.221Z" },
-    { url = "https://files.pythonhosted.org/packages/49/61/3ce326a1538781deb89f6cf5e094e2029cd308ed1e21b2ba2278b08426f6/aiohttp-3.13.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:320e40192a2dcc1cf4b5576936e9652981ab596bf81eb309535db7e2f5b5672f", size = 1570697, upload-time = "2026-03-28T17:17:02.985Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/77/4ab5a546857bb3028fbaf34d6eea180267bdab022ee8b1168b1fcde4bfdd/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:9e587fcfce2bcf06526a43cb705bdee21ac089096f2e271d75de9c339db3100c", size = 1702258, upload-time = "2026-03-28T17:17:05.28Z" },
-    { url = "https://files.pythonhosted.org/packages/79/63/d8f29021e39bc5af8e5d5e9da1b07976fb9846487a784e11e4f4eeda4666/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:9eb9c2eea7278206b5c6c1441fdd9dc420c278ead3f3b2cc87f9b693698cc500", size = 1740287, upload-time = "2026-03-28T17:17:07.712Z" },
-    { url = "https://files.pythonhosted.org/packages/55/3a/cbc6b3b124859a11bc8055d3682c26999b393531ef926754a3445b99dfef/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:29be00c51972b04bf9d5c8f2d7f7314f48f96070ca40a873a53056e652e805f7", size = 1753011, upload-time = "2026-03-28T17:17:10.053Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/30/836278675205d58c1368b21520eab9572457cf19afd23759216c04483048/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:90c06228a6c3a7c9f776fe4fc0b7ff647fffd3bed93779a6913c804ae00c1073", size = 1566359, upload-time = "2026-03-28T17:17:12.433Z" },
-    { url = "https://files.pythonhosted.org/packages/50/b4/8032cc9b82d17e4277704ba30509eaccb39329dc18d6a35f05e424439e32/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:a533ec132f05fd9a1d959e7f34184cd7d5e8511584848dab85faefbaac573069", size = 1785537, upload-time = "2026-03-28T17:17:14.721Z" },
-    { url = "https://files.pythonhosted.org/packages/17/7d/5873e98230bde59f493bf1f7c3e327486a4b5653fa401144704df5d00211/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1c946f10f413836f82ea4cfb90200d2a59578c549f00857e03111cf45ad01ca5", size = 1740752, upload-time = "2026-03-28T17:17:17.387Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/f2/13e46e0df051494d7d3c68b7f72d071f48c384c12716fc294f75d5b1a064/aiohttp-3.13.4-cp313-cp313-win32.whl", hash = "sha256:48708e2706106da6967eff5908c78ca3943f005ed6bcb75da2a7e4da94ef8c70", size = 433187, upload-time = "2026-03-28T17:17:19.523Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/c0/649856ee655a843c8f8664592cfccb73ac80ede6a8c8db33a25d810c12db/aiohttp-3.13.4-cp313-cp313-win_amd64.whl", hash = "sha256:74a2eb058da44fa3a877a49e2095b591d4913308bb424c418b77beb160c55ce3", size = 459778, upload-time = "2026-03-28T17:17:21.964Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/29/6657cc37ae04cacc2dbf53fb730a06b6091cc4cbe745028e047c53e6d840/aiohttp-3.13.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:e0a2c961fc92abeff61d6444f2ce6ad35bb982db9fc8ff8a47455beacf454a57", size = 749363, upload-time = "2026-03-28T17:17:24.044Z" },
-    { url = "https://files.pythonhosted.org/packages/90/7f/30ccdf67ca3d24b610067dc63d64dcb91e5d88e27667811640644aa4a85d/aiohttp-3.13.4-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:153274535985a0ff2bff1fb6c104ed547cec898a09213d21b0f791a44b14d933", size = 499317, upload-time = "2026-03-28T17:17:26.199Z" },
-    { url = "https://files.pythonhosted.org/packages/93/13/e372dd4e68ad04ee25dafb050c7f98b0d91ea643f7352757e87231102555/aiohttp-3.13.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:351f3171e2458da3d731ce83f9e6b9619e325c45cbd534c7759750cabf453ad7", size = 500477, upload-time = "2026-03-28T17:17:28.279Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/fe/ee6298e8e586096fb6f5eddd31393d8544f33ae0792c71ecbb4c2bef98ac/aiohttp-3.13.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f989ac8bc5595ff761a5ccd32bdb0768a117f36dd1504b1c2c074ed5d3f4df9c", size = 1737227, upload-time = "2026-03-28T17:17:30.587Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/b9/a7a0463a09e1a3fe35100f74324f23644bfc3383ac5fd5effe0722a5f0b7/aiohttp-3.13.4-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d36fc1709110ec1e87a229b201dd3ddc32aa01e98e7868083a794609b081c349", size = 1694036, upload-time = "2026-03-28T17:17:33.29Z" },
-    { url = "https://files.pythonhosted.org/packages/57/7c/8972ae3fb7be00a91aee6b644b2a6a909aedb2c425269a3bfd90115e6f8f/aiohttp-3.13.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:42adaeea83cbdf069ab94f5103ce0787c21fb1a0153270da76b59d5578302329", size = 1786814, upload-time = "2026-03-28T17:17:36.035Z" },
-    { url = "https://files.pythonhosted.org/packages/93/01/c81e97e85c774decbaf0d577de7d848934e8166a3a14ad9f8aa5be329d28/aiohttp-3.13.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:92deb95469928cc41fd4b42a95d8012fa6df93f6b1c0a83af0ffbc4a5e218cde", size = 1866676, upload-time = "2026-03-28T17:17:38.441Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/5f/5b46fe8694a639ddea2cd035bf5729e4677ea882cb251396637e2ef1590d/aiohttp-3.13.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0c0c7c07c4257ef3a1df355f840bc62d133bcdef5c1c5ba75add3c08553e2eed", size = 1740842, upload-time = "2026-03-28T17:17:40.783Z" },
-    { url = "https://files.pythonhosted.org/packages/20/a2/0d4b03d011cca6b6b0acba8433193c1e484efa8d705ea58295590fe24203/aiohttp-3.13.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f062c45de8a1098cb137a1898819796a2491aec4e637a06b03f149315dff4d8f", size = 1566508, upload-time = "2026-03-28T17:17:43.235Z" },
-    { url = "https://files.pythonhosted.org/packages/98/17/e689fd500da52488ec5f889effd6404dece6a59de301e380f3c64f167beb/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:76093107c531517001114f0ebdb4f46858ce818590363e3e99a4a2280334454a", size = 1700569, upload-time = "2026-03-28T17:17:46.165Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/0d/66402894dbcf470ef7db99449e436105ea862c24f7ea4c95c683e635af35/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:6f6ec32162d293b82f8b63a16edc80769662fbd5ae6fbd4936d3206a2c2cc63b", size = 1707407, upload-time = "2026-03-28T17:17:48.825Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/eb/af0ab1a3650092cbd8e14ef29e4ab0209e1460e1c299996c3f8288b3f1ff/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:5903e2db3d202a00ad9f0ec35a122c005e85d90c9836ab4cda628f01edf425e2", size = 1752214, upload-time = "2026-03-28T17:17:51.206Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/bf/72326f8a98e4c666f292f03c385545963cc65e358835d2a7375037a97b57/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2d5bea57be7aca98dbbac8da046d99b5557c5cf4e28538c4c786313078aca09e", size = 1562162, upload-time = "2026-03-28T17:17:53.634Z" },
-    { url = "https://files.pythonhosted.org/packages/67/9f/13b72435f99151dd9a5469c96b3b5f86aa29b7e785ca7f35cf5e538f74c0/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:bcf0c9902085976edc0232b75006ef38f89686901249ce14226b6877f88464fb", size = 1768904, upload-time = "2026-03-28T17:17:55.991Z" },
-    { url = "https://files.pythonhosted.org/packages/18/bc/28d4970e7d5452ac7776cdb5431a1164a0d9cf8bd2fffd67b4fb463aa56d/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:c3295f98bfeed2e867cab588f2a146a9db37a85e3ae9062abf46ba062bd29165", size = 1723378, upload-time = "2026-03-28T17:17:58.348Z" },
-    { url = "https://files.pythonhosted.org/packages/53/74/b32458ca1a7f34d65bdee7aef2036adbe0438123d3d53e2b083c453c24dd/aiohttp-3.13.4-cp314-cp314-win32.whl", hash = "sha256:a598a5c5767e1369d8f5b08695cab1d8160040f796c4416af76fd773d229b3c9", size = 438711, upload-time = "2026-03-28T17:18:00.728Z" },
-    { url = "https://files.pythonhosted.org/packages/40/b2/54b487316c2df3e03a8f3435e9636f8a81a42a69d942164830d193beb56a/aiohttp-3.13.4-cp314-cp314-win_amd64.whl", hash = "sha256:c555db4bc7a264bead5a7d63d92d41a1122fcd39cc62a4db815f45ad46f9c2c8", size = 464977, upload-time = "2026-03-28T17:18:03.367Z" },
-    { url = "https://files.pythonhosted.org/packages/47/fb/e41b63c6ce71b07a59243bb8f3b457ee0c3402a619acb9d2c0d21ef0e647/aiohttp-3.13.4-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:45abbbf09a129825d13c18c7d3182fecd46d9da3cfc383756145394013604ac1", size = 781549, upload-time = "2026-03-28T17:18:05.779Z" },
-    { url = "https://files.pythonhosted.org/packages/97/53/532b8d28df1e17e44c4d9a9368b78dcb6bf0b51037522136eced13afa9e8/aiohttp-3.13.4-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:74c80b2bc2c2adb7b3d1941b2b60701ee2af8296fc8aad8b8bc48bc25767266c", size = 514383, upload-time = "2026-03-28T17:18:08.096Z" },
-    { url = "https://files.pythonhosted.org/packages/1b/1f/62e5d400603e8468cd635812d99cb81cfdc08127a3dc474c647615f31339/aiohttp-3.13.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c97989ae40a9746650fa196894f317dafc12227c808c774929dda0ff873a5954", size = 518304, upload-time = "2026-03-28T17:18:10.642Z" },
-    { url = "https://files.pythonhosted.org/packages/90/57/2326b37b10896447e3c6e0cbef4fe2486d30913639a5cfd1332b5d870f82/aiohttp-3.13.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dae86be9811493f9990ef44fff1685f5c1a3192e9061a71a109d527944eed551", size = 1893433, upload-time = "2026-03-28T17:18:13.121Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/b4/a24d82112c304afdb650167ef2fe190957d81cbddac7460bedd245f765aa/aiohttp-3.13.4-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:1db491abe852ca2fa6cc48a3341985b0174b3741838e1341b82ac82c8bd9e871", size = 1755901, upload-time = "2026-03-28T17:18:16.21Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/2d/0883ef9d878d7846287f036c162a951968f22aabeef3ac97b0bea6f76d5d/aiohttp-3.13.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0e5d701c0aad02a7dce72eef6b93226cf3734330f1a31d69ebbf69f33b86666e", size = 1876093, upload-time = "2026-03-28T17:18:18.703Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/52/9204bb59c014869b71971addad6778f005daa72a96eed652c496789d7468/aiohttp-3.13.4-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8ac32a189081ae0a10ba18993f10f338ec94341f0d5df8fff348043962f3c6f8", size = 1970815, upload-time = "2026-03-28T17:18:21.858Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/b5/e4eb20275a866dde0f570f411b36c6b48f7b53edfe4f4071aa1b0728098a/aiohttp-3.13.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:98e968cdaba43e45c73c3f306fca418c8009a957733bac85937c9f9cf3f4de27", size = 1816223, upload-time = "2026-03-28T17:18:24.729Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/23/e98075c5bb146aa61a1239ee1ac7714c85e814838d6cebbe37d3fe19214a/aiohttp-3.13.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ca114790c9144c335d538852612d3e43ea0f075288f4849cf4b05d6cd2238ce7", size = 1649145, upload-time = "2026-03-28T17:18:27.269Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/c1/7bad8be33bb06c2bb224b6468874346026092762cbec388c3bdb65a368ee/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ea2e071661ba9cfe11eabbc81ac5376eaeb3061f6e72ec4cc86d7cdd1ffbdbbb", size = 1816562, upload-time = "2026-03-28T17:18:29.847Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/10/c00323348695e9a5e316825969c88463dcc24c7e9d443244b8a2c9cf2eae/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:34e89912b6c20e0fd80e07fa401fd218a410aa1ce9f1c2f1dad6db1bd0ce0927", size = 1800333, upload-time = "2026-03-28T17:18:32.269Z" },
-    { url = "https://files.pythonhosted.org/packages/84/43/9b2147a1df3559f49bd723e22905b46a46c068a53adb54abdca32c4de180/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0e217cf9f6a42908c52b46e42c568bd57adc39c9286ced31aaace614b6087965", size = 1820617, upload-time = "2026-03-28T17:18:35.238Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/7f/b3481a81e7a586d02e99387b18c6dafff41285f6efd3daa2124c01f87eae/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:0c296f1221e21ba979f5ac1964c3b78cfde15c5c5f855ffd2caab337e9cd9182", size = 1643417, upload-time = "2026-03-28T17:18:37.949Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/72/07181226bc99ce1124e0f89280f5221a82d3ae6a6d9d1973ce429d48e52b/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:d99a9d168ebaffb74f36d011750e490085ac418f4db926cce3989c8fe6cb6b1b", size = 1849286, upload-time = "2026-03-28T17:18:40.534Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/e6/1b3566e103eca6da5be4ae6713e112a053725c584e96574caf117568ffef/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cb19177205d93b881f3f89e6081593676043a6828f59c78c17a0fd6c1fbed2ba", size = 1782635, upload-time = "2026-03-28T17:18:43.073Z" },
-    { url = "https://files.pythonhosted.org/packages/37/58/1b11c71904b8d079eb0c39fe664180dd1e14bebe5608e235d8bfbadc8929/aiohttp-3.13.4-cp314-cp314t-win32.whl", hash = "sha256:c606aa5656dab6552e52ca368e43869c916338346bfaf6304e15c58fb113ea30", size = 472537, upload-time = "2026-03-28T17:18:46.286Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/8f/87c56a1a1977d7dddea5b31e12189665a140fdb48a71e9038ff90bb564ec/aiohttp-3.13.4-cp314-cp314t-win_amd64.whl", hash = "sha256:014dcc10ec8ab8db681f0d68e939d1e9286a5aa2b993cbbdb0db130853e02144", size = 506381, upload-time = "2026-03-28T17:18:48.74Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/4c/a164164834f03924d9a29dc3acd9e7ee58f95857e0b467f6d04298594ebb/aiohttp-3.13.3-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:5b6073099fb654e0a068ae678b10feff95c5cae95bbfcbfa7af669d361a8aa6b", size = 746051, upload-time = "2026-01-03T17:29:43.287Z" },
+    { url = "https://files.pythonhosted.org/packages/82/71/d5c31390d18d4f58115037c432b7e0348c60f6f53b727cad33172144a112/aiohttp-3.13.3-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:1cb93e166e6c28716c8c6aeb5f99dfb6d5ccf482d29fe9bf9a794110e6d0ab64", size = 499234, upload-time = "2026-01-03T17:29:44.822Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/c9/741f8ac91e14b1d2e7100690425a5b2b919a87a5075406582991fb7de920/aiohttp-3.13.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:28e027cf2f6b641693a09f631759b4d9ce9165099d2b5d92af9bd4e197690eea", size = 494979, upload-time = "2026-01-03T17:29:46.405Z" },
+    { url = "https://files.pythonhosted.org/packages/75/b5/31d4d2e802dfd59f74ed47eba48869c1c21552c586d5e81a9d0d5c2ad640/aiohttp-3.13.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3b61b7169ababd7802f9568ed96142616a9118dd2be0d1866e920e77ec8fa92a", size = 1748297, upload-time = "2026-01-03T17:29:48.083Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/3e/eefad0ad42959f226bb79664826883f2687d602a9ae2941a18e0484a74d3/aiohttp-3.13.3-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:80dd4c21b0f6237676449c6baaa1039abae86b91636b6c91a7f8e61c87f89540", size = 1707172, upload-time = "2026-01-03T17:29:49.648Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/3a/54a64299fac2891c346cdcf2aa6803f994a2e4beeaf2e5a09dcc54acc842/aiohttp-3.13.3-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:65d2ccb7eabee90ce0503c17716fc77226be026dcc3e65cce859a30db715025b", size = 1805405, upload-time = "2026-01-03T17:29:51.244Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/70/ddc1b7169cf64075e864f64595a14b147a895a868394a48f6a8031979038/aiohttp-3.13.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5b179331a481cb5529fca8b432d8d3c7001cb217513c94cd72d668d1248688a3", size = 1899449, upload-time = "2026-01-03T17:29:53.938Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/7e/6815aab7d3a56610891c76ef79095677b8b5be6646aaf00f69b221765021/aiohttp-3.13.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d4c940f02f49483b18b079d1c27ab948721852b281f8b015c058100e9421dd1", size = 1748444, upload-time = "2026-01-03T17:29:55.484Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/f2/073b145c4100da5511f457dc0f7558e99b2987cf72600d42b559db856fbc/aiohttp-3.13.3-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f9444f105664c4ce47a2a7171a2418bce5b7bae45fb610f4e2c36045d85911d3", size = 1606038, upload-time = "2026-01-03T17:29:57.179Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/c1/778d011920cae03ae01424ec202c513dc69243cf2db303965615b81deeea/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:694976222c711d1d00ba131904beb60534f93966562f64440d0c9d41b8cdb440", size = 1724156, upload-time = "2026-01-03T17:29:58.914Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/cb/3419eabf4ec1e9ec6f242c32b689248365a1cf621891f6f0386632525494/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:f33ed1a2bf1997a36661874b017f5c4b760f41266341af36febaf271d179f6d7", size = 1722340, upload-time = "2026-01-03T17:30:01.962Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/e5/76cf77bdbc435bf233c1f114edad39ed4177ccbfab7c329482b179cff4f4/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:e636b3c5f61da31a92bf0d91da83e58fdfa96f178ba682f11d24f31944cdd28c", size = 1783041, upload-time = "2026-01-03T17:30:03.609Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/d4/dd1ca234c794fd29c057ce8c0566b8ef7fd6a51069de5f06fa84b9a1971c/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:5d2d94f1f5fcbe40838ac51a6ab5704a6f9ea42e72ceda48de5e6b898521da51", size = 1596024, upload-time = "2026-01-03T17:30:05.132Z" },
+    { url = "https://files.pythonhosted.org/packages/55/58/4345b5f26661a6180afa686c473620c30a66afdf120ed3dd545bbc809e85/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:2be0e9ccf23e8a94f6f0650ce06042cefc6ac703d0d7ab6c7a917289f2539ad4", size = 1804590, upload-time = "2026-01-03T17:30:07.135Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/06/05950619af6c2df7e0a431d889ba2813c9f0129cec76f663e547a5ad56f2/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:9af5e68ee47d6534d36791bbe9b646d2a7c7deb6fc24d7943628edfbb3581f29", size = 1740355, upload-time = "2026-01-03T17:30:09.083Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/80/958f16de79ba0422d7c1e284b2abd0c84bc03394fbe631d0a39ffa10e1eb/aiohttp-3.13.3-cp311-cp311-win32.whl", hash = "sha256:a2212ad43c0833a873d0fb3c63fa1bacedd4cf6af2fee62bf4b739ceec3ab239", size = 433701, upload-time = "2026-01-03T17:30:10.869Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/f2/27cdf04c9851712d6c1b99df6821a6623c3c9e55956d4b1e318c337b5a48/aiohttp-3.13.3-cp311-cp311-win_amd64.whl", hash = "sha256:642f752c3eb117b105acbd87e2c143de710987e09860d674e068c4c2c441034f", size = 457678, upload-time = "2026-01-03T17:30:12.719Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/be/4fc11f202955a69e0db803a12a062b8379c970c7c84f4882b6da17337cc1/aiohttp-3.13.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:b903a4dfee7d347e2d87697d0713be59e0b87925be030c9178c5faa58ea58d5c", size = 739732, upload-time = "2026-01-03T17:30:14.23Z" },
+    { url = "https://files.pythonhosted.org/packages/97/2c/621d5b851f94fa0bb7430d6089b3aa970a9d9b75196bc93bb624b0db237a/aiohttp-3.13.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:a45530014d7a1e09f4a55f4f43097ba0fd155089372e105e4bff4ca76cb1b168", size = 494293, upload-time = "2026-01-03T17:30:15.96Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/43/4be01406b78e1be8320bb8316dc9c42dbab553d281c40364e0f862d5661c/aiohttp-3.13.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:27234ef6d85c914f9efeb77ff616dbf4ad2380be0cda40b4db086ffc7ddd1b7d", size = 493533, upload-time = "2026-01-03T17:30:17.431Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/a8/5a35dc56a06a2c90d4742cbf35294396907027f80eea696637945a106f25/aiohttp-3.13.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d32764c6c9aafb7fb55366a224756387cd50bfa720f32b88e0e6fa45b27dcf29", size = 1737839, upload-time = "2026-01-03T17:30:19.422Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/62/4b9eeb331da56530bf2e198a297e5303e1c1ebdceeb00fe9b568a65c5a0c/aiohttp-3.13.3-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:b1a6102b4d3ebc07dad44fbf07b45bb600300f15b552ddf1851b5390202ea2e3", size = 1703932, upload-time = "2026-01-03T17:30:21.756Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/f6/af16887b5d419e6a367095994c0b1332d154f647e7dc2bd50e61876e8e3d/aiohttp-3.13.3-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c014c7ea7fb775dd015b2d3137378b7be0249a448a1612268b5a90c2d81de04d", size = 1771906, upload-time = "2026-01-03T17:30:23.932Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/83/397c634b1bcc24292fa1e0c7822800f9f6569e32934bdeef09dae7992dfb/aiohttp-3.13.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2b8d8ddba8f95ba17582226f80e2de99c7a7948e66490ef8d947e272a93e9463", size = 1871020, upload-time = "2026-01-03T17:30:26Z" },
+    { url = "https://files.pythonhosted.org/packages/86/f6/a62cbbf13f0ac80a70f71b1672feba90fdb21fd7abd8dbf25c0105fb6fa3/aiohttp-3.13.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9ae8dd55c8e6c4257eae3a20fd2c8f41edaea5992ed67156642493b8daf3cecc", size = 1755181, upload-time = "2026-01-03T17:30:27.554Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/87/20a35ad487efdd3fba93d5843efdfaa62d2f1479eaafa7453398a44faf13/aiohttp-3.13.3-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:01ad2529d4b5035578f5081606a465f3b814c542882804e2e8cda61adf5c71bf", size = 1561794, upload-time = "2026-01-03T17:30:29.254Z" },
+    { url = "https://files.pythonhosted.org/packages/de/95/8fd69a66682012f6716e1bc09ef8a1a2a91922c5725cb904689f112309c4/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bb4f7475e359992b580559e008c598091c45b5088f28614e855e42d39c2f1033", size = 1697900, upload-time = "2026-01-03T17:30:31.033Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/66/7b94b3b5ba70e955ff597672dad1691333080e37f50280178967aff68657/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:c19b90316ad3b24c69cd78d5c9b4f3aa4497643685901185b65166293d36a00f", size = 1728239, upload-time = "2026-01-03T17:30:32.703Z" },
+    { url = "https://files.pythonhosted.org/packages/47/71/6f72f77f9f7d74719692ab65a2a0252584bf8d5f301e2ecb4c0da734530a/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:96d604498a7c782cb15a51c406acaea70d8c027ee6b90c569baa6e7b93073679", size = 1740527, upload-time = "2026-01-03T17:30:34.695Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/b4/75ec16cbbd5c01bdaf4a05b19e103e78d7ce1ef7c80867eb0ace42ff4488/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:084911a532763e9d3dd95adf78a78f4096cd5f58cdc18e6fdbc1b58417a45423", size = 1554489, upload-time = "2026-01-03T17:30:36.864Z" },
+    { url = "https://files.pythonhosted.org/packages/52/8f/bc518c0eea29f8406dcf7ed1f96c9b48e3bc3995a96159b3fc11f9e08321/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:7a4a94eb787e606d0a09404b9c38c113d3b099d508021faa615d70a0131907ce", size = 1767852, upload-time = "2026-01-03T17:30:39.433Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/f2/a07a75173124f31f11ea6f863dc44e6f09afe2bca45dd4e64979490deab1/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:87797e645d9d8e222e04160ee32aa06bc5c163e8499f24db719e7852ec23093a", size = 1722379, upload-time = "2026-01-03T17:30:41.081Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/4a/1a3fee7c21350cac78e5c5cef711bac1b94feca07399f3d406972e2d8fcd/aiohttp-3.13.3-cp312-cp312-win32.whl", hash = "sha256:b04be762396457bef43f3597c991e192ee7da460a4953d7e647ee4b1c28e7046", size = 428253, upload-time = "2026-01-03T17:30:42.644Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/b7/76175c7cb4eb73d91ad63c34e29fc4f77c9386bba4a65b53ba8e05ee3c39/aiohttp-3.13.3-cp312-cp312-win_amd64.whl", hash = "sha256:e3531d63d3bdfa7e3ac5e9b27b2dd7ec9df3206a98e0b3445fa906f233264c57", size = 455407, upload-time = "2026-01-03T17:30:44.195Z" },
+    { url = "https://files.pythonhosted.org/packages/97/8a/12ca489246ca1faaf5432844adbfce7ff2cc4997733e0af120869345643a/aiohttp-3.13.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:5dff64413671b0d3e7d5918ea490bdccb97a4ad29b3f311ed423200b2203e01c", size = 734190, upload-time = "2026-01-03T17:30:45.832Z" },
+    { url = "https://files.pythonhosted.org/packages/32/08/de43984c74ed1fca5c014808963cc83cb00d7bb06af228f132d33862ca76/aiohttp-3.13.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:87b9aab6d6ed88235aa2970294f496ff1a1f9adcd724d800e9b952395a80ffd9", size = 491783, upload-time = "2026-01-03T17:30:47.466Z" },
+    { url = "https://files.pythonhosted.org/packages/17/f8/8dd2cf6112a5a76f81f81a5130c57ca829d101ad583ce57f889179accdda/aiohttp-3.13.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:425c126c0dc43861e22cb1c14ba4c8e45d09516d0a3ae0a3f7494b79f5f233a3", size = 490704, upload-time = "2026-01-03T17:30:49.373Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/40/a46b03ca03936f832bc7eaa47cfbb1ad012ba1be4790122ee4f4f8cba074/aiohttp-3.13.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7f9120f7093c2a32d9647abcaf21e6ad275b4fbec5b55969f978b1a97c7c86bf", size = 1720652, upload-time = "2026-01-03T17:30:50.974Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/7e/917fe18e3607af92657e4285498f500dca797ff8c918bd7d90b05abf6c2a/aiohttp-3.13.3-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:697753042d57f4bf7122cab985bf15d0cef23c770864580f5af4f52023a56bd6", size = 1692014, upload-time = "2026-01-03T17:30:52.729Z" },
+    { url = "https://files.pythonhosted.org/packages/71/b6/cefa4cbc00d315d68973b671cf105b21a609c12b82d52e5d0c9ae61d2a09/aiohttp-3.13.3-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6de499a1a44e7de70735d0b39f67c8f25eb3d91eb3103be99ca0fa882cdd987d", size = 1759777, upload-time = "2026-01-03T17:30:54.537Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/e3/e06ee07b45e59e6d81498b591fc589629be1553abb2a82ce33efe2a7b068/aiohttp-3.13.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:37239e9f9a7ea9ac5bf6b92b0260b01f8a22281996da609206a84df860bc1261", size = 1861276, upload-time = "2026-01-03T17:30:56.512Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/24/75d274228acf35ceeb2850b8ce04de9dd7355ff7a0b49d607ee60c29c518/aiohttp-3.13.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f76c1e3fe7d7c8afad7ed193f89a292e1999608170dcc9751a7462a87dfd5bc0", size = 1743131, upload-time = "2026-01-03T17:30:58.256Z" },
+    { url = "https://files.pythonhosted.org/packages/04/98/3d21dde21889b17ca2eea54fdcff21b27b93f45b7bb94ca029c31ab59dc3/aiohttp-3.13.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fc290605db2a917f6e81b0e1e0796469871f5af381ce15c604a3c5c7e51cb730", size = 1556863, upload-time = "2026-01-03T17:31:00.445Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/84/da0c3ab1192eaf64782b03971ab4055b475d0db07b17eff925e8c93b3aa5/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4021b51936308aeea0367b8f006dc999ca02bc118a0cc78c303f50a2ff6afb91", size = 1682793, upload-time = "2026-01-03T17:31:03.024Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/0f/5802ada182f575afa02cbd0ec5180d7e13a402afb7c2c03a9aa5e5d49060/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:49a03727c1bba9a97d3e93c9f93ca03a57300f484b6e935463099841261195d3", size = 1716676, upload-time = "2026-01-03T17:31:04.842Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/8c/714d53bd8b5a4560667f7bbbb06b20c2382f9c7847d198370ec6526af39c/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:3d9908a48eb7416dc1f4524e69f1d32e5d90e3981e4e37eb0aa1cd18f9cfa2a4", size = 1733217, upload-time = "2026-01-03T17:31:06.868Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/79/e2176f46d2e963facea939f5be2d26368ce543622be6f00a12844d3c991f/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2712039939ec963c237286113c68dbad80a82a4281543f3abf766d9d73228998", size = 1552303, upload-time = "2026-01-03T17:31:08.958Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/6a/28ed4dea1759916090587d1fe57087b03e6c784a642b85ef48217b0277ae/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:7bfdc049127717581866fa4708791220970ce291c23e28ccf3922c700740fdc0", size = 1763673, upload-time = "2026-01-03T17:31:10.676Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/35/4a3daeb8b9fab49240d21c04d50732313295e4bd813a465d840236dd0ce1/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8057c98e0c8472d8846b9c79f56766bcc57e3e8ac7bfd510482332366c56c591", size = 1721120, upload-time = "2026-01-03T17:31:12.575Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/9f/d643bb3c5fb99547323e635e251c609fbbc660d983144cfebec529e09264/aiohttp-3.13.3-cp313-cp313-win32.whl", hash = "sha256:1449ceddcdbcf2e0446957863af03ebaaa03f94c090f945411b61269e2cb5daf", size = 427383, upload-time = "2026-01-03T17:31:14.382Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/f1/ab0395f8a79933577cdd996dd2f9aa6014af9535f65dddcf88204682fe62/aiohttp-3.13.3-cp313-cp313-win_amd64.whl", hash = "sha256:693781c45a4033d31d4187d2436f5ac701e7bbfe5df40d917736108c1cc7436e", size = 453899, upload-time = "2026-01-03T17:31:15.958Z" },
+    { url = "https://files.pythonhosted.org/packages/99/36/5b6514a9f5d66f4e2597e40dea2e3db271e023eb7a5d22defe96ba560996/aiohttp-3.13.3-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:ea37047c6b367fd4bd632bff8077449b8fa034b69e812a18e0132a00fae6e808", size = 737238, upload-time = "2026-01-03T17:31:17.909Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/49/459327f0d5bcd8c6c9ca69e60fdeebc3622861e696490d8674a6d0cb90a6/aiohttp-3.13.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:6fc0e2337d1a4c3e6acafda6a78a39d4c14caea625124817420abceed36e2415", size = 492292, upload-time = "2026-01-03T17:31:19.919Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/0b/b97660c5fd05d3495b4eb27f2d0ef18dc1dc4eff7511a9bf371397ff0264/aiohttp-3.13.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c685f2d80bb67ca8c3837823ad76196b3694b0159d232206d1e461d3d434666f", size = 493021, upload-time = "2026-01-03T17:31:21.636Z" },
+    { url = "https://files.pythonhosted.org/packages/54/d4/438efabdf74e30aeceb890c3290bbaa449780583b1270b00661126b8aae4/aiohttp-3.13.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:48e377758516d262bde50c2584fc6c578af272559c409eecbdd2bae1601184d6", size = 1717263, upload-time = "2026-01-03T17:31:23.296Z" },
+    { url = "https://files.pythonhosted.org/packages/71/f2/7bddc7fd612367d1459c5bcf598a9e8f7092d6580d98de0e057eb42697ad/aiohttp-3.13.3-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:34749271508078b261c4abb1767d42b8d0c0cc9449c73a4df494777dc55f0687", size = 1669107, upload-time = "2026-01-03T17:31:25.334Z" },
+    { url = "https://files.pythonhosted.org/packages/00/5a/1aeaecca40e22560f97610a329e0e5efef5e0b5afdf9f857f0d93839ab2e/aiohttp-3.13.3-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:82611aeec80eb144416956ec85b6ca45a64d76429c1ed46ae1b5f86c6e0c9a26", size = 1760196, upload-time = "2026-01-03T17:31:27.394Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/f8/0ff6992bea7bd560fc510ea1c815f87eedd745fe035589c71ce05612a19a/aiohttp-3.13.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2fff83cfc93f18f215896e3a190e8e5cb413ce01553901aca925176e7568963a", size = 1843591, upload-time = "2026-01-03T17:31:29.238Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/d1/e30e537a15f53485b61f5be525f2157da719819e8377298502aebac45536/aiohttp-3.13.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bbe7d4cecacb439e2e2a8a1a7b935c25b812af7a5fd26503a66dadf428e79ec1", size = 1720277, upload-time = "2026-01-03T17:31:31.053Z" },
+    { url = "https://files.pythonhosted.org/packages/84/45/23f4c451d8192f553d38d838831ebbc156907ea6e05557f39563101b7717/aiohttp-3.13.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b928f30fe49574253644b1ca44b1b8adbd903aa0da4b9054a6c20fc7f4092a25", size = 1548575, upload-time = "2026-01-03T17:31:32.87Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/ed/0a42b127a43712eda7807e7892c083eadfaf8429ca8fb619662a530a3aab/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7b5e8fe4de30df199155baaf64f2fcd604f4c678ed20910db8e2c66dc4b11603", size = 1679455, upload-time = "2026-01-03T17:31:34.76Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/b5/c05f0c2b4b4fe2c9d55e73b6d3ed4fd6c9dc2684b1d81cbdf77e7fad9adb/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:8542f41a62bcc58fc7f11cf7c90e0ec324ce44950003feb70640fc2a9092c32a", size = 1687417, upload-time = "2026-01-03T17:31:36.699Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/6b/915bc5dad66aef602b9e459b5a973529304d4e89ca86999d9d75d80cbd0b/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:5e1d8c8b8f1d91cd08d8f4a3c2b067bfca6ec043d3ff36de0f3a715feeedf926", size = 1729968, upload-time = "2026-01-03T17:31:38.622Z" },
+    { url = "https://files.pythonhosted.org/packages/11/3b/e84581290a9520024a08640b63d07673057aec5ca548177a82026187ba73/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:90455115e5da1c3c51ab619ac57f877da8fd6d73c05aacd125c5ae9819582aba", size = 1545690, upload-time = "2026-01-03T17:31:40.57Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/04/0c3655a566c43fd647c81b895dfe361b9f9ad6d58c19309d45cff52d6c3b/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:042e9e0bcb5fba81886c8b4fbb9a09d6b8a00245fd8d88e4d989c1f96c74164c", size = 1746390, upload-time = "2026-01-03T17:31:42.857Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/53/71165b26978f719c3419381514c9690bd5980e764a09440a10bb816ea4ab/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2eb752b102b12a76ca02dff751a801f028b4ffbbc478840b473597fc91a9ed43", size = 1702188, upload-time = "2026-01-03T17:31:44.984Z" },
+    { url = "https://files.pythonhosted.org/packages/29/a7/cbe6c9e8e136314fa1980da388a59d2f35f35395948a08b6747baebb6aa6/aiohttp-3.13.3-cp314-cp314-win32.whl", hash = "sha256:b556c85915d8efaed322bf1bdae9486aa0f3f764195a0fb6ee962e5c71ef5ce1", size = 433126, upload-time = "2026-01-03T17:31:47.463Z" },
+    { url = "https://files.pythonhosted.org/packages/de/56/982704adea7d3b16614fc5936014e9af85c0e34b58f9046655817f04306e/aiohttp-3.13.3-cp314-cp314-win_amd64.whl", hash = "sha256:9bf9f7a65e7aa20dd764151fb3d616c81088f91f8df39c3893a536e279b4b984", size = 459128, upload-time = "2026-01-03T17:31:49.2Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/2a/3c79b638a9c3d4658d345339d22070241ea341ed4e07b5ac60fb0f418003/aiohttp-3.13.3-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:05861afbbec40650d8a07ea324367cb93e9e8cc7762e04dd4405df99fa65159c", size = 769512, upload-time = "2026-01-03T17:31:51.134Z" },
+    { url = "https://files.pythonhosted.org/packages/29/b9/3e5014d46c0ab0db8707e0ac2711ed28c4da0218c358a4e7c17bae0d8722/aiohttp-3.13.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:2fc82186fadc4a8316768d61f3722c230e2c1dcab4200d52d2ebdf2482e47592", size = 506444, upload-time = "2026-01-03T17:31:52.85Z" },
+    { url = "https://files.pythonhosted.org/packages/90/03/c1d4ef9a054e151cd7839cdc497f2638f00b93cbe8043983986630d7a80c/aiohttp-3.13.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0add0900ff220d1d5c5ebbf99ed88b0c1bbf87aa7e4262300ed1376a6b13414f", size = 510798, upload-time = "2026-01-03T17:31:54.91Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/76/8c1e5abbfe8e127c893fe7ead569148a4d5a799f7cf958d8c09f3eedf097/aiohttp-3.13.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:568f416a4072fbfae453dcf9a99194bbb8bdeab718e08ee13dfa2ba0e4bebf29", size = 1868835, upload-time = "2026-01-03T17:31:56.733Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/ac/984c5a6f74c363b01ff97adc96a3976d9c98940b8969a1881575b279ac5d/aiohttp-3.13.3-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:add1da70de90a2569c5e15249ff76a631ccacfe198375eead4aadf3b8dc849dc", size = 1720486, upload-time = "2026-01-03T17:31:58.65Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/9a/b7039c5f099c4eb632138728828b33428585031a1e658d693d41d07d89d1/aiohttp-3.13.3-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:10b47b7ba335d2e9b1239fa571131a87e2d8ec96b333e68b2a305e7a98b0bae2", size = 1847951, upload-time = "2026-01-03T17:32:00.989Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/02/3bec2b9a1ba3c19ff89a43a19324202b8eb187ca1e928d8bdac9bbdddebd/aiohttp-3.13.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3dd4dce1c718e38081c8f35f323209d4c1df7d4db4bab1b5c88a6b4d12b74587", size = 1941001, upload-time = "2026-01-03T17:32:03.122Z" },
+    { url = "https://files.pythonhosted.org/packages/37/df/d879401cedeef27ac4717f6426c8c36c3091c6e9f08a9178cc87549c537f/aiohttp-3.13.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:34bac00a67a812570d4a460447e1e9e06fae622946955f939051e7cc895cfab8", size = 1797246, upload-time = "2026-01-03T17:32:05.255Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/15/be122de1f67e6953add23335c8ece6d314ab67c8bebb3f181063010795a7/aiohttp-3.13.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a19884d2ee70b06d9204b2727a7b9f983d0c684c650254679e716b0b77920632", size = 1627131, upload-time = "2026-01-03T17:32:07.607Z" },
+    { url = "https://files.pythonhosted.org/packages/12/12/70eedcac9134cfa3219ab7af31ea56bc877395b1ac30d65b1bc4b27d0438/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:5f8ca7f2bb6ba8348a3614c7918cc4bb73268c5ac2a207576b7afea19d3d9f64", size = 1795196, upload-time = "2026-01-03T17:32:09.59Z" },
+    { url = "https://files.pythonhosted.org/packages/32/11/b30e1b1cd1f3054af86ebe60df96989c6a414dd87e27ad16950eee420bea/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:b0d95340658b9d2f11d9697f59b3814a9d3bb4b7a7c20b131df4bcef464037c0", size = 1782841, upload-time = "2026-01-03T17:32:11.445Z" },
+    { url = "https://files.pythonhosted.org/packages/88/0d/d98a9367b38912384a17e287850f5695c528cff0f14f791ce8ee2e4f7796/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:a1e53262fd202e4b40b70c3aff944a8155059beedc8a89bba9dc1f9ef06a1b56", size = 1795193, upload-time = "2026-01-03T17:32:13.705Z" },
+    { url = "https://files.pythonhosted.org/packages/43/a5/a2dfd1f5ff5581632c7f6a30e1744deda03808974f94f6534241ef60c751/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:d60ac9663f44168038586cab2157e122e46bdef09e9368b37f2d82d354c23f72", size = 1621979, upload-time = "2026-01-03T17:32:15.965Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/f0/12973c382ae7c1cccbc4417e129c5bf54c374dfb85af70893646e1f0e749/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:90751b8eed69435bac9ff4e3d2f6b3af1f57e37ecb0fbeee59c0174c9e2d41df", size = 1822193, upload-time = "2026-01-03T17:32:18.219Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/5f/24155e30ba7f8c96918af1350eb0663e2430aad9e001c0489d89cd708ab1/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:fc353029f176fd2b3ec6cfc71be166aba1936fe5d73dd1992ce289ca6647a9aa", size = 1769801, upload-time = "2026-01-03T17:32:20.25Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/f8/7314031ff5c10e6ece114da79b338ec17eeff3a079e53151f7e9f43c4723/aiohttp-3.13.3-cp314-cp314t-win32.whl", hash = "sha256:2e41b18a58da1e474a057b3d35248d8320029f61d70a37629535b16a0c8f3767", size = 466523, upload-time = "2026-01-03T17:32:22.215Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/63/278a98c715ae467624eafe375542d8ba9b4383a016df8fdefe0ae28382a7/aiohttp-3.13.3-cp314-cp314t-win_amd64.whl", hash = "sha256:44531a36aa2264a1860089ffd4dce7baf875ee5a6079d5fb42e261c704ef7344", size = 499694, upload-time = "2026-01-03T17:32:24.546Z" },
 ]
 
 [[package]]
@@ -274,14 +274,14 @@ wheels = [
 
 [[package]]
 name = "click"
-version = "8.1.8"
+version = "8.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b9/2e/0090cbf739cee7d23781ad4b89a9894a41538e4fcf4c31dcdd705b78eb8b/click-8.1.8.tar.gz", hash = "sha256:ed53c9d8990d83c2a27deae68e4ee337473f6330c040a31d4225c9574d16096a", size = 226593, upload-time = "2024-12-21T18:38:44.339Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/7e/d4/7ebdbd03970677812aac39c869717059dbb71a4cfc033ca6e5221787892c/click-8.1.8-py3-none-any.whl", hash = "sha256:63c132bbbed01578a06712a2d1f497bb62d9c1c0d329b7903a866228027263b2", size = 98188, upload-time = "2024-12-21T18:38:41.666Z" },
+    { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" },
 ]
 
 [[package]]
@@ -644,11 +644,11 @@ requires-dist = [
     { name = "coverage", marker = "extra == 'dev'", specifier = ">=7.6.0" },
     { name = "datasets", specifier = ">=3.0.0" },
     { name = "hypothesis", marker = "extra == 'dev'", specifier = ">=6.88.0" },
-    { name = "litellm", specifier = "!=1.82.7,!=1.82.8,>=1.83.7" },
+    { name = "litellm", specifier = ">=1.50.0" },
     { name = "mini-swe-agent", specifier = ">=2.0.0" },
     { name = "pandas", specifier = ">=2.0.0" },
-    { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" },
-    { name = "python-dotenv", specifier = ">=1.2.2" },
+    { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0.0" },
+    { name = "python-dotenv", specifier = ">=1.0.0" },
     { name = "pyyaml", specifier = ">=6.0" },
     { name = "rich", specifier = ">=13.0.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.5.0" },
@@ -769,14 +769,14 @@ wheels = [
 
 [[package]]
 name = "importlib-metadata"
-version = "8.5.0"
+version = "9.0.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "zipp" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/cd/12/33e59336dca5be0c398a7482335911a33aa0e20776128f038019f1a95f1b/importlib_metadata-8.5.0.tar.gz", hash = "sha256:71522656f0abace1d072b9e5481a48f07c138e00f079c38c8f883823f9c26bd7", size = 55304, upload-time = "2024-09-11T14:56:08.937Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a9/01/15bb152d77b21318514a96f43af312635eb2500c96b55398d020c93d86ea/importlib_metadata-9.0.0.tar.gz", hash = "sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc", size = 56405, upload-time = "2026-03-20T06:42:56.999Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a0/d9/a1e041c5e7caa9a05c925f4bdbdfb7f006d1f74996af53467bc394c97be7/importlib_metadata-8.5.0-py3-none-any.whl", hash = "sha256:45e54197d28b7a7f1559e60b95e7c567032b602131fbd588f1497f47880aa68b", size = 26514, upload-time = "2024-09-11T14:56:07.019Z" },
+    { url = "https://files.pythonhosted.org/packages/38/3d/2d244233ac4f76e38533cfcb2991c9eb4c7bf688ae0a036d30725b8faafe/importlib_metadata-9.0.0-py3-none-any.whl", hash = "sha256:2d21d1cc5a017bd0559e36150c21c830ab1dc304dedd1b7ea85d20f45ef3edd7", size = 27789, upload-time = "2026-03-20T06:42:55.665Z" },
 ]
 
 [[package]]
@@ -887,7 +887,7 @@ wheels = [
 
 [[package]]
 name = "jsonschema"
-version = "4.23.0"
+version = "4.26.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "attrs" },
@@ -895,9 +895,9 @@ dependencies = [
     { name = "referencing" },
     { name = "rpds-py" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/38/2e/03362ee4034a4c917f697890ccd4aec0800ccf9ded7f511971c75451deec/jsonschema-4.23.0.tar.gz", hash = "sha256:d71497fef26351a33265337fa77ffeb82423f3ea21283cd9467bb03999266bc4", size = 325778, upload-time = "2024-07-08T18:40:05.546Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/69/4a/4f9dbeb84e8850557c02365a0eee0649abe5eb1d84af92a25731c6c0f922/jsonschema-4.23.0-py3-none-any.whl", hash = "sha256:fbadb6f8b144a8f8cf9f0b89ba94501d143e50411a1278633f56a7acf7fd5566", size = 88462, upload-time = "2024-07-08T18:40:00.165Z" },
+    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
 ]
 
 [[package]]
@@ -926,7 +926,7 @@ wheels = [
 
 [[package]]
 name = "litellm"
-version = "1.83.14"
+version = "1.82.6"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -942,9 +942,9 @@ dependencies = [
     { name = "tiktoken" },
     { name = "tokenizers" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/8d/7c/c095649380adc96c8630273c1768c2ad1e74aa2ee1dd8dd05d218a60569f/litellm-1.83.14.tar.gz", hash = "sha256:24aef9b47cdc424c833e32f3727f411741c690832cd1fe4405e0077144fe09c9", size = 14836599, upload-time = "2026-04-26T03:16:10.176Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/29/75/1c537aa458426a9127a92bc2273787b2f987f4e5044e21f01f2eed5244fd/litellm-1.82.6.tar.gz", hash = "sha256:2aa1c2da21fe940c33613aa447119674a3ad4d2ad5eb064e4d5ce5ee42420136", size = 17414147, upload-time = "2026-03-22T06:36:00.452Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/7f/5c/1b5691575420135e90578543b2bf219497caa33cfd0af64cb38f30288450/litellm-1.83.14-py3-none-any.whl", hash = "sha256:92b11ba2a32cf80707ddf388d18526696c7999a21b418c5e3b6eda1243d2cfdb", size = 16457054, upload-time = "2026-04-26T03:16:05.72Z" },
+    { url = "https://files.pythonhosted.org/packages/02/6c/5327667e6dbe9e98cbfbd4261c8e91386a52e38f41419575854248bbab6a/litellm-1.82.6-py3-none-any.whl", hash = "sha256:164a3ef3e19f309e3cabc199bef3d2045212712fefdfa25fc7f75884a5b5b205", size = 15591595, upload-time = "2026-03-22T06:35:56.795Z" },
 ]
 
 [[package]]
@@ -1302,7 +1302,7 @@ wheels = [
 
 [[package]]
 name = "openai"
-version = "2.24.0"
+version = "2.29.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -1314,9 +1314,9 @@ dependencies = [
     { name = "tqdm" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/55/13/17e87641b89b74552ed408a92b231283786523edddc95f3545809fab673c/openai-2.24.0.tar.gz", hash = "sha256:1e5769f540dbd01cb33bc4716a23e67b9d695161a734aff9c5f925e2bf99a673", size = 658717, upload-time = "2026-02-24T20:02:07.958Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b4/15/203d537e58986b5673e7f232453a2a2f110f22757b15921cbdeea392e520/openai-2.29.0.tar.gz", hash = "sha256:32d09eb2f661b38d3edd7d7e1a2943d1633f572596febe64c0cd370c86d52bec", size = 671128, upload-time = "2026-03-17T17:53:49.599Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c9/30/844dc675ee6902579b8eef01ed23917cc9319a1c9c0c14ec6e39340c96d0/openai-2.24.0-py3-none-any.whl", hash = "sha256:fed30480d7d6c884303287bde864980a4b137b60553ffbcf9ab4a233b7a73d94", size = 1120122, upload-time = "2026-02-24T20:02:05.669Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/b1/35b6f9c8cf9318e3dbb7146cc82dab4cf61182a8d5406fc9b50864362895/openai-2.29.0-py3-none-any.whl", hash = "sha256:b7c5de513c3286d17c5e29b92c4c98ceaf0d775244ac8159aeb1bddf840eb42a", size = 1141533, upload-time = "2026-03-17T17:53:47.348Z" },
 ]
 
 [[package]]
@@ -1690,7 +1690,7 @@ wheels = [
 
 [[package]]
 name = "pytest"
-version = "9.0.3"
+version = "9.0.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
@@ -1699,9 +1699,9 @@ dependencies = [
     { name = "pluggy" },
     { name = "pygments" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
 ]
 
 [[package]]
@@ -1900,7 +1900,7 @@ wheels = [
 
 [[package]]
 name = "requests"
-version = "2.33.0"
+version = "2.32.5"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "certifi" },
@@ -1908,9 +1908,9 @@ dependencies = [
     { name = "idna" },
     { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/34/64/8860370b167a9721e8956ae116825caff829224fbca0ca6e7bf8ddef8430/requests-2.33.0.tar.gz", hash = "sha256:c7ebc5e8b0f21837386ad0e1c8fe8b829fa5f544d8df3b2253bff14ef29d7652", size = 134232, upload-time = "2026-03-25T15:10:41.586Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/56/5d/c814546c2333ceea4ba42262d8c4d55763003e767fa169adc693bd524478/requests-2.33.0-py3-none-any.whl", hash = "sha256:3324635456fa185245e24865e810cecec7b4caf933d7eb133dcde67d48cee69b", size = 65017, upload-time = "2026-03-25T15:10:40.382Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
 ]
 
 [[package]]
@@ -2224,7 +2224,7 @@ wheels = [
 
 [[package]]
 name = "typer"
-version = "0.23.1"
+version = "0.24.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "annotated-doc" },
@@ -2232,9 +2232,9 @@ dependencies = [
     { name = "rich" },
     { name = "shellingham" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/fd/07/b822e1b307d40e263e8253d2384cf98c51aa2368cc7ba9a07e523a1d964b/typer-0.23.1.tar.gz", hash = "sha256:2070374e4d31c83e7b61362fd859aa683576432fd5b026b060ad6b4cd3b86134", size = 120047, upload-time = "2026-02-13T10:04:30.984Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d5/91/9b286ab899c008c2cb05e8be99814807e7fbbd33f0c0c960470826e5ac82/typer-0.23.1-py3-none-any.whl", hash = "sha256:3291ad0d3c701cbf522012faccfbb29352ff16ad262db2139e6b01f15781f14e", size = 56813, upload-time = "2026-02-13T10:04:32.008Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" },
 ]
 
 [[package]]

gitnexus-claude-plugin/hooks/gitnexus-hook.js

@@ -31,25 +31,11 @@ function readInput() {
  * Find the .gitnexus directory by walking up from startDir.
  * Returns the path to .gitnexus/ or null if not found.
  */
-function isGlobalRegistryDir(candidate) {
-  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
-  return (
-    fs.existsSync(path.join(candidate, 'registry.json')) ||
-    fs.existsSync(path.join(candidate, 'repos'))
-  );
-}
-
-/**
- * Walk up from `startDir` looking for a non-registry `.gitnexus/` folder.
- * Returns the path to `.gitnexus/` or null if not found within 5 levels.
- */
-function walkForGitNexusDir(startDir) {
-  let dir = startDir;
+function findGitNexusDir(startDir) {
+  let dir = startDir || process.cwd();
   for (let i = 0; i < 5; i++) {
     const candidate = path.join(dir, '.gitnexus');
-    if (fs.existsSync(candidate)) {
-      if (!isGlobalRegistryDir(candidate)) return candidate;
-    }
+    if (fs.existsSync(candidate)) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
@@ -57,51 +43,6 @@ function walkForGitNexusDir(startDir) {
   return null;
 }
 
-/**
- * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside
- * any git working tree — including a *linked* worktree created via
- * `git worktree add`. Linked worktrees never contain `.gitnexus/`, so the
- * upward walk from cwd alone misses the index. Returns null when `cwd` is
- * not inside a git repo or `git` is not available.
- *
- * Implementation: `git rev-parse --git-common-dir` resolves to the canonical
- * `.git/` directory (or `.git/worktrees/...` parent) that is shared across
- * all linked worktrees. The canonical repo root is its parent directory.
- */
-function findCanonicalRepoRoot(cwd) {
-  try {
-    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
-      encoding: 'utf-8',
-      timeout: 2000,
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    if (result.error || result.status !== 0) return null;
-    const commonDir = (result.stdout || '').trim();
-    if (!commonDir || !path.isAbsolute(commonDir)) return null;
-    return path.dirname(commonDir);
-  } catch {
-    return null;
-  }
-}
-
-function findGitNexusDir(startDir) {
-  const cwd = startDir || process.cwd();
-
-  // Fast path: the cwd is inside the canonical repo (most common case).
-  const fromCwd = walkForGitNexusDir(cwd);
-  if (fromCwd) return fromCwd;
-
-  // Fallback: cwd may be inside a linked git worktree whose `.gitnexus/`
-  // only lives in the canonical repo root. Resolve the shared git dir
-  // and retry from there.
-  const canonicalRoot = findCanonicalRepoRoot(cwd);
-  if (canonicalRoot && canonicalRoot !== cwd) {
-    return walkForGitNexusDir(canonicalRoot);
-  }
-  return null;
-}
-
 /**
  * Extract search pattern from tool input.
  */

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

@@ -21,7 +21,6 @@ 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. |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
 

gitnexus-cursor-integration/README.md

@@ -1,89 +0,0 @@
-# GitNexus — Cursor integration
-
-Static config that adds GitNexus knowledge-graph augmentation and skill files to Cursor.
-
-> **Hooks require Cursor 2.4+.** Earlier versions don't expose `postToolUse` and the hook will silently no-op.
-
-## What you get
-
-| Layer                     | What it does                                                                                                                              | How it's installed                                                              |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| **MCP**                   | `gitnexus` MCP server with 16 tools (`query`, `context`, `impact`, `detect_changes`, `rename`, …)                                         | `npx gitnexus setup` writes `~/.cursor/mcp.json` automatically.                 |
-| **Skills**                | `/gitnexus-exploring`, `/gitnexus-debugging`, `/gitnexus-impact-analysis`, `/gitnexus-refactoring`, `/gitnexus-pr-review` markdown skills | `npx gitnexus setup` copies them to `~/.cursor/skills/gitnexus/`.               |
-| **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets             | **Manual** — copy the two files described below into your project's `.cursor/`. |
-
-## Hook install
-
-Cursor 2.4+ reads `.cursor/hooks.json` from the project root and runs hook commands with the project root as the working directory ([docs](https://cursor.com/docs/agent/hooks)).
-
-From this repo's `gitnexus-cursor-integration/hooks/`, copy the two files into your **project root**:
-
-```text
-<your-project>/
-├── .cursor/
-│   └── hooks.json              ← from gitnexus-cursor-integration/hooks/hooks.json
-└── hooks/
-    └── gitnexus-hook.cjs       ← from gitnexus-cursor-integration/hooks/gitnexus-hook.cjs
-```
-
-Equivalent shell commands (run from your project root, with `$GITNEXUS_REPO` pointing at a clone of this repo):
-
-```bash
-mkdir -p .cursor hooks
-cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/hooks.json"        .cursor/hooks.json
-cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs" hooks/gitnexus-hook.cjs
-```
-
-If you already have a `.cursor/hooks.json`, merge the `hooks.postToolUse` array rather than overwriting.
-
-### Verify
-
-1. Index the project: `npx gitnexus analyze`
-2. Reload the Cursor window so it picks up the new hook config.
-3. Ask the agent something that triggers `Read` / `Grep` / `Shell rg`. You should see a `[GitNexus]` block appended to the tool result.
-4. Diagnose silent no-ops by setting `GITNEXUS_DEBUG=1` in your shell environment — the hook will write Cursor's raw event payload to stderr so you can verify field names.
-
-### What's installed manually vs. automated
-
-| Step                                                                 | Automated by `gitnexus setup`? |
-| -------------------------------------------------------------------- | ------------------------------ |
-| `~/.cursor/mcp.json`                                                 | ✅                             |
-| `~/.cursor/skills/gitnexus/*`                                        | ✅                             |
-| `<project>/.cursor/hooks.json` + `<project>/hooks/gitnexus-hook.cjs` | ❌ — copy manually (see above) |
-
-Hook install is per-project (Cursor scopes hooks to a project root); skills and MCP config are global.
-
-## Hook contract
-
-The hook receives a JSON event on stdin matching Cursor 2.4's `postToolUse` shape:
-
-```json
-{
-  "tool_name": "Grep" | "Read" | "Shell",
-  "tool_input": { /* tool-specific */ },
-  "tool_output": { /* optional */ },
-  "cwd": "/absolute/path/to/project"
-}
-```
-
-It writes augmentation context to stdout as:
-
-```json
-{ "additional_context": "[GitNexus] …" }
-```
-
-Empty stdout means "no augmentation, continue normally" — the hook never blocks the tool.
-
-### Pattern extraction per tool
-
-| Tool    | Pattern source                                                                                                         | Notes                                                                                                |
-| ------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `Grep`  | `tool_input.query` (also `pattern`, `regex`, `q`, `search`, `searchQuery`)                                             | Last-resort fallback: longest string value in `tool_input` (≥ 3 chars).                              |
-| `Read`  | basename of `tool_input.target_file` (also `file_path`, `filePath`, `path`, `file`), stripped to identifier characters | `auth/handler.ts` → `handler`.                                                                       |
-| `Shell` | First positional argument after `rg` / `grep` in `tool_input.command`                                                  | Best-effort tokenizer; quoted multi-word patterns (`rg "User Service"`) extract the first word only. |
-
-## Troubleshooting
-
-- **Nothing happens** — Confirm Cursor is on 2.4+ and the project root has both `.cursor/hooks.json` and the script at `hooks/gitnexus-hook.cjs`. Then `npx gitnexus list` to confirm the project is indexed.
-- **`gitnexus` not found** — The hook prefers a locally-resolvable `gitnexus/dist/cli/index.js` and falls back to `npx -y gitnexus`. Install globally with `npm i -g gitnexus` to skip the npx cold-start latency.
-- **Wrong pattern extracted** — Set `GITNEXUS_DEBUG=1` and run a tool call. The raw stdin payload is logged to stderr; use it to confirm Cursor's actual `tool_input` field names against the table above. If they differ, file an issue with the captured payload.

gitnexus-cursor-integration/hooks/augment-shell.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# GitNexus beforeShellExecution hook for Cursor
+# Receives JSON on stdin with { command, cwd, timeout }
+# Returns JSON on stdout with { permission, agent_message }
+#
+# Extracts search pattern from grep/rg commands, runs gitnexus augment,
+# and injects the enriched context via agent_message.
+
+INPUT=$(cat)
+
+COMMAND=$(echo "$INPUT" | jq -r '.command // empty' 2>/dev/null)
+
+if [ -z "$COMMAND" ]; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+
+# Skip non-search commands
+case "$COMMAND" in
+  cd\ *|npm\ *|yarn\ *|pnpm\ *|git\ commit*|git\ push*|git\ pull*|mkdir\ *|rm\ *|cp\ *|mv\ *|echo\ *|cat\ *)
+    echo '{"permission":"allow"}'
+    exit 0
+    ;;
+esac
+
+# Extract search pattern from rg/grep commands
+PATTERN=""
+if echo "$COMMAND" | grep -qE '\brg\b'; then
+  PATTERN=$(echo "$COMMAND" | sed -n "s/.*\brg\s\+\(--[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+elif echo "$COMMAND" | grep -qE '\bgrep\b'; then
+  PATTERN=$(echo "$COMMAND" | sed -n "s/.*\bgrep\s\+\(-[^ ]*\s\+\)*['\"]\\?\([^'\";\| >]*\\).*/\2/p")
+fi
+
+if [ -z "$PATTERN" ] || [ ${#PATTERN} -lt 3 ]; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+
+# Run gitnexus augment
+RESULT=$(npx -y gitnexus augment "$PATTERN" 2>/dev/null)
+
+if [ -n "$RESULT" ]; then
+  # Escape for JSON
+  ESCAPED=$(echo "$RESULT" | jq -Rs .)
+  echo "{\"permission\":\"allow\",\"agent_message\":$ESCAPED}"
+else
+  echo '{"permission":"allow"}'
+fi
+
+exit 0

gitnexus-cursor-integration/hooks/gitnexus-hook.cjs

@@ -1,259 +0,0 @@
-#!/usr/bin/env node
-/**
- * GitNexus Cursor postToolUse Hook
- *
- * Receives a JSON event on stdin describing a finished tool call, derives a
- * search pattern (Grep query, Read file basename, or rg/grep arg from a Shell
- * command), runs `gitnexus augment <pattern>`, and emits the enriched context
- * back as `{ additional_context: "..." }` so the agent sees it alongside the
- * tool result.
- *
- * Replaces the legacy beforeShellExecution / augment-shell.sh pipeline:
- *   - Cross-platform (no bash, no jq — runs on Windows out of the box)
- *   - Covers Read and Grep, not just Shell rg/grep
- *
- * Cursor 2.4+ generic hooks: https://cursor.com/docs/agent/hooks
- */
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-function readInput() {
-  try {
-    const data = fs.readFileSync(0, 'utf-8');
-    return JSON.parse(data);
-  } catch {
-    return {};
-  }
-}
-
-function isGlobalRegistryDir(candidate) {
-  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
-  return (
-    fs.existsSync(path.join(candidate, 'registry.json')) ||
-    fs.existsSync(path.join(candidate, 'repos'))
-  );
-}
-
-function walkForGitNexusDir(startDir) {
-  let dir = startDir;
-  for (let i = 0; i < 5; i++) {
-    const candidate = path.join(dir, '.gitnexus');
-    if (fs.existsSync(candidate)) {
-      if (!isGlobalRegistryDir(candidate)) return candidate;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
-function findCanonicalRepoRoot(cwd) {
-  try {
-    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
-      encoding: 'utf-8',
-      timeout: 2000,
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    if (result.error || result.status !== 0) return null;
-    const commonDir = (result.stdout || '').trim();
-    if (!commonDir || !path.isAbsolute(commonDir)) return null;
-    return path.dirname(commonDir);
-  } catch {
-    return null;
-  }
-}
-
-function findGitNexusDir(startDir) {
-  const cwd = startDir || process.cwd();
-  const fromCwd = walkForGitNexusDir(cwd);
-  if (fromCwd) return fromCwd;
-  const canonicalRoot = findCanonicalRepoRoot(cwd);
-  if (canonicalRoot && canonicalRoot !== cwd) {
-    return walkForGitNexusDir(canonicalRoot);
-  }
-  return null;
-}
-
-function parseRgGrepPattern(cmd) {
-  const tokens = cmd.split(/\s+/);
-  let foundCmd = false;
-  let skipNext = false;
-  const flagsWithValues = new Set([
-    '-e',
-    '-f',
-    '-m',
-    '-A',
-    '-B',
-    '-C',
-    '-g',
-    '--glob',
-    '-t',
-    '--type',
-    '--include',
-    '--exclude',
-  ]);
-
-  for (const token of tokens) {
-    if (skipNext) {
-      skipNext = false;
-      continue;
-    }
-    if (!foundCmd) {
-      if (/\brg$|\bgrep$/.test(token)) foundCmd = true;
-      continue;
-    }
-    if (token.startsWith('-')) {
-      if (flagsWithValues.has(token)) skipNext = true;
-      continue;
-    }
-    const cleaned = token.replace(/['"]/g, '');
-    return cleaned.length >= 3 ? cleaned : null;
-  }
-  return null;
-}
-
-/**
- * Extract a search pattern from the tool input. Cursor 2.4 docs at
- * https://cursor.com/docs/agent/hooks list the tool *matchers* but do not
- * formally specify the per-tool tool_input field names, so we probe a
- * generous set of MCP-style aliases. As a last-resort fallback for Grep
- * (the highest-frequency search path) we also accept the longest plausible
- * string value in tool_input. Set GITNEXUS_DEBUG=1 to log the raw payload
- * to stderr if Cursor changes the contract and aliases stop matching.
- */
-function pickLongestStringValue(obj) {
-  let best = null;
-  if (!obj || typeof obj !== 'object') return null;
-  for (const v of Object.values(obj)) {
-    if (typeof v === 'string' && v.length >= 3 && (!best || v.length > best.length)) {
-      best = v;
-    }
-  }
-  return best;
-}
-
-function extractPattern(toolName, toolInput) {
-  const t = (toolName || '').toLowerCase();
-
-  if (t === 'grep') {
-    const aliases = [
-      toolInput.query,
-      toolInput.pattern,
-      toolInput.regex,
-      toolInput.q,
-      toolInput.search,
-      toolInput.searchQuery,
-    ];
-    for (const a of aliases) {
-      if (typeof a === 'string' && a.length >= 3) return a;
-    }
-    // Last resort: scan tool_input for any reasonable-looking string value.
-    return pickLongestStringValue(toolInput);
-  }
-
-  if (t === 'read') {
-    const filePath =
-      toolInput.target_file ||
-      toolInput.file_path ||
-      toolInput.filePath ||
-      toolInput.path ||
-      toolInput.file ||
-      '';
-    if (!filePath) return null;
-    const base = path.basename(String(filePath), path.extname(String(filePath)));
-    const cleaned = base.replace(/[^a-zA-Z0-9_]/g, '');
-    return cleaned.length >= 3 ? cleaned : null;
-  }
-
-  if (t === 'shell') {
-    const cmd = toolInput.command || '';
-    if (!/\brg\b|\bgrep\b/.test(cmd)) return null;
-    // NOTE: parseRgGrepPattern uses split(/\s+/) and cannot handle shell
-    // quoting. `rg "User Service" src/` returns "User" (the first token
-    // after the rg/grep arg, with surrounding quotes stripped) — the
-    // multi-word pattern is intentionally not reconstructed since BM25 is
-    // already token-tolerant. Quoted single tokens (`rg "validateUser"`)
-    // work fine.
-    return parseRgGrepPattern(cmd);
-  }
-
-  return null;
-}
-
-function resolveCliPath() {
-  try {
-    return require.resolve('gitnexus/dist/cli/index.js');
-  } catch {
-    return '';
-  }
-}
-
-function runGitNexusCli(cliPath, args, cwd, timeout) {
-  const isWin = process.platform === 'win32';
-  if (cliPath) {
-    return spawnSync(process.execPath, [cliPath, ...args], {
-      encoding: 'utf-8',
-      timeout,
-      cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-  }
-  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
-    encoding: 'utf-8',
-    timeout: timeout + 5000,
-    cwd,
-    stdio: ['pipe', 'pipe', 'pipe'],
-  });
-}
-
-function main() {
-  try {
-    const input = readInput();
-    if (process.env.GITNEXUS_DEBUG) {
-      // Echo the payload so users can capture Cursor's actual contract when
-      // diagnosing why augmentation isn't firing. Stderr only — stdout is
-      // reserved for the JSON response Cursor consumes.
-      try {
-        process.stderr.write(
-          `GitNexus Cursor hook stdin: ${JSON.stringify(input).slice(0, 500)}\n`,
-        );
-      } catch {
-        /* never let debug logging break the hook */
-      }
-    }
-    const cwd = input.cwd || process.cwd();
-    if (!path.isAbsolute(cwd)) return;
-    if (!findGitNexusDir(cwd)) return;
-
-    const toolName = input.tool_name || '';
-    const toolInput = input.tool_input || {};
-
-    const pattern = extractPattern(toolName, toolInput);
-    if (!pattern || pattern.length < 3) return;
-
-    const cliPath = resolveCliPath();
-    let result = '';
-    try {
-      const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
-      if (!child.error && child.status === 0) {
-        result = child.stderr || '';
-      }
-    } catch {
-      /* graceful failure */
-    }
-
-    if (result && result.trim()) {
-      console.log(JSON.stringify({ additional_context: result.trim() }));
-    }
-  } catch (err) {
-    if (process.env.GITNEXUS_DEBUG) {
-      console.error('GitNexus Cursor hook error:', (err.message || '').slice(0, 200));
-    }
-  }
-}
-
-main();

gitnexus-cursor-integration/hooks/hooks.json

@@ -1,11 +1,11 @@
 {
   "version": 1,
   "hooks": {
-    "postToolUse": [
+    "beforeShellExecution": [
       {
-        "matcher": "Shell|Read|Grep",
-        "command": "node ./hooks/gitnexus-hook.cjs",
-        "timeout": 10
+        "command": "./hooks/augment-shell.sh",
+        "timeout": 5,
+        "matcher": "\\brg\\b|\\bgrep\\b"
       }
     ]
   }

gitnexus-shared/package-lock.json

@@ -8,13 +8,13 @@
       "name": "gitnexus-shared",
       "version": "1.0.0",
       "devDependencies": {
-        "typescript": "^6.0.3"
+        "typescript": "^6.0.2"
       }
     },
     "node_modules/typescript": {
-      "version": "6.0.3",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
-      "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.2.tgz",
+      "integrity": "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {

gitnexus-shared/package.json

@@ -10,10 +10,6 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    },
-    "./test-helpers": {
-      "types": "./dist/test-helpers.d.ts",
-      "default": "./dist/test-helpers.js"
     }
   },
   "scripts": {
@@ -24,6 +20,6 @@
     "src"
   ],
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.2"
   }
 }

gitnexus-shared/src/graph/types.ts

@@ -131,20 +131,4 @@ export interface GraphRelationship {
   confidence: number;
   reason: string;
   step?: number;
-  /**
-   * Per-signal evidence trace for edges emitted by the scope-based
-   * resolution pipeline (RFC #909 Ring 2 PKG #925). Populated by
-   * `emit-references.ts` when draining `ReferenceIndex` into the graph
-   * so downstream query / audit tools can inspect *why* a given edge
-   * was emitted with its confidence value.
-   *
-   * Optional and additive — every existing edge emitter ignores this
-   * field, and every existing query continues to work whether or not
-   * an edge carries it.
-   */
-  evidence?: readonly {
-    readonly kind: string;
-    readonly weight: number;
-    readonly note?: string;
-  }[];
 }

gitnexus-shared/src/index.ts

@@ -23,160 +23,3 @@ export type { MroStrategy } from './mro-strategy.js';
 
 // Pipeline progress
 export type { PipelinePhase, PipelineProgress } from './pipeline.js';
-
-// ─── Scope-based resolution — RFC #909 (Ring 1 #910) ────────────────────────
-// Data model (RFC §2)
-export type { SymbolDefinition } from './scope-resolution/symbol-definition.js';
-export type {
-  ScopeId,
-  DefId,
-  ScopeKind,
-  Range,
-  Capture,
-  CaptureMatch,
-  BindingRef,
-  ImportEdge,
-  TypeRef,
-  Scope,
-  ResolutionEvidence,
-  Resolution,
-  Reference,
-  ReferenceIndex,
-  LookupParams,
-  RegistryContributor,
-  ParsedImport,
-  ParsedTypeBinding,
-  WorkspaceIndex,
-  Callsite,
-  ScopeLookup,
-} from './scope-resolution/types.js';
-
-// Evidence + tie-break constants (RFC Appendix A, Appendix B)
-export { EvidenceWeights, typeBindingWeightAtDepth } from './scope-resolution/evidence-weights.js';
-export { ORIGIN_PRIORITY } from './scope-resolution/origin-priority.js';
-export type { OriginForTieBreak } from './scope-resolution/origin-priority.js';
-
-// Language classification (RFC §6.1 Ring 3/4 governance)
-export {
-  LanguageClassifications,
-  isProductionLanguage,
-} from './scope-resolution/language-classification.js';
-export type { LanguageClassification } from './scope-resolution/language-classification.js';
-
-// Core indexes over per-file artifacts (RFC §3.1; Ring 2 SHARED #913)
-export { buildDefIndex } from './scope-resolution/def-index.js';
-export type { DefIndex } from './scope-resolution/def-index.js';
-export { buildModuleScopeIndex } from './scope-resolution/module-scope-index.js';
-export type { ModuleScopeIndex, ModuleScopeEntry } from './scope-resolution/module-scope-index.js';
-export { buildQualifiedNameIndex } from './scope-resolution/qualified-name-index.js';
-export type { QualifiedNameIndex } from './scope-resolution/qualified-name-index.js';
-
-// Strict type-reference resolver (RFC §4.6; Ring 2 SHARED #916)
-// `ScopeLookup` is defined in `./scope-resolution/types.js` and exported
-// from the type-export block above — not from this module.
-export { resolveTypeRef } from './scope-resolution/resolve-type-ref.js';
-export type { ResolveTypeRefContext } from './scope-resolution/resolve-type-ref.js';
-
-// ScopeExtractor output contracts (RFC §3.2 Phase 1; Ring 2 PKG #919)
-export type { ParsedFile } from './scope-resolution/parsed-file.js';
-export type { ReferenceSite, ReferenceKind, CallForm } from './scope-resolution/reference-site.js';
-
-// Method-dispatch materialized view over HeritageMap (RFC §3.1; Ring 2 SHARED #914)
-export { buildMethodDispatchIndex } from './scope-resolution/method-dispatch-index.js';
-export type {
-  MethodDispatchIndex,
-  MethodDispatchInput,
-} from './scope-resolution/method-dispatch-index.js';
-
-// SCC-aware cross-file finalize (RFC §3.2 Phase 2; Ring 2 SHARED #915)
-export { finalize } from './scope-resolution/finalize-algorithm.js';
-export type {
-  FinalizeInput,
-  FinalizeFile,
-  FinalizeHooks,
-  FinalizeOutput,
-  FinalizedScc,
-  FinalizeStats,
-} from './scope-resolution/finalize-algorithm.js';
-
-// Scope-aware registries + 7-step lookup (RFC §4; Ring 2 SHARED #917)
-export { buildClassRegistry } from './scope-resolution/registries/class-registry.js';
-export type { ClassRegistry } from './scope-resolution/registries/class-registry.js';
-export { buildMethodRegistry } from './scope-resolution/registries/method-registry.js';
-export type {
-  MethodRegistry,
-  MethodLookupOptions,
-} from './scope-resolution/registries/method-registry.js';
-export { buildFieldRegistry } from './scope-resolution/registries/field-registry.js';
-export type {
-  FieldRegistry,
-  FieldLookupOptions,
-} from './scope-resolution/registries/field-registry.js';
-export { lookupCore } from './scope-resolution/registries/lookup-core.js';
-export type { CoreLookupParams } from './scope-resolution/registries/lookup-core.js';
-export { lookupQualified } from './scope-resolution/registries/lookup-qualified.js';
-export type { LookupQualifiedParams } from './scope-resolution/registries/lookup-qualified.js';
-export { composeEvidence, confidenceFromEvidence } from './scope-resolution/registries/evidence.js';
-export type { RawSignals } from './scope-resolution/registries/evidence.js';
-export {
-  compareByConfidenceWithTiebreaks,
-  CONFIDENCE_EPSILON,
-} from './scope-resolution/registries/tie-breaks.js';
-export type { TieBreakKey } from './scope-resolution/registries/tie-breaks.js';
-export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS } from './scope-resolution/registries/context.js';
-export type {
-  RegistryContext,
-  RegistryProviders,
-  OwnerScopedContributor,
-  ArityVerdict,
-} from './scope-resolution/registries/context.js';
-
-// Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)
-export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
-export type { ScopeIdInput } from './scope-resolution/scope-id.js';
-export {
-  buildScopeTree,
-  canParentScope,
-  ScopeTreeInvariantError,
-} from './scope-resolution/scope-tree.js';
-export type { ScopeTree } from './scope-resolution/scope-tree.js';
-export { buildPositionIndex } from './scope-resolution/position-index.js';
-export type { PositionIndex } from './scope-resolution/position-index.js';
-
-// Resilient fetch primitives — bounded retries + per-process circuit breaker.
-// Test-only helpers (`__resetBreakerRegistry__`, `classifyOutcome`) are
-// reachable via the separate `gitnexus-shared/test-helpers` subpath; do
-// NOT add them here. Production consumers must not call them.
-export { withRetry, computeBackoffMs } from './integrations/retry.js';
-export type { RetryOptions, RetryDecision } from './integrations/retry.js';
-export { CircuitBreaker, CircuitOpenError, getBreaker } from './integrations/circuit-breaker.js';
-export type { CircuitBreakerOptions } from './integrations/circuit-breaker.js';
-export {
-  resilientFetch,
-  ResilientFetchExhaustedError,
-  RETRY_AFTER_CAP_MS,
-  parseRetryAfter,
-} from './integrations/resilient-fetch.js';
-export type { ResilientFetchOptions } from './integrations/resilient-fetch.js';
-
-// Understand-Quickly registry integration (opt-in)
-export {
-  UNDERSTAND_QUICKLY_DISPATCH_URL,
-  UNDERSTAND_QUICKLY_EVENT_TYPE,
-  UNDERSTAND_QUICKLY_TOKEN_ENV,
-  buildUqDispatchPayload,
-  isValidOwnerRepo,
-  parseOwnerRepoFromRemote,
-  stripGitSuffix,
-} from './integrations/understand-quickly.js';
-export type { UqDispatchPayload } from './integrations/understand-quickly.js';
-
-// Shadow-mode diff + aggregation (RFC §6.3; Ring 2 SHARED #918)
-export { diffResolutions } from './scope-resolution/shadow/diff.js';
-export type {
-  ShadowAgreement,
-  ShadowCallsite,
-  ShadowDiff,
-} from './scope-resolution/shadow/diff.js';
-export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';
-export type { LanguageParityRow, ShadowParityReport } from './scope-resolution/shadow/aggregate.js';

gitnexus-shared/src/integrations/circuit-breaker.ts

@@ -1,273 +0,0 @@
-/**
- * Per-process circuit breaker.
- *
- * Closed -> Open transition fires after `failureThreshold` consecutive
- * failures. While Open, `check` throws `CircuitOpenError` until
- * `cooldownMs` has elapsed since the breaker tripped. The first call
- * after the cooldown enters Half-Open and consumes the *probe permit*:
- * a recorded success returns to Closed; a recorded failure flips back
- * to Open with a fresh timestamp.
- *
- * Half-open admits exactly one in-flight probe at a time. Concurrent
- * callers attempting `check()` while a probe is outstanding receive
- * `CircuitOpenError` with `retryAfterMs = halfOpenRetryAfterMs` (default
- * 1000ms; configurable). This prevents the recovery-time thundering
- * herd that defeats the breaker's "fail fast" promise.
- *
- * Outcome reporting splits permit-release from state-resolution:
- *   - `recordSuccess` — releases the probe permit, resets the failure
- *     counter, transitions to Closed. Reserved for true 2xx/3xx outcomes.
- *   - `recordFailure` — releases the probe permit, increments the
- *     consecutive-failure counter, transitions to Open with a fresh
- *     `openedAt` (when called from Half-Open or when the threshold
- *     trips from Closed).
- *   - `recordNeutral` — releases the probe permit, BUT leaves state and
- *     counter untouched. Used for outcomes that are neither evidence of
- *     backend health nor evidence of backend failure (caller-driven
- *     cancellation, local timeout, terminal 4xx client errors). Critical
- *     design point: if `recordNeutral` did not release the permit, a
- *     single `TimeoutError` from per-attempt `AbortSignal.timeout` would
- *     route through `recordNeutral` and permanently park the breaker in
- *     half-open until process restart. Releasing the permit while leaving
- *     state half-open keeps the "neutral doesn't claim health" semantic
- *     without creating that wedge.
- *
- * Pairing invariant: every successful `check()` MUST be paired with
- * exactly one `record*()` on every code path including throws. Direct
- * consumers should wrap the protected operation in `try/finally`:
- *
- *   breaker.check();
- *   try {
- *     const result = await operation();
- *     breaker.recordSuccess();
- *     return result;
- *   } catch (err) {
- *     // classify err and call recordFailure / recordNeutral / etc.
- *     throw err;
- *   }
- *
- * `resilientFetch`'s catch-all on `fetchImpl` already satisfies this
- * for that consumer.
- *
- * Atomicity model: the half-open gate relies on JavaScript event-loop
- * single-threadedness within a synchronous `check()` body. There is no
- * `await` inside `check()`; concurrent callers serialize on microtask
- * order, and exactly one observes `probeInFlight === false`. Do not
- * introduce `await` inside `check()` without revisiting the gate. If
- * this code is ever ported to a runtime with shared-memory threads
- * (Node `worker_threads` with `SharedArrayBuffer`, Web Workers with
- * shared registries), the boolean must become an atomic CAS — Resilience4j
- * and Hystrix use atomic permits *because* they run in JVM thread pools.
- *
- * Runtime-agnostic: depends only on a `now()` clock and standard JS —
- * no Node-only imports. Tests inject `now` to advance the clock
- * deterministically without `vi.useFakeTimers()`.
- */
-
-export class CircuitOpenError extends Error {
-  override readonly name = 'CircuitOpenError';
-  /** Approximate wait time before the breaker may transition to Half-Open
-   *  (or before the in-flight probe is expected to resolve). */
-  readonly retryAfterMs: number;
-
-  constructor(retryAfterMs: number, key?: string) {
-    super(
-      key
-        ? `Circuit '${key}' is open; retry in ${Math.ceil(retryAfterMs / 1000)}s`
-        : `Circuit is open; retry in ${Math.ceil(retryAfterMs / 1000)}s`,
-    );
-    this.retryAfterMs = retryAfterMs;
-  }
-}
-
-export interface CircuitBreakerOptions {
-  /** Consecutive failures required to trip Closed -> Open. */
-  failureThreshold?: number;
-  /** Milliseconds Open before the next call may probe (Half-Open). */
-  cooldownMs?: number;
-  /**
-   * Milliseconds to suggest in `CircuitOpenError.retryAfterMs` when the
-   * breaker is Half-Open with the probe permit consumed. Default 1000ms.
-   * Consumers with long-running protected ops (LLM streaming, large
-   * uploads) should raise this — the cooldown clock is no longer the
-   * right answer because cooldown has elapsed. Returning 0 invites
-   * retry storms; returning the full cooldown misleads about wait.
-   */
-  halfOpenRetryAfterMs?: number;
-  /** Optional key for error messages and registry lookups. */
-  key?: string;
-  /** Clock override — defaults to `Date.now`. Tests inject deterministic time. */
-  now?: () => number;
-}
-
-type State = 'closed' | 'open' | 'half-open';
-
-export class CircuitBreaker {
-  private readonly failureThreshold: number;
-  private readonly cooldownMs: number;
-  private readonly halfOpenRetryAfterMs: number;
-  private readonly key: string | undefined;
-  private readonly now: () => number;
-
-  private state: State = 'closed';
-  private consecutiveFailures = 0;
-  private openedAt: number | null = null;
-  /**
-   * True between a successful `check()` and the next `record*()` call
-   * during Half-Open. Gates concurrent callers from stampeding a still-
-   * recovering dependency. Boolean rather than counter — single-permit
-   * is the conservative end of the Hystrix/Resilience4j spectrum.
-   */
-  private probeInFlight = false;
-
-  constructor(opts: CircuitBreakerOptions = {}) {
-    this.failureThreshold = opts.failureThreshold ?? 3;
-    this.cooldownMs = opts.cooldownMs ?? 30_000;
-    this.halfOpenRetryAfterMs = opts.halfOpenRetryAfterMs ?? 1_000;
-    this.key = opts.key;
-    this.now = opts.now ?? (() => Date.now());
-  }
-
-  /**
-   * Throw `CircuitOpenError` if the breaker won't admit this call.
-   * Otherwise consume the half-open probe permit (if applicable) and
-   * return so the caller can attempt the protected work.
-   *
-   * Three rejection paths:
-   *   1. Open and still in cooldown → throws with `retryAfterMs` =
-   *      remaining cooldown.
-   *   2. Open with cooldown elapsed AND a probe is already in flight
-   *      (race: another caller transitioned to half-open and grabbed
-   *      the permit on a microtask before us) → throws with
-   *      `halfOpenRetryAfterMs`.
-   *   3. Half-Open with probe in flight → throws with `halfOpenRetryAfterMs`.
-   *
-   * **Pairing invariant**: every successful return from `check()` MUST
-   * be paired with exactly one `recordSuccess` / `recordFailure` /
-   * `recordNeutral` on every code path including thrown exceptions.
-   * Failing to pair leaves the probe permit consumed forever and
-   * wedges the breaker. See file-header JSDoc for the canonical
-   * try/finally pattern.
-   */
-  check(): void {
-    if (this.state === 'open' && this.openedAt !== null) {
-      const elapsed = this.now() - this.openedAt;
-      if (elapsed < this.cooldownMs) {
-        throw new CircuitOpenError(this.cooldownMs - elapsed, this.key);
-      }
-      // Cooldown elapsed — transition to Half-Open. The very next
-      // `probeInFlight` check below decides whether THIS caller gets
-      // the permit or hits the gate.
-      this.state = 'half-open';
-    }
-
-    if (this.state === 'half-open') {
-      if (this.probeInFlight) {
-        throw new CircuitOpenError(this.halfOpenRetryAfterMs, this.key);
-      }
-      this.probeInFlight = true;
-    }
-    // Closed state falls through silently.
-  }
-
-  recordSuccess(): void {
-    this.probeInFlight = false;
-    this.consecutiveFailures = 0;
-    this.state = 'closed';
-    this.openedAt = null;
-  }
-
-  recordFailure(): void {
-    this.probeInFlight = false;
-    this.consecutiveFailures += 1;
-    if (this.state === 'half-open' || this.consecutiveFailures >= this.failureThreshold) {
-      this.state = 'open';
-      this.openedAt = this.now();
-    }
-  }
-
-  /**
-   * Releases the probe permit BUT leaves state and counter untouched.
-   * Use when an attempt produced a response or error that should not
-   * influence breaker health in either direction — caller-driven aborts,
-   * local AbortSignal timeouts, terminal 4xx client errors.
-   *
-   * Why permit-release-without-state-resolution: if `recordNeutral` did
-   * not clear `probeInFlight`, a single `TimeoutError` from per-attempt
-   * `AbortSignal.timeout` (which routes through neutral classification)
-   * would permanently park the breaker in half-open. Since timeouts are
-   * an *expected* outcome under flaky-dependency conditions, the cited
-   * "per-attempt timeout bounds the stuck state" mitigation would itself
-   * be the trigger for a permanent wedge. Releasing the permit closes
-   * that loop while keeping the "neutral doesn't claim dependency
-   * health" semantic.
-   *
-   * Calling `recordSuccess` for these would erase legitimate prior
-   * failure signal; calling `recordFailure` would trip the breaker for
-   * outcomes the backend isn't responsible for.
-   */
-  recordNeutral(): void {
-    this.probeInFlight = false;
-    // State and consecutiveFailures are preserved by design.
-  }
-
-  /**
-   * Pure read — no state mutation, no permit accounting. Returns the
-   * *would-be* state at the current instant: 'half-open' if the breaker
-   * is open with cooldown elapsed (regardless of whether a probe is in
-   * flight), 'open' if open and still in cooldown, 'closed' otherwise.
-   *
-   * Inspection-only; safe to call from tests without consuming a probe
-   * permit. The implicit Open -> Half-Open transition that mutates
-   * `state` lives in `check()` only.
-   */
-  getState(): State {
-    if (this.state === 'open' && this.openedAt !== null) {
-      const elapsed = this.now() - this.openedAt;
-      if (elapsed >= this.cooldownMs) return 'half-open';
-    }
-    return this.state;
-  }
-  getConsecutiveFailures(): number {
-    return this.consecutiveFailures;
-  }
-  /** Inspection-only test accessor for the half-open probe permit. */
-  isProbeInFlight(): boolean {
-    return this.probeInFlight;
-  }
-  /** Timestamp (ms since epoch) when the breaker last transitioned to Open,
-   *  or `null` if it's currently Closed. Useful for computing remaining
-   *  cooldown without consuming a probe permit via `check()`. */
-  getOpenedAt(): number | null {
-    return this.openedAt;
-  }
-  /** Configured cooldown duration in milliseconds. */
-  getCooldownMs(): number {
-    return this.cooldownMs;
-  }
-}
-
-// ─── Per-process registry ────────────────────────────────────────────
-//
-// Single shared map keyed on caller-chosen strings. Used by
-// `resilient-fetch.ts` so multiple call sites targeting the same logical
-// endpoint share breaker state. Per-process only — not persisted.
-
-const registry = new Map<string, CircuitBreaker>();
-
-export function getBreaker(key: string, opts?: CircuitBreakerOptions): CircuitBreaker {
-  let breaker = registry.get(key);
-  if (!breaker) {
-    breaker = new CircuitBreaker({ ...opts, key });
-    registry.set(key, breaker);
-  }
-  return breaker;
-}
-
-/**
- * Test-only: clear all registered breakers. Tests must call this in
- * `beforeEach` to prevent breaker state from leaking across test cases.
- */
-export function __resetBreakerRegistry__(): void {
-  registry.clear();
-}

gitnexus-shared/src/integrations/resilient-fetch.ts

@@ -1,279 +0,0 @@
-/**
- * `resilientFetch` — fetch wrapped in retry + circuit breaker, with
- * GitHub-flavoured retry classification baked in (Retry-After parsing,
- * 401/403/404/422 treated as terminal client errors).
- *
- * Designed for the `gitnexus publish` GitHub `repository_dispatch`
- * call, but the classification rules apply to any GitHub REST endpoint.
- * Runtime-agnostic — no Node-only imports.
- */
-
-import {
-  CircuitBreaker,
-  CircuitOpenError,
-  getBreaker,
-  type CircuitBreakerOptions,
-} from './circuit-breaker.js';
-import { computeBackoffMs, type RetryOptions } from './retry.js';
-
-export { CircuitOpenError };
-
-export interface ResilientFetchOptions {
-  /** Optional fetch implementation override. Defaults to `globalThis.fetch`. */
-  fetchImpl?: typeof fetch;
-  /**
-   * Logical key for the breaker. Defaults to `<host><pathname>` of the
-   * request URL — call sites targeting the same endpoint share breaker
-   * state regardless of query-string differences.
-   */
-  breakerKey?: string;
-  /** Per-call breaker override. Used for tests and one-off configuration. */
-  breaker?: CircuitBreaker;
-  /** Tuning knobs for the breaker registered under `breakerKey`. */
-  breakerOptions?: CircuitBreakerOptions;
-  /** Tuning knobs for the retry helper. */
-  retry?: Partial<Pick<RetryOptions, 'maxAttempts' | 'baseDelayMs' | 'capDelayMs'>> & {
-    sleep?: RetryOptions['sleep'];
-    random?: RetryOptions['random'];
-  };
-  /** Clock override propagated into Retry-After HTTP-date math and breaker. */
-  now?: () => number;
-}
-
-/** Cap on any single Retry-After wait — protects CLI from a buggy registry. */
-export const RETRY_AFTER_CAP_MS = 30_000;
-
-const DEFAULT_RETRY = {
-  maxAttempts: 3,
-  baseDelayMs: 500,
-  capDelayMs: 5_000,
-};
-
-/**
- * Parse a `Retry-After` header value into milliseconds.
- * Accepts either a delta-seconds integer (`"30"`) or an HTTP-date.
- * Returns null on parse failure or negative deltas.
- */
-export function parseRetryAfter(value: string | null, now: () => number = Date.now): number | null {
-  if (!value) return null;
-  const trimmed = value.trim();
-  if (trimmed === '') return null;
-
-  if (/^[0-9]+$/.test(trimmed)) {
-    const seconds = parseInt(trimmed, 10);
-    if (Number.isNaN(seconds) || seconds < 0) return null;
-    return seconds * 1000;
-  }
-
-  const target = Date.parse(trimmed);
-  if (Number.isNaN(target)) return null;
-  const delta = target - now();
-  return delta >= 0 ? delta : 0;
-}
-
-/** Internal: outcome classification used by the resilientFetch loop. */
-type Outcome =
-  | { kind: 'success'; resp: Response }
-  | { kind: 'terminal-client'; resp: Response } // 4xx other than 429: no retry, breaker neutral
-  | { kind: 'retryable-status'; resp: Response; afterMs: number | undefined } // 5xx, 429
-  | { kind: 'terminal-network'; err: unknown } // TimeoutError or AbortError: no retry, breaker neutral
-  | { kind: 'retryable-network'; err: unknown }; // DNS, ECONNRESET, etc.
-
-/** Exported for unit tests. */
-export function classifyOutcome(
-  result: { kind: 'error'; err: unknown } | { kind: 'response'; resp: Response },
-  now: () => number,
-): Outcome {
-  if (result.kind === 'error') {
-    // Both timer-fired aborts (`AbortSignal.timeout()` → `TimeoutError`)
-    // and caller-driven aborts (`AbortController.abort()` → `AbortError`)
-    // are terminal: retrying against an already-aborted signal would
-    // fail again immediately, and neither outcome reflects backend
-    // health. They route through the breaker's neutral path.
-    if (
-      result.err instanceof DOMException &&
-      (result.err.name === 'TimeoutError' || result.err.name === 'AbortError')
-    ) {
-      return { kind: 'terminal-network', err: result.err };
-    }
-    return { kind: 'retryable-network', err: result.err };
-  }
-  const resp = result.resp;
-  if (resp.status >= 200 && resp.status < 400) return { kind: 'success', resp };
-  if (resp.status === 429) {
-    // `resp.headers` is always present on a real `Response`, but tests
-    // sometimes stub `fetch` with a plain `{ ok, status }` object. Be
-    // defensive — a missing `Retry-After` falls through to exponential
-    // backoff, which is the correct behaviour anyway.
-    const retryAfterHeader =
-      typeof resp.headers?.get === 'function' ? resp.headers.get('Retry-After') : null;
-    const parsed = parseRetryAfter(retryAfterHeader, now);
-    return {
-      kind: 'retryable-status',
-      resp,
-      afterMs: parsed !== null ? Math.min(parsed, RETRY_AFTER_CAP_MS) : undefined,
-    };
-  }
-  if (resp.status >= 500) return { kind: 'retryable-status', resp, afterMs: undefined };
-  return { kind: 'terminal-client', resp };
-}
-
-const defaultSleep = (ms: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(resolve, ms));
-
-function defaultBreakerKey(input: string | URL): string {
-  try {
-    const url = typeof input === 'string' ? new URL(input) : input;
-    return `${url.host}${url.pathname}`;
-  } catch {
-    return String(input);
-  }
-}
-
-/** Final error thrown when retries are exhausted on a 5xx / 429. */
-export class ResilientFetchExhaustedError extends Error {
-  override readonly name = 'ResilientFetchExhaustedError';
-  constructor(public readonly response: Response) {
-    super(`Request failed after retries (HTTP ${response.status})`);
-  }
-}
-
-/**
- * Wrap `fetch` with bounded retries and a per-process circuit breaker.
- *
- * Semantics:
- * - 5xx and 429 responses are retried; 429 honors `Retry-After` (capped).
- * - Network throws are retried unless they are `TimeoutError` DOMExceptions.
- * - Timeouts and 4xx (other than 429) are returned/thrown without retry
- *   AND without incrementing the breaker — they reflect caller config
- *   or local network state, not registry health.
- * - Each `fetch` call carries the caller-supplied `signal` (e.g. an
- *   `AbortSignal.timeout()`) — that timeout bounds each individual
- *   attempt, not the whole retry sequence.
- * - When the breaker is open, throws `CircuitOpenError` synchronously
- *   without invoking `fetch`.
- * - When retries are exhausted on a 5xx / 429, throws
- *   `ResilientFetchExhaustedError` carrying the last response.
- *
- * Cumulative wall-clock budget:
- *   maxAttempts × (per-attempt-timeout + capDelayMs)
- *   With defaults (3, 500ms base, 5000ms cap) and a typical 15s per-attempt
- *   timeout from the caller's signal, worst case is ~3 × (15s + 5s) = 60s.
- *   Callers that want a tighter total bound should reduce `maxAttempts` or
- *   wrap `resilientFetch` in their own outer `AbortSignal.timeout()`.
- */
-export async function resilientFetch(
-  input: string | URL,
-  init: RequestInit | undefined,
-  opts: ResilientFetchOptions = {},
-): Promise<Response> {
-  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
-  const now = opts.now ?? (() => Date.now());
-  const breaker =
-    opts.breaker ?? getBreaker(opts.breakerKey ?? defaultBreakerKey(input), opts.breakerOptions);
-
-  const retryConfig = {
-    maxAttempts: opts.retry?.maxAttempts ?? DEFAULT_RETRY.maxAttempts,
-    baseDelayMs: opts.retry?.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
-    capDelayMs: opts.retry?.capDelayMs ?? DEFAULT_RETRY.capDelayMs,
-  };
-  const sleep = opts.retry?.sleep ?? defaultSleep;
-  const random = opts.retry?.random ?? Math.random;
-
-  // Fail fast on an open breaker, before invoking fetch.
-  breaker.check();
-
-  for (let attempt = 0; attempt < retryConfig.maxAttempts; attempt++) {
-    let result: { kind: 'error'; err: unknown } | { kind: 'response'; resp: Response };
-    try {
-      // CodeQL js/server-side-request-forgery — flagged because `input`
-      // is caller-supplied. Suppressed: every concrete caller passes
-      // either a hardcoded URL constant (UNDERSTAND_QUICKLY_DISPATCH_URL,
-      // OpenRouter base URL) or a value derived from configuration
-      // (env vars, saved settings, the local backend URL). User-input
-      // request fields (e.g. PR title, repo name) never flow into
-      // `input`. Validating URL shape here would push false-positive
-      // rejection onto every caller — wrong layer for the check.
-      // lgtm[js/server-side-request-forgery]
-      // codeql[js/server-side-request-forgery]
-      const resp = await fetchImpl(input, init);
-      result = { kind: 'response', resp };
-    } catch (err) {
-      result = { kind: 'error', err };
-    }
-
-    const outcome = classifyOutcome(result, now);
-
-    switch (outcome.kind) {
-      case 'success':
-        breaker.recordSuccess();
-        return outcome.resp;
-
-      case 'terminal-client':
-        // 4xx: do not count as breaker failure (the server is healthy
-        // and rejecting our request — auth, scope, or routing). But
-        // also do NOT call recordSuccess: a 401 sandwiched between
-        // 5xx responses would otherwise erase the running outage
-        // signal. The breaker's neutral path leaves state untouched.
-        breaker.recordNeutral();
-        return outcome.resp;
-
-      case 'terminal-network':
-        // Either `AbortSignal.timeout()` fired locally OR an external
-        // caller cancelled the request via AbortController. The server
-        // never had a chance to answer; this reflects the user's
-        // network or an explicit cancel, not registry health. Don't
-        // punish the breaker AND don't reset its outage signal.
-        breaker.recordNeutral();
-        throw outcome.err;
-
-      case 'retryable-status':
-        if (attempt + 1 >= retryConfig.maxAttempts) {
-          breaker.recordFailure();
-          throw new ResilientFetchExhaustedError(outcome.resp);
-        }
-        await sleep(
-          computeBackoffMs(
-            attempt,
-            retryConfig.baseDelayMs,
-            retryConfig.capDelayMs,
-            outcome.afterMs,
-            random,
-          ),
-        );
-        break;
-
-      case 'retryable-network':
-        if (attempt + 1 >= retryConfig.maxAttempts) {
-          breaker.recordFailure();
-          throw outcome.err;
-        }
-        await sleep(
-          computeBackoffMs(
-            attempt,
-            retryConfig.baseDelayMs,
-            retryConfig.capDelayMs,
-            undefined,
-            random,
-          ),
-        );
-        break;
-
-      default: {
-        // Exhaustiveness guard. If a sixth `Outcome` kind is added in
-        // future, TypeScript will refuse to assign it to `never` and
-        // this line forces the maintainer to add an explicit arm
-        // rather than silently fall through to retry/no-retry behaviour.
-        const _exhaustive: never = outcome;
-        throw new Error(`resilientFetch: unhandled outcome ${JSON.stringify(_exhaustive)}`);
-      }
-    }
-  }
-
-  // Unreachable: every iteration of the loop either returns (success
-  // / terminal-client) or throws (terminal-network / retry exhaustion).
-  // The throw is here purely so TypeScript's control-flow analysis sees
-  // the function never falls off the end without producing `Promise<Response>`.
-  /* c8 ignore next 2 */
-  throw new Error('resilientFetch: retry loop terminated unexpectedly');
-}

gitnexus-shared/src/integrations/retry.ts

@@ -1,105 +0,0 @@
-/**
- * Bounded retry helper with full-jitter exponential backoff.
- *
- * Runtime-agnostic: depends only on `setTimeout`, `Math.random`, and the
- * Promise machinery — no Node-only imports. Safe to consume from CLI,
- * server, or browser callers.
- *
- * Pattern reference: gitnexus/src/core/embeddings/http-client.ts. This
- * helper is the upgraded form: classification is caller-supplied (so
- * 4xx-vs-5xx-vs-timeout decisions live with the protocol that knows
- * them), backoff is exponential with full jitter, and an optional
- * `afterMs` lets callers honor `Retry-After` headers.
- */
-
-export interface RetryOptions {
-  /** Initial delay before the first retry attempt, in milliseconds. */
-  baseDelayMs: number;
-  /** Upper bound on any single delay, in milliseconds. */
-  capDelayMs: number;
-  /** Total attempts including the first call. Must be >= 1. */
-  maxAttempts: number;
-  /**
-   * Decide whether to retry after a thrown error.
-   * Return `{retry:false}` to terminate immediately and rethrow.
-   * Return `{retry:true}` to retry with exponential-backoff jitter.
-   * Return `{retry:true, afterMs}` to wait at least `afterMs` (still
-   * subject to `capDelayMs`) — used by callers parsing `Retry-After`.
-   */
-  isRetryable: (err: unknown, attempt: number) => RetryDecision;
-  /** Sleep override — defaults to `setTimeout`. Tests inject fake timers. */
-  sleep?: (ms: number) => Promise<void>;
-  /** Random override — defaults to `Math.random`. Tests inject seeded values. */
-  random?: () => number;
-}
-
-export type RetryDecision = { retry: false } | { retry: true; afterMs?: number };
-
-const defaultSleep = (ms: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(resolve, ms));
-
-/**
- * Compute the delay before the next retry attempt.
- *
- * - When the caller specifies `afterMs` (e.g., from `Retry-After`), use
- *   `min(afterMs, capDelayMs)` so a misbehaving server can't pin the
- *   client for an arbitrarily long wait.
- * - Otherwise compute full-jitter exponential backoff:
- *   `random() * min(cap, base * 2^attempt)`. Full jitter (rather than
- *   "equal jitter") avoids retry-storm thundering herd, per AWS
- *   guidance on backoff strategies.
- */
-export function computeBackoffMs(
-  attempt: number,
-  baseDelayMs: number,
-  capDelayMs: number,
-  afterMs: number | undefined,
-  random: () => number,
-): number {
-  if (afterMs !== undefined) {
-    return Math.min(Math.max(0, afterMs), capDelayMs);
-  }
-  const exponential = baseDelayMs * Math.pow(2, attempt);
-  const upper = Math.min(capDelayMs, exponential);
-  return Math.floor(random() * upper);
-}
-
-/**
- * Execute `fn` with bounded retries.
- *
- * The classification of "retryable" is the caller's responsibility — see
- * `resilient-fetch.ts` for the GitHub-dispatch-specific rules. This
- * helper is the mechanical retry loop only.
- */
-export async function withRetry<T>(
-  fn: (attempt: number) => Promise<T>,
-  opts: RetryOptions,
-): Promise<T> {
-  if (opts.maxAttempts < 1) {
-    throw new Error(`withRetry: maxAttempts must be >= 1, got ${opts.maxAttempts}`);
-  }
-  const sleep = opts.sleep ?? defaultSleep;
-  const random = opts.random ?? Math.random;
-
-  let lastError: unknown;
-  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
-    try {
-      return await fn(attempt);
-    } catch (err) {
-      lastError = err;
-      const decision = opts.isRetryable(err, attempt);
-      if (!decision.retry) throw err;
-      // Don't sleep after the final attempt.
-      if (attempt + 1 >= opts.maxAttempts) break;
-      const delayMs = computeBackoffMs(
-        attempt,
-        opts.baseDelayMs,
-        opts.capDelayMs,
-        decision.afterMs,
-        random,
-      );
-      if (delayMs > 0) await sleep(delayMs);
-    }
-  }
-  throw lastError;
-}

gitnexus-shared/src/integrations/understand-quickly.ts

@@ -1,151 +0,0 @@
-/**
- * Understand-Quickly registry integration helpers.
- *
- * Pure, runtime-agnostic logic for opting in to publishing a GitNexus
- * index to the [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly)
- * registry. Lives in `gitnexus-shared` so both the Node CLI and any
- * future browser-side surface can construct identical dispatch payloads.
- *
- * Network I/O lives in the CLI command (`gitnexus/src/cli/publish.ts`)
- * to keep this module free of Node-only imports — see the comment at
- * the top of `gitnexus-shared/src/graph/types.ts`.
- *
- * The protocol contract (single dispatch event, no graph upload) is
- * documented at:
- *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
- */
-
-/**
- * URL of the registry repo's repository_dispatch endpoint. Hardcoded
- * because the registry is the canonical home for this integration —
- * users who want a private registry can fork and patch.
- */
-export const UNDERSTAND_QUICKLY_DISPATCH_URL =
-  'https://api.github.com/repos/looptech-ai/understand-quickly/dispatches';
-
-/**
- * Event type the registry's sync workflow listens for.
- * See `looptech-ai/understand-quickly/.github/workflows/sync.yml`.
- */
-export const UNDERSTAND_QUICKLY_EVENT_TYPE = 'sync-entry';
-
-/** Environment variable that gates the dispatch. */
-export const UNDERSTAND_QUICKLY_TOKEN_ENV = 'UNDERSTAND_QUICKLY_TOKEN';
-
-export interface UqDispatchPayload {
-  event_type: typeof UNDERSTAND_QUICKLY_EVENT_TYPE;
-  client_payload: {
-    /** `<owner>/<repo>` shape — must match the registered entry. */
-    id: string;
-  };
-}
-
-/**
- * Build the JSON body for the `repository_dispatch` ping. Pure — no
- * env reads, no network. Validates that `id` looks like `owner/repo`
- * (one slash, no whitespace, both halves non-empty) so a misconfigured
- * caller fails loudly before the round-trip.
- */
-export function buildUqDispatchPayload(id: string): UqDispatchPayload {
-  if (!isValidOwnerRepo(id)) {
-    throw new Error(
-      `[understand-quickly] expected id of the form "owner/repo", got "${id}". ` +
-        `The registry uses this string to look up your entry in registry.json — ` +
-        `it must match the GitHub owner/repo of the source code, not a local path.`,
-    );
-  }
-  return {
-    event_type: UNDERSTAND_QUICKLY_EVENT_TYPE,
-    client_payload: { id },
-  };
-}
-
-/**
- * `owner/repo` validation. Conservative on purpose: GitHub's actual
- * naming rules are looser, but we want to catch local paths
- * (`/Users/...`), bare slugs (`my-repo`), and accidental whitespace.
- *
- * Matches GitHub's published slug rules:
- *   owner: starts with alnum, then alnum/hyphen only, must end with
- *          alnum (no trailing hyphen — GitHub rejects this at account
- *          creation, so a `my-org-/repo` input would otherwise pass us
- *          and 422 from GitHub). No underscore, no dot. Length cap 39.
- *   repo:  any of alnum/dot/hyphen/underscore. Length cap 100.
- */
-export function isValidOwnerRepo(id: string): boolean {
-  return /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\/[A-Za-z0-9._-]{1,100}$/.test(id);
-}
-
-/**
- * Strip a single trailing `.git` (case-insensitive) and any trailing
- * slashes from a URL-ish string. Bounded linear: each character is
- * visited at most twice, no backtracking.
- *
- * Replaces `s.replace(/\.git\/*$/i, '').replace(/\/+$/, '')` which
- * CodeQL's polynomial-regex check (codeql/js/polynomial-redos) flags as
- * a worst-case O(n²) on adversarial input like "////.../x".
- */
-export function stripGitSuffix(input: string): string {
-  let end = input.length;
-  // Trim trailing '/'.
-  while (end > 0 && input.charCodeAt(end - 1) === 0x2f) end--;
-  // Drop one trailing '.git' (case-insensitive).
-  if (end >= 4) {
-    const tail = input.slice(end - 4, end).toLowerCase();
-    if (tail === '.git') end -= 4;
-  }
-  // Trim trailing '/' that may have sat between '.git' and the rest.
-  while (end > 0 && input.charCodeAt(end - 1) === 0x2f) end--;
-  return input.slice(0, end);
-}
-
-/**
- * Parse `owner/repo` out of a git remote URL. Mirrors the heuristic in
- * `gitnexus/src/storage/git.ts:parseRepoNameFromUrl` but keeps both
- * halves so we can build a registry id. Returns `null` on shapes we
- * don't recognise.
- *
- * Examples:
- *   git@github.com:looptech-ai/understand-quickly.git
- *   https://github.com/looptech-ai/understand-quickly
- *   ssh://git@github.com/looptech-ai/understand-quickly.git
- */
-export function parseOwnerRepoFromRemote(url: string | null | undefined): string | null {
-  if (!url) return null;
-  const trimmed = url.trim();
-  if (!trimmed) return null;
-  // Strip a trailing `.git` (case-insensitive) and any trailing slashes
-  // so https://h/o/r and https://h/o/r.git collapse to the same id.
-  // Bounded-linear helper avoids the polynomial-regex CodeQL alert.
-  const stripped = stripGitSuffix(trimmed);
-
-  // SCP-form SSH (`git@host:owner/repo`). Capture host so we can reject
-  // non-GitHub remotes — a GitLab origin like
-  // `https://gitlab.example.com/group/sub/project.git` would otherwise
-  // silently dispatch the wrong id (LOW 9).
-  const ssh = stripped.match(/^[^@]+@([^:]+):([^/]+)\/([^/]+)$/);
-  if (ssh) {
-    const host = ssh[1].toLowerCase();
-    if (host !== 'github.com' && host !== 'www.github.com') return null;
-    return `${ssh[2]}/${ssh[3]}`;
-  }
-
-  // URL forms (https://, ssh://, git://, file://) — last two path segments.
-  const url2 = stripped.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/([^/]+)\/(.+)$/);
-  if (url2) {
-    // Strip optional `userinfo@` (e.g. `ssh://git@github.com/...`).
-    const authority = url2[1];
-    const atIdx = authority.lastIndexOf('@');
-    const hostAndPort = atIdx >= 0 ? authority.slice(atIdx + 1) : authority;
-    // Strip `:port` suffix if present.
-    const colonIdx = hostAndPort.indexOf(':');
-    const host = (colonIdx >= 0 ? hostAndPort.slice(0, colonIdx) : hostAndPort).toLowerCase();
-    if (host !== 'github.com' && host !== 'www.github.com') return null;
-    const segments = url2[2].split('/').filter(Boolean);
-    if (segments.length >= 2) {
-      const [owner, repo] = segments.slice(-2);
-      return `${owner}/${repo}`;
-    }
-  }
-  return null;
-}

gitnexus-shared/src/lbug/schema-constants.ts

@@ -30,7 +30,6 @@ export const NODE_TABLES = [
   'TypeAlias',
   'Const',
   'Static',
-  'Variable',
   'Property',
   'Record',
   'Delegate',

gitnexus-shared/src/mro-strategy.ts

@@ -1,46 +1,23 @@
 /**
- * MRO (Method Resolution Order) strategy — shared canonical definition.
+ * MRO (Method Resolution Order) strategy — shared between CLI and any
+ * future consumer that reasons about multiple-inheritance semantics.
  *
- * Lives in `gitnexus-shared` so `model/resolve.ts` and `mro-processor.ts` share
- * the type without importing the language registry (avoids circular coupling).
+ * Lives in `gitnexus-shared` so the low-level resolution module
+ * (`core/ingestion/model/resolve.ts`) does not need to import from
+ * `languages/` — keeping the `model/` layer free of language-registry
+ * coupling.
  *
- * `first-wins` (default, Java/C#/Kotlin/Go/Swift/Dart):
- *   BFS ancestor walk in declaration order; first match wins.
- *
- * `leftmost-base` (C++):
- *   BFS walk; HeritageMap preserves source insertion order, so BFS naturally
- *   picks the leftmost base in diamond inheritance.
- *
- * `c3` (Python):
- *   C3-linearization; falls back to BFS on cyclic/inconsistent hierarchy.
- *   See model/resolve.ts § c3Linearize.
- *
- * `implements-split` (Java/C#/Kotlin):
- *   Low-level lookup is BFS; graph-level mro-processor detects and warns on
- *   interface-default method ambiguity.
- *
- * `qualified-syntax` (Rust):
- *   No auto-resolution — `lookupMethodByOwnerWithMRO` returns undefined immediately.
- *   Rust requires explicit `<Type as Trait>::method` syntax.
- *
- * `ruby-mixin` (Ruby):
- *   Kind-aware walk that does NOT short-circuit on direct owner first (`prepend`
- *   must beat the class's own method). Walk order:
- *     1. Prepend providers (reverse declaration — last-prepended wins)
- *     2. Direct owner's own methods
- *     3. Include providers (reverse declaration)
- *     4. Transitive ancestors (BFS fallback)
- *   Singleton dispatch: caller passes `ancestryOverride` (extend providers only);
- *   becomes a simple left-to-right scan. Miss NEVER falls through to file-scoped
- *   lookup — null-routes or honors `fallback`.
- *
- * @see model/resolve.ts § lookupMethodByOwnerWithMRO
- * @see languages/ruby.ts § selectDispatch
+ * Strategy semantics:
+ * - `first-wins`:       BFS ancestor walk, first match wins (default).
+ * - `leftmost-base`:    BFS ancestor walk, leftmost base wins (C++).
+ * - `c3`:               C3-linearized ancestor order, first match wins (Python).
+ * - `implements-split`: BFS walk, first match wins (Java/C#/Kotlin) — full
+ *                       interface-default ambiguity is handled at graph level.
+ * - `qualified-syntax`: No auto-resolution (Rust — requires `<T as Trait>::m`).
  */
 export type MroStrategy =
   | 'first-wins'
   | 'c3'
   | 'leftmost-base'
   | 'implements-split'
-  | 'qualified-syntax'
-  | 'ruby-mixin';
+  | 'qualified-syntax';

gitnexus-shared/src/scope-resolution/def-index.ts

@@ -1,62 +0,0 @@
-/**
- * `DefIndex` — O(1) `DefId → SymbolDefinition` materialization.
- *
- * The global "what is this id?" lookup. Every per-kind registry (ClassRegistry,
- * MethodRegistry, FieldRegistry) returns `DefId[]` and resolves them back to
- * full `SymbolDefinition` records through this index — one central hash map,
- * one allocation per def.
- *
- * Part of RFC #909 Ring 2 SHARED — #913.
- *
- * Consumed by: #917 (`Registry.lookup` implementations), #915 (SCC finalize).
- */
-
-import type { SymbolDefinition } from './symbol-definition.js';
-import type { DefId } from './types.js';
-
-export interface DefIndex {
-  readonly byId: ReadonlyMap<DefId, SymbolDefinition>;
-  readonly size: number;
-  get(id: DefId): SymbolDefinition | undefined;
-  has(id: DefId): boolean;
-}
-
-/**
- * Build a `DefIndex` from a flat list of `SymbolDefinition` records.
- *
- * **Collision policy: first-write-wins.** `DefId` is meant to be unique
- * (`nodeId` is the stable graph identifier), so a collision indicates an
- * upstream bug — most likely the same symbol parsed twice or a duplicate
- * commit into the pipeline. Rather than silently overwriting with a later
- * definition that may be partial or wrong, the first record wins and
- * subsequent records for the same id are dropped. Pipeline bugs surface
- * later as `has(id) === true` but the def looking older than expected,
- * which is easier to debug than a silent overwrite.
- *
- * Pure function — safe to call repeatedly; no side effects.
- */
-export function buildDefIndex(defs: readonly SymbolDefinition[]): DefIndex {
-  const byId = new Map<DefId, SymbolDefinition>();
-  for (const def of defs) {
-    if (byId.has(def.nodeId)) continue; // first-write-wins
-    byId.set(def.nodeId, def);
-  }
-  return wrapIndex(byId);
-}
-
-// ─── Internal ───────────────────────────────────────────────────────────────
-
-function wrapIndex(byId: Map<DefId, SymbolDefinition>): DefIndex {
-  return {
-    byId,
-    get size() {
-      return byId.size;
-    },
-    get(id: DefId): SymbolDefinition | undefined {
-      return byId.get(id);
-    },
-    has(id: DefId): boolean {
-      return byId.has(id);
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/evidence-weights.ts

@@ -1,90 +0,0 @@
-/**
- * `EvidenceWeights` — RFC Appendix A (authoritative values).
- *
- * Starting calibration for scope-based resolution. Shadow-first rollout
- * tunes these against legacy DAG parity. Every `ResolutionEvidence.weight`
- * value in the codebase MUST reference this map; inline magic numbers are a
- * lint violation. Extends issue #429 (centralize hardcoded confidence values).
- *
- * Evidence composes additively inside `composeEvidence`; the sum is capped
- * at 1.0 in `Resolution.confidence`.
- */
-
-/**
- * Authoritative weight map. Keys are a mix of `ResolutionEvidence.kind`
- * values and special modifiers (scope-chain depth, MRO depth decay,
- * unlinked-import multiplicative cap).
- */
-export const EvidenceWeights = {
-  // ─── Where-found signals (visibility) ─────────────────────────────────────
-  /** `BindingRef.origin === 'local'` */
-  local: 0.55,
-  /** `BindingRef.origin === 'import'` */
-  import: 0.45,
-  /** `BindingRef.origin === 'reexport'` */
-  reexport: 0.4,
-  /** `BindingRef.origin === 'namespace'` */
-  namespace: 0.4,
-  /** `BindingRef.origin === 'wildcard'` */
-  wildcard: 0.3,
-
-  // ─── Scope-chain deduction (per-hop) ──────────────────────────────────────
-  /** Deducted per parent-hop taken (depth-0 = 0, depth-1 = −0.02, …). */
-  scopeChainPerDepth: -0.02,
-
-  // ─── Receiver-type-binding signal (decays by MRO depth) ───────────────────
-  /**
-   * Weight applied when the receiver's type binding resolves to a class that
-   * declares the candidate as a method/field. Decays by MRO depth: direct
-   * class = index 0; 1 parent hop = index 1; etc. Falls back to the last
-   * value for depths beyond the table.
-   */
-  typeBindingByMroDepth: [0.5, 0.42, 0.36, 0.32, 0.3] as const,
-
-  // ─── Corroborating signals ────────────────────────────────────────────────
-  /** `def.ownerId === resolvedReceiver.def.id` (exact owner match). */
-  ownerMatch: 0.2,
-  /** Explanatory only — retained for debuggability. Never discriminates
-   *  because surviving candidates already passed `acceptedKinds`. */
-  kindMatch: 0.0,
-
-  // ─── Arity compatibility (from `provider.arityCompatibility`) ─────────────
-  /** `provider.arityCompatibility(...) === 'compatible'` */
-  arityMatchCompatible: 0.1,
-  /** `provider.arityCompatibility(...) === 'unknown'` */
-  arityMatchUnknown: 0.0,
-  /** `provider.arityCompatibility(...) === 'incompatible'` — penalizes;
-   *  candidates filtered only when a compatible candidate exists. */
-  arityMatchIncompatible: -0.15,
-
-  // ─── Global fallback (only when nothing lexically visible) ────────────────
-  /** Hit via `QualifiedNameIndex.byQualifiedName`. */
-  globalQualified: 0.35,
-  /** Fallback hit in a `byName` index (and nothing was lexically visible). */
-  globalName: 0.1,
-
-  // ─── Degraded signals ─────────────────────────────────────────────────────
-  /** Call/reference flowing through a `dynamic-unresolved` edge. */
-  dynamicImportUnresolved: 0.02,
-
-  // ─── Unresolved-import cap (multiplicative, applied per-signal) ───────────
-  /**
-   * Multiplicative cap on the edge-derived evidence signal
-   * (`import`/`wildcard`/`reexport`/`namespace`) when
-   * `ImportEdge.linkStatus === 'unresolved'`. Independent corroborating
-   * signals on the same candidate (`owner-match`, `arity-match`,
-   * `type-binding`) are NOT penalized.
-   */
-  unlinkedImportMultiplier: 0.5,
-} as const;
-
-/**
- * Look up the `type-binding` signal weight for a given MRO depth, falling
- * back to the last tabulated value for depths beyond the table.
- */
-export function typeBindingWeightAtDepth(mroDepth: number): number {
-  const table = EvidenceWeights.typeBindingByMroDepth;
-  if (mroDepth < 0) return table[0];
-  if (mroDepth >= table.length) return table[table.length - 1];
-  return table[mroDepth];
-}

gitnexus-shared/src/scope-resolution/language-classification.ts

@@ -1,49 +0,0 @@
-/**
- * `LanguageClassification` — RFC §6.1 Ring 3 / Ring 4 governance.
- *
- * Classifies each `SupportedLanguages` member for the rollout. Ring 4 (DAG
- * retirement) is gated on *all production languages* being registry-primary
- * and stable for one release cycle; `experimental` and `quarantined`
- * languages do not block.
- *
- * Initial classification (locked in Ring 1 #910):
- *   - production: javascript, typescript, python, java, c, cpp, csharp, go,
- *                 ruby, rust, php, kotlin, swift, dart
- *   - experimental: vue (embedded-language / SFC complexity),
- *                   cobol (regex-provider path)
- *   - quarantined: (none)
- */
-
-import { SupportedLanguages } from '../languages.js';
-
-export type LanguageClassification = 'production' | 'experimental' | 'quarantined';
-
-/**
- * The canonical classification for each supported language. Governance
- * changes (promote `experimental` → `production`, quarantine a language, …)
- * update this map in a dedicated PR.
- */
-export const LanguageClassifications: Readonly<Record<SupportedLanguages, LanguageClassification>> =
-  {
-    [SupportedLanguages.JavaScript]: 'production',
-    [SupportedLanguages.TypeScript]: 'production',
-    [SupportedLanguages.Python]: 'production',
-    [SupportedLanguages.Java]: 'production',
-    [SupportedLanguages.C]: 'production',
-    [SupportedLanguages.CPlusPlus]: 'production',
-    [SupportedLanguages.CSharp]: 'production',
-    [SupportedLanguages.Go]: 'production',
-    [SupportedLanguages.Ruby]: 'production',
-    [SupportedLanguages.Rust]: 'production',
-    [SupportedLanguages.PHP]: 'production',
-    [SupportedLanguages.Kotlin]: 'production',
-    [SupportedLanguages.Swift]: 'production',
-    [SupportedLanguages.Dart]: 'production',
-    [SupportedLanguages.Vue]: 'experimental',
-    [SupportedLanguages.Cobol]: 'experimental',
-  };
-
-/** Convenience predicate: is this language gating Ring 4 retirement? */
-export function isProductionLanguage(lang: SupportedLanguages): boolean {
-  return LanguageClassifications[lang] === 'production';
-}

gitnexus-shared/src/scope-resolution/method-dispatch-index.ts

@@ -1,145 +0,0 @@
-/**
- * `MethodDispatchIndex` — materialized view of class hierarchies keyed by
- * `DefId` (RFC §3.1; Ring 2 SHARED #914).
- *
- * Two O(1)-access maps used by `Registry.lookupMethod` and interface-
- * dispatch callers:
- *
- *   - `mroByOwnerDefId`       : owner class → full MRO ancestor chain
- *                               (excludes the owner itself, in per-language
- *                               strategy order).
- *   - `implsByInterfaceDefId` : interface/trait → classes that implement it.
- *
- * **Not an MRO implementation.** The build function is a pure aggregator: it
- * asks the caller (via `computeMro` and `implementsOf` callbacks) for the
- * per-language answers and materializes the two-way index. MRO strategies
- * live where they already do today (`model/resolve.ts § c3Linearize`,
- * `languages/ruby.ts § selectDispatch`, etc.) — this index does not
- * reimplement them.
- *
- * Why callbacks and not a shared strategy registry: the five strategies
- * (Python C3, Ruby kind-aware, Java/Kotlin linear, Rust qualified-syntax,
- * COBOL none) already exist in the CLI package and depend on the CLI's
- * `HeritageMap` + `SemanticModel`. Pulling them into `gitnexus-shared` would
- * require migrating both — out of scope for #914. Callbacks let the shared
- * build stay pure while honoring existing strategies verbatim.
- *
- * Consumed by: #917 (`Registry.lookupMethod` MRO fast path, interface
- * dispatch resolver).
- */
-
-import type { DefId } from './types.js';
-
-// ─── Public contracts ───────────────────────────────────────────────────────
-
-export interface MethodDispatchIndex {
-  /**
-   * Full MRO ancestor chain per owner class (excludes the owner itself).
-   * Order reflects the per-language strategy used by `computeMro`.
-   */
-  readonly mroByOwnerDefId: ReadonlyMap<DefId, readonly DefId[]>;
-  /** Interfaces / traits → classes that implement them. */
-  readonly implsByInterfaceDefId: ReadonlyMap<DefId, readonly DefId[]>;
-
-  /** `mroByOwnerDefId.get`, with an empty frozen array on miss. */
-  mroFor(ownerDefId: DefId): readonly DefId[];
-  /** `implsByInterfaceDefId.get`, with an empty frozen array on miss. */
-  implementorsOf(interfaceDefId: DefId): readonly DefId[];
-}
-
-export interface MethodDispatchInput {
-  /**
-   * Owner defs to index (classes, structs, traits, interfaces — any kind
-   * that can appear on the owner side of a method-dispatch graph).
-   */
-  readonly owners: readonly DefId[];
-  /**
-   * Return the full MRO ancestor chain for `ownerDefId`, **excluding the
-   * owner itself**, in the order dictated by the owner's language-specific
-   * MRO strategy.
-   *
-   * Contract:
-   *   - Pure (no side effects).
-   *   - Deterministic per input.
-   *   - `undefined` not allowed — return `[]` when the owner has no parents.
-   */
-  readonly computeMro: (ownerDefId: DefId) => readonly DefId[];
-  /**
-   * Return the set of interface/trait defs that `ownerDefId` implements.
-   * Transitive inclusion (e.g., `implements` on a parent class) is the
-   * caller's choice — the build function simply inverts whatever is
-   * returned.
-   *
-   * Repeated IDs in the output are deduplicated automatically.
-   *
-   * **Call-count contract.** `implementsOf` is invoked **once per
-   * occurrence** of an owner in `input.owners`, not once per unique
-   * owner. Duplicate owners therefore re-invoke it; dedup happens at
-   * the bucket layer (after the callback returns). Callers with
-   * expensive `implementsOf` implementations should pass a deduplicated
-   * `owners` list. `computeMro`, by contrast, is memoized by the first-
-   * write-wins policy and fires at most once per unique owner.
-   */
-  readonly implementsOf: (ownerDefId: DefId) => readonly DefId[];
-}
-
-// ─── Builder ────────────────────────────────────────────────────────────────
-
-export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDispatchIndex {
-  const mroByOwnerDefId = new Map<DefId, readonly DefId[]>();
-  const implsBuilding = new Map<DefId, DefId[]>();
-  const implsSeen = new Map<DefId, Set<DefId>>();
-
-  for (const ownerId of input.owners) {
-    // First-write-wins on duplicate owner ids: a stable policy consistent
-    // with sibling indexes (#913 DefIndex / ModuleScopeIndex).
-    if (!mroByOwnerDefId.has(ownerId)) {
-      const chain = input.computeMro(ownerId);
-      mroByOwnerDefId.set(ownerId, Object.freeze(chain.slice()));
-    }
-
-    for (const ifaceId of input.implementsOf(ownerId)) {
-      let seen = implsSeen.get(ifaceId);
-      if (seen === undefined) {
-        seen = new Set<DefId>();
-        implsSeen.set(ifaceId, seen);
-      }
-      if (seen.has(ownerId)) continue;
-      seen.add(ownerId);
-
-      let bucket = implsBuilding.get(ifaceId);
-      if (bucket === undefined) {
-        bucket = [];
-        implsBuilding.set(ifaceId, bucket);
-      }
-      bucket.push(ownerId);
-    }
-  }
-
-  const implsByInterfaceDefId = new Map<DefId, readonly DefId[]>();
-  for (const [ifaceId, owners] of implsBuilding) {
-    implsByInterfaceDefId.set(ifaceId, Object.freeze(owners.slice()));
-  }
-
-  return wrapIndex(mroByOwnerDefId, implsByInterfaceDefId);
-}
-
-// ─── Internal ───────────────────────────────────────────────────────────────
-
-const EMPTY: readonly DefId[] = Object.freeze([]);
-
-function wrapIndex(
-  mroByOwnerDefId: Map<DefId, readonly DefId[]>,
-  implsByInterfaceDefId: Map<DefId, readonly DefId[]>,
-): MethodDispatchIndex {
-  return {
-    mroByOwnerDefId,
-    implsByInterfaceDefId,
-    mroFor(ownerDefId: DefId): readonly DefId[] {
-      return mroByOwnerDefId.get(ownerDefId) ?? EMPTY;
-    },
-    implementorsOf(interfaceDefId: DefId): readonly DefId[] {
-      return implsByInterfaceDefId.get(interfaceDefId) ?? EMPTY;
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/module-scope-index.ts

@@ -1,73 +0,0 @@
-/**
- * `ModuleScopeIndex` — O(1) `filePath → moduleScopeId` lookup.
- *
- * Every file parsed produces exactly one `Module` scope at its root. The
- * finalize algorithm needs to resolve `ImportEdge.targetFile` to a concrete
- * module scope id in constant time during the link pass; this index is that
- * mapping.
- *
- * Part of RFC #909 Ring 2 SHARED — #913.
- *
- * Consumed by: #915 (SCC finalize link pass), #923 (shadow harness when
- * resolving callsite file → enclosing module).
- */
-
-import type { ScopeId } from './types.js';
-
-export interface ModuleScopeIndex {
-  readonly byFilePath: ReadonlyMap<string, ScopeId>;
-  readonly size: number;
-  get(filePath: string): ScopeId | undefined;
-  has(filePath: string): boolean;
-}
-
-export interface ModuleScopeEntry {
-  readonly filePath: string;
-  readonly moduleScopeId: ScopeId;
-}
-
-/**
- * Build a `ModuleScopeIndex` from a flat list of `{ filePath, moduleScopeId }`
- * pairs.
- *
- * **Collision policy: first-write-wins.** A file should appear exactly once
- * in a single ingestion run; collisions indicate the same file was parsed
- * twice or a `filePath` normalization bug upstream. Dropping the later
- * entry preserves the first-stable id the rest of the pipeline may already
- * have registered against.
- *
- * **Caller contract: filePath keys must be pre-normalized.** This index
- * keys on the raw `filePath` string and does NOT canonicalize separators,
- * case, or trailing slashes. Callers upstream of this function must agree
- * on a canonical form (typically repo-root-relative, POSIX separators,
- * no trailing slash) before constructing entries — otherwise `C:\foo\bar.ts`,
- * `C:/foo/bar.ts`, and `foo/bar.ts` will all hash to distinct buckets and
- * `get()` will miss.
- *
- * Pure function — safe to call repeatedly; no side effects.
- */
-export function buildModuleScopeIndex(entries: readonly ModuleScopeEntry[]): ModuleScopeIndex {
-  const byFilePath = new Map<string, ScopeId>();
-  for (const { filePath, moduleScopeId } of entries) {
-    if (byFilePath.has(filePath)) continue; // first-write-wins
-    byFilePath.set(filePath, moduleScopeId);
-  }
-  return wrapIndex(byFilePath);
-}
-
-// ─── Internal ───────────────────────────────────────────────────────────────
-
-function wrapIndex(byFilePath: Map<string, ScopeId>): ModuleScopeIndex {
-  return {
-    byFilePath,
-    get size() {
-      return byFilePath.size;
-    },
-    get(filePath: string): ScopeId | undefined {
-      return byFilePath.get(filePath);
-    },
-    has(filePath: string): boolean {
-      return byFilePath.has(filePath);
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/origin-priority.ts

@@ -1,30 +0,0 @@
-/**
- * `ORIGIN_PRIORITY` — RFC Appendix B (authoritative values).
- *
- * Tie-break ordering applied inside `Registry.lookup` Step 7 when
- * `|Δconfidence| < 0.001` between two `Resolution` candidates. Lower number
- * = stronger (wins the tie).
- *
- * Full tie-break order (§4.2 Step 7):
- *   confidence DESC → scope depth ASC → MRO depth ASC → ORIGIN_PRIORITY ASC
- *   → DefId.localeCompare
- */
-
-export type OriginForTieBreak =
-  | 'local'
-  | 'import'
-  | 'reexport'
-  | 'namespace'
-  | 'wildcard'
-  | 'global-qualified'
-  | 'global-name';
-
-export const ORIGIN_PRIORITY: Readonly<Record<OriginForTieBreak, number>> = {
-  local: 0,
-  import: 1,
-  reexport: 2,
-  namespace: 3,
-  wildcard: 4,
-  'global-qualified': 5,
-  'global-name': 6,
-};

gitnexus-shared/src/scope-resolution/parsed-file.ts

@@ -1,77 +0,0 @@
-/**
- * `ParsedFile` — the per-file artifact produced by `ScopeExtractor`
- * (RFC §3.2 Phase 1; Ring 2 PKG #919).
- *
- * The boundary between Phase 1 (extraction, per-file, parallelizable) and
- * Phase 2 (finalize, cross-file). One `ParsedFile` is emitted per source
- * file; the finalize orchestrator (#921) collects them into a workspace-
- * wide set and feeds them to the shared `finalize` algorithm (#915).
- *
- * ## Shape
- *
- *   - `scopes`           — every `Scope` created for this file, in tree-
- *                          topological order (module first, then children).
- *                          `Scope.bindings` carry **local-only** bindings at
- *                          this stage; finalize merges imports/wildcards on top.
- *   - `parsedImports`    — raw `ParsedImport[]` for this file; finalize
- *                          resolves each to a concrete `ImportEdge`.
- *   - `localDefs`        — defs structurally declared in this file. A
- *                          superset of every `Scope.ownedDefs` union.
- *                          Listed separately so `finalize` can dedup-index
- *                          without re-walking scopes.
- *   - `referenceSites`   — pre-resolution usage facts; populated by the
- *                          resolution phase into `ReferenceIndex`.
- *
- * ## What `ParsedFile` deliberately does NOT carry
- *
- *   - Linked `ImportEdge`s. Those are finalize output.
- *   - A `ScopeTree` instance. Callers build one from `scopes` (cheap —
- *     `buildScopeTree(parsedFile.scopes)`). Keeping the ParsedFile flat
- *     makes IPC serialization from worker threads straightforward.
- *   - Merged module-scope bindings. Finalize owns that materialization.
- *
- * ## Compatibility with `FinalizeFile`
- *
- * `FinalizeFile` (defined in `./finalize-algorithm.ts`) is a structural
- * subset of `ParsedFile` — `filePath`, `moduleScope`, `parsedImports`,
- * `localDefs`. A `ParsedFile` is trivially convertible to a `FinalizeFile`
- * by picking those four fields, so the finalize orchestrator threads
- * ParsedFile through to the shared algorithm without shape-shifting.
- *
- * ## Source-of-truth invariant
- *
- * `ParsedFile` is the single semantic model consumed by both the legacy
- * DAG (`gitnexus/src/core/ingestion/` outside `scope-resolution/`) and
- * the scope-resolution pipeline (`gitnexus/src/core/ingestion/scope-resolution/`).
- * Downstream passes MUST NOT build a parallel parse representation; if
- * a pass needs AST-level facts that `ParsedFile` doesn't expose, it
- * should reuse the orchestrator's `treeCache` rather than re-invoke
- * `parser.parse(...)` on its own. See the
- * `ScopeResolver` contract (`gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts`)
- * for the full list of invariants downstream consumers rely on.
- */
-
-import type { Scope, ScopeId } from './types.js';
-import type { ParsedImport } from './types.js';
-import type { SymbolDefinition } from './symbol-definition.js';
-import type { ReferenceSite } from './reference-site.js';
-
-export interface ParsedFile {
-  readonly filePath: string;
-  /** `Scope.id` of the file's root `Module` scope. */
-  readonly moduleScope: ScopeId;
-  /**
-   * All scopes in this file, typically emitted in tree-topological order.
-   * Caller reconstructs a `ScopeTree` via `buildScopeTree(scopes)` when
-   * navigation or invariant re-validation is needed.
-   */
-  readonly scopes: readonly Scope[];
-  readonly parsedImports: readonly ParsedImport[];
-  /**
-   * All defs structurally declared in this file (classes, methods, fields,
-   * variables). Mirrors the union of `Scope.ownedDefs` across `scopes`,
-   * pre-flattened for O(N) consumption by finalize.
-   */
-  readonly localDefs: readonly SymbolDefinition[];
-  readonly referenceSites: readonly ReferenceSite[];
-}

gitnexus-shared/src/scope-resolution/position-index.ts

@@ -1,166 +0,0 @@
-/**
- * `PositionIndex` — O(log N_file) scope-at-position lookup
- * (RFC §3.1; Ring 2 SHARED #912).
- *
- * Per-file sorted array of `(range, scopeId)` entries, sorted by start
- * position ASC (`startLine`, then `startCol`). `atPosition(filePath, line,
- * col)` binary-searches for the last entry whose start ≤ (line, col), then
- * scans backward through the sorted prefix and returns the first entry
- * whose range contains the query position.
- *
- * **Why this works.** `ScopeTree`'s invariants (parent strictly contains
- * child; siblings don't overlap) guarantee that the scopes containing a
- * given point form an **ancestor chain**. When scanning backward through
- * entries sorted by start position ASC, the first scope we find that
- * contains the query is the innermost one — any deeper-starting scope
- * that also contained the query would appear *later* in the sorted array,
- * but we're only scanning entries with start ≤ query, so anything later
- * necessarily starts after the query and can't contain it.
- *
- * Expected complexity: `O(log N_file + D)` where `D` is the lexical depth
- * at the query position (typically ≤ 10). Worst-case degrades to `O(N_file)`
- * only under pathological inputs (many scopes starting at the same line).
- *
- * **Line/column conventions.** Matches `Range` in `types.ts`: lines are
- * 1-based, columns are 0-based. Ranges are **inclusive on both ends** —
- * a scope whose `endLine:endCol` equals the query position still contains
- * it. That matches how tree-sitter captures bodies (closing brace
- * included) and how closed PR #902's `enclosingFunctions` behaved.
- */
-
-import type { Range, Scope, ScopeId } from './types.js';
-
-export interface PositionIndex {
-  /** Total scope entries indexed across all files. */
-  readonly size: number;
-  /**
-   * Innermost scope containing `(line, col)` in `filePath`, or `undefined`
-   * when nothing contains it (position before file start, after file end,
-   * or filePath not indexed).
-   *
-   * **Touching-boundary semantics.** Ranges are inclusive on both ends.
-   * When two sibling scopes share a boundary point — e.g.
-   * `[5:0, 10:0]` and `[10:0, 15:0]`, which is legal under `ScopeTree`'s
-   * non-overlap invariant — a query at the shared point `(10, 0)` is
-   * contained by **both**. The innermost-wins tie-break rule applies as
-   * usual: since neither is nested inside the other, the one that
-   * **starts latest** wins, i.e. the **right** sibling. The mechanism
-   * is the backward scan through the start-position-sorted array (see
-   * `findLastStartLteIndex` below) — both siblings land before the
-   * upper-bound cursor, and the right sibling is scanned first. Queries at non-boundary positions between them naturally
-   * fall to the unique containing scope.
-   */
-  atPosition(filePath: string, line: number, col: number): ScopeId | undefined;
-}
-
-/**
- * Build a `PositionIndex` from a flat list of `Scope` records.
- *
- * Duplicate `id`s are tolerated and deduplicated — the caller's
- * `ScopeTree.buildScopeTree` is the authoritative validator of scope
- * identity, and the position index does not need to re-check that
- * invariant.
- */
-export function buildPositionIndex(scopes: readonly Scope[]): PositionIndex {
-  const entriesByFile = new Map<string, Entry[]>();
-  const seen = new Set<ScopeId>();
-
-  for (const scope of scopes) {
-    if (seen.has(scope.id)) continue;
-    seen.add(scope.id);
-
-    let bucket = entriesByFile.get(scope.filePath);
-    if (bucket === undefined) {
-      bucket = [];
-      entriesByFile.set(scope.filePath, bucket);
-    }
-    bucket.push({ id: scope.id, range: scope.range });
-  }
-
-  for (const bucket of entriesByFile.values()) {
-    bucket.sort(compareEntry);
-  }
-
-  return wrapIndex(entriesByFile, seen.size);
-}
-
-// ─── Internals ──────────────────────────────────────────────────────────────
-
-interface Entry {
-  readonly id: ScopeId;
-  readonly range: Range;
-}
-
-/**
- * Sort by start position ASC, breaking ties by end position DESC so that
- * larger (outer) scopes appear before their smaller (inner) co-starting
- * siblings in the array. Makes the backward-scan contract crisp: the
- * first containing hit from the end of the scanned prefix is the
- * innermost scope.
- */
-function compareEntry(a: Entry, b: Entry): number {
-  if (a.range.startLine !== b.range.startLine) return a.range.startLine - b.range.startLine;
-  if (a.range.startCol !== b.range.startCol) return a.range.startCol - b.range.startCol;
-  if (a.range.endLine !== b.range.endLine) return b.range.endLine - a.range.endLine;
-  return b.range.endCol - a.range.endCol;
-}
-
-/** Whether `(line, col)` is at or after `range`'s start. */
-function startIsAtOrBefore(range: Range, line: number, col: number): boolean {
-  if (range.startLine < line) return true;
-  if (range.startLine > line) return false;
-  return range.startCol <= col;
-}
-
-/** Whether `(line, col)` is at or before `range`'s end (inclusive). */
-function endIsAtOrAfter(range: Range, line: number, col: number): boolean {
-  if (range.endLine > line) return true;
-  if (range.endLine < line) return false;
-  return range.endCol >= col;
-}
-
-/**
- * Return the largest index `i` in `arr` where `arr[i].range` starts at or
- * before `(line, col)`. Returns `-1` if no entry starts ≤ the query.
- *
- * Classic "upper bound - 1" binary search: find the first entry that
- * starts *after* the query, then step back one.
- */
-function findLastStartLteIndex(arr: readonly Entry[], line: number, col: number): number {
-  let lo = 0;
-  let hi = arr.length;
-  while (lo < hi) {
-    const mid = (lo + hi) >>> 1;
-    if (startIsAtOrBefore(arr[mid]!.range, line, col)) {
-      lo = mid + 1;
-    } else {
-      hi = mid;
-    }
-  }
-  return lo - 1;
-}
-
-function wrapIndex(entriesByFile: Map<string, Entry[]>, size: number): PositionIndex {
-  return {
-    get size() {
-      return size;
-    },
-    atPosition(filePath: string, line: number, col: number): ScopeId | undefined {
-      const bucket = entriesByFile.get(filePath);
-      if (bucket === undefined || bucket.length === 0) return undefined;
-
-      const endIdx = findLastStartLteIndex(bucket, line, col);
-      if (endIdx < 0) return undefined;
-
-      // Scan backward; first containing hit is innermost (see file header).
-      for (let i = endIdx; i >= 0; i--) {
-        const entry = bucket[i]!;
-        if (endIsAtOrAfter(entry.range, line, col)) {
-          // `startIsAtOrBefore` is guaranteed true by the binary search.
-          return entry.id;
-        }
-      }
-      return undefined;
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/qualified-name-index.ts

@@ -1,92 +0,0 @@
-/**
- * `QualifiedNameIndex` — O(1) `qualifiedName → DefId[]` lookup across all kinds.
- *
- * Cross-kind fast path for qualified-name resolution
- * (`lookupQualified(qname, scope, params)` in RFC §4.5). Class, method,
- * field, and namespace defs all contribute to a single index here; consumers
- * filter the returned `DefId[]` by `p.acceptedKinds` at the call site.
- *
- * Returns `DefId[]` (not a single `DefId`) because multiple defs can legally
- * share a qualified name — partial classes in C#, method overloads, or
- * accidental cross-kind collisions. The lookup caller filters to the expected
- * kind(s) and ranks the survivors.
- *
- * Part of RFC #909 Ring 2 SHARED — #913.
- *
- * Consumed by: #917 (`Registry.lookup` qualified fast path, `resolveTypeRef`
- * dotted fallback via #916).
- */
-
-import type { SymbolDefinition } from './symbol-definition.js';
-import type { DefId } from './types.js';
-
-export interface QualifiedNameIndex {
-  readonly byQualifiedName: ReadonlyMap<string, readonly DefId[]>;
-  readonly size: number;
-  /** Returns all `DefId`s registered under this qualified name; empty frozen
-   *  array on miss so callers can iterate without null checks. */
-  get(qualifiedName: string): readonly DefId[];
-  has(qualifiedName: string): boolean;
-}
-
-/**
- * Build a `QualifiedNameIndex` from a flat list of `SymbolDefinition` records.
- *
- * Only defs with a non-empty `qualifiedName` contribute; defs without one are
- * silently skipped (not every kind carries a qualified name — anonymous or
- * top-level symbols, dynamic-unresolved imports, etc.).
- *
- * **Duplicate policy: appended in input order.** Each unique `(qname, DefId)`
- * pair contributes at most once — repeated entries for the same pair are
- * deduplicated. Distinct `DefId`s sharing a `qname` accumulate in insertion
- * order (stable output for deterministic lookup ranking at the call site).
- *
- * Pure function — safe to call repeatedly; no side effects.
- */
-export function buildQualifiedNameIndex(defs: readonly SymbolDefinition[]): QualifiedNameIndex {
-  const byQualifiedName = new Map<string, DefId[]>();
-  const seenPairs = new Set<string>();
-
-  for (const def of defs) {
-    const qname = def.qualifiedName;
-    if (qname === undefined || qname.length === 0) continue;
-
-    const pairKey = `${qname}\0${def.nodeId}`;
-    if (seenPairs.has(pairKey)) continue;
-    seenPairs.add(pairKey);
-
-    const bucket = byQualifiedName.get(qname);
-    if (bucket === undefined) {
-      byQualifiedName.set(qname, [def.nodeId]);
-    } else {
-      bucket.push(def.nodeId);
-    }
-  }
-
-  // Freeze bucket arrays so consumers can't mutate the index.
-  const frozen = new Map<string, readonly DefId[]>();
-  for (const [k, v] of byQualifiedName) {
-    frozen.set(k, Object.freeze(v.slice()));
-  }
-
-  return wrapIndex(frozen);
-}
-
-// ─── Internal ───────────────────────────────────────────────────────────────
-
-const EMPTY: readonly DefId[] = Object.freeze([]);
-
-function wrapIndex(byQualifiedName: Map<string, readonly DefId[]>): QualifiedNameIndex {
-  return {
-    byQualifiedName,
-    get size() {
-      return byQualifiedName.size;
-    },
-    get(qualifiedName: string): readonly DefId[] {
-      return byQualifiedName.get(qualifiedName) ?? EMPTY;
-    },
-    has(qualifiedName: string): boolean {
-      return byQualifiedName.has(qualifiedName);
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/reference-site.ts

@@ -1,82 +0,0 @@
-/**
- * `ReferenceSite` — a pre-resolution usage fact collected by `ScopeExtractor`
- * (RFC §3.2 Phase 1; Ring 2 PKG #919).
- *
- * One record per `@reference.*` capture. The extractor records:
- *   - the name being referenced (method/field/class name),
- *   - the source range,
- *   - the innermost lexical scope containing the reference,
- *   - the reference kind (call, read, write, inherits, etc.),
- *   - optional call-form classification from `provider.classifyCallForm`,
- *   - optional explicit-receiver hint for dotted calls (`user.save()`),
- *   - optional arity for call sites.
- *
- * Reference sites are consumed by the resolution phase (RFC §3.2 Phase 4)
- * which routes each through `Registry.lookup` / `resolveTypeRef` and
- * emits the final `Reference` record into `ReferenceIndex`.
- *
- * **Pre-resolution only.** `ReferenceSite` intentionally carries no
- * `toDef`, `confidence`, or `evidence`. Those are populated by the
- * resolution step that reads this record and produces a `Reference`
- * (defined in `./types.ts`).
- */
-
-import type { Range, ScopeId } from './types.js';
-
-/**
- * What kind of usage this reference represents — the graph-edge kind
- * emitted after resolution (`CALLS`, `READS`, `WRITES`, etc.).
- *
- * Matches the `kind` field on `Reference` in `./types.ts` so the
- * resolution phase can pass it through without re-classification.
- */
-export type ReferenceKind =
-  | 'call'
-  | 'read'
-  | 'write'
-  | 'type-reference'
-  | 'inherits'
-  | 'import-use';
-
-/**
- * How a call site binds its target. Informs `Registry.lookup` Step 2
- * (type-binding path):
- *   - `'free'`   — bare call (no receiver); resolution via lexical chain.
- *   - `'member'` — dotted call (`x.foo()`); resolution via receiver type.
- *   - `'constructor'` — `new Foo()`; receiver is the class itself.
- *   - `'index'`  — index expression (`arr[0]`); rare as a dispatch site.
- *
- * Only meaningful for `kind === 'call'`; ignored for reads/writes.
- */
-export type CallForm = 'free' | 'member' | 'constructor' | 'index';
-
-export interface ReferenceSite {
-  /** The name being referenced (e.g., `'save'`, `'User'`, `'count'`). */
-  readonly name: string;
-  /** Source-text range of this reference. */
-  readonly atRange: Range;
-  /**
-   * Innermost lexical scope that contains `atRange`. Resolved by the
-   * extractor via position lookup and frozen here so the resolution
-   * phase doesn't re-compute it per call.
-   */
-  readonly inScope: ScopeId;
-  readonly kind: ReferenceKind;
-  /** Set when `kind === 'call'`. */
-  readonly callForm?: CallForm;
-  /**
-   * Explicit receiver for dotted calls (`user.save()` → `{ name: 'user' }`).
-   * Passed through to `Registry.lookup.explicitReceiver`.
-   */
-  readonly explicitReceiver?: { readonly name: string };
-  /** Argument count at the call site; used by `provider.arityCompatibility`. */
-  readonly arity?: number;
-  /**
-   * Inferred argument types at the call site, one per argument. An
-   * empty-string entry means "unknown" — consumers narrowing overload
-   * candidates treat unknown as any-match. Populated by languages
-   * that can derive types from literals / constructor expressions
-   * (C#: `42` → `'int'`, `"alice"` → `'string'`).
-   */
-  readonly argumentTypes?: readonly string[];
-}

gitnexus-shared/src/scope-resolution/registries/class-registry.ts

@@ -1,41 +0,0 @@
-/**
- * `ClassRegistry` — scope-aware lookup for class-like symbols
- * (RFC §4.4; Ring 2 SHARED #917).
- *
- * Thin wrapper over `lookupCore`, specialized for class kinds:
- *
- *   - `acceptedKinds` = Class / Interface / Enum / Struct / Union /
- *     Trait / TypeAlias / Typedef / Record / Delegate / Annotation /
- *     Template / Namespace.
- *   - `useReceiverTypeBinding` is **false** — classes are resolved by
- *     name through the lexical chain + global qualified fallback, not
- *     via a receiver type.
- *   - Arity filter is not applicable (classes are not called with
- *     argument counts at lookup time).
- */
-
-import type { Resolution, ScopeId } from '../types.js';
-import { lookupCore, type CoreLookupParams } from './lookup-core.js';
-import { CLASS_KINDS, type RegistryContext } from './context.js';
-
-export interface ClassRegistry {
-  /**
-   * Look up a class-like symbol by simple or dotted name anchored at
-   * `scope`. Returns a confidence-ranked `Resolution[]`; consume `[0]`
-   * for the best answer.
-   */
-  lookup(name: string, scope: ScopeId): readonly Resolution[];
-}
-
-export function buildClassRegistry(ctx: RegistryContext): ClassRegistry {
-  const params: CoreLookupParams = {
-    acceptedKinds: CLASS_KINDS,
-    useReceiverTypeBinding: false,
-    ownerScopedContributor: null,
-  };
-  return {
-    lookup(name: string, scope: ScopeId) {
-      return lookupCore(name, scope, params, ctx);
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/registries/context.ts

@@ -1,110 +0,0 @@
-/**
- * `RegistryContext` — the injected state required by the scope-aware
- * registry lookups (RFC §4; Ring 2 SHARED #917).
- *
- * Bundles every Ring 2 index + every provider hook the 7-step algorithm
- * might consult. Threaded through `lookupCore` and the three public
- * registries unchanged; construction is the caller's responsibility
- * (typically once per workspace-indexing pass in Ring 2 PKG).
- *
- * The design intent is **pure-logic in `gitnexus-shared`, data + hooks
- * supplied by the caller**. Nothing here loads files, parses AST, or
- * reaches into the CLI package.
- */
-
-import type { NodeLabel } from '../../graph/types.js';
-import type { SymbolDefinition } from '../symbol-definition.js';
-import type { Callsite, DefId } from '../types.js';
-import type { DefIndex } from '../def-index.js';
-import type { QualifiedNameIndex } from '../qualified-name-index.js';
-import type { ModuleScopeIndex } from '../module-scope-index.js';
-import type { ScopeTree } from '../scope-tree.js';
-import type { MethodDispatchIndex } from '../method-dispatch-index.js';
-
-// ─── Provider hooks consumed by the registries ─────────────────────────────
-
-export interface RegistryProviders {
-  /**
-   * Language-specific arity compatibility between a callsite and a candidate
-   * `def`. Mirrors `LanguageProvider.arityCompatibility` from #911. Optional:
-   * when absent, every candidate receives `'unknown'` (neutral signal).
-   */
-  arityCompatibility?(callsite: Callsite, def: SymbolDefinition): ArityVerdict;
-}
-
-export type ArityVerdict = 'compatible' | 'unknown' | 'incompatible';
-
-// ─── Owner-scoped contributor (concrete shape for `RegistryContributor`) ────
-
-/**
- * Per-owner membership view plugged into `LookupParams.ownerScopedContributor`.
- *
- * When the caller knows a receiver is of type `Owner` (e.g., after
- * resolving an explicit receiver or via `self`), it can supply the
- * `Owner`'s own member bucket here. `lookupCore` treats hits from this
- * contributor as `origin: 'local'` inside the owner's body scope —
- * strongest-visibility evidence, unaffected by the scope-chain hop
- * deduction that punishes outer-scope hits.
- *
- * Ring 1's `RegistryContributor = unknown` opaque placeholder is narrowed
- * to this concrete shape here in Ring 2 SHARED (#917).
- */
-export interface OwnerScopedContributor {
-  /** The owner (class/struct/trait/interface) that bounds this view. */
-  readonly ownerDefId: DefId;
-  /**
-   * Methods / fields directly declared on the owner, keyed by simple name.
-   * Return empty array on miss; implementations should NOT walk the MRO —
-   * that's `MethodDispatchIndex`'s job, handled in the type-binding step.
-   */
-  byName(name: string): readonly SymbolDefinition[];
-}
-
-// ─── Top-level context threaded through every lookup ───────────────────────
-
-export interface RegistryContext {
-  readonly scopes: ScopeTree;
-  readonly defs: DefIndex;
-  readonly qualifiedNames: QualifiedNameIndex;
-  readonly moduleScopes: ModuleScopeIndex;
-  /**
-   * Method-dispatch index; required for method/field registries that
-   * honor `useReceiverTypeBinding`. Omit for class-only lookups.
-   */
-  readonly methodDispatch?: MethodDispatchIndex;
-  readonly providers: RegistryProviders;
-}
-
-// ─── Per-kind default `acceptedKinds` sets ─────────────────────────────────
-//
-// Exported so the three public registries stay declarative (each one just
-// points at the right constant + passes it to `lookupCore`).
-
-export const CLASS_KINDS: readonly NodeLabel[] = Object.freeze([
-  'Class',
-  'Interface',
-  'Enum',
-  'Struct',
-  'Union',
-  'Trait',
-  'TypeAlias',
-  'Typedef',
-  'Record',
-  'Delegate',
-  'Annotation',
-  'Template',
-  'Namespace',
-]);
-
-export const METHOD_KINDS: readonly NodeLabel[] = Object.freeze([
-  'Method',
-  'Function',
-  'Constructor',
-]);
-
-export const FIELD_KINDS: readonly NodeLabel[] = Object.freeze([
-  'Variable',
-  'Property',
-  'Const',
-  'Static',
-]);

gitnexus-shared/src/scope-resolution/registries/evidence.ts

@@ -1,196 +0,0 @@
-/**
- * `composeEvidence` — translate accumulated raw signals per candidate
- * into a `ResolutionEvidence[]` using the authoritative `EvidenceWeights`
- * map (RFC §4.3 + Appendix A; Ring 2 SHARED #917).
- *
- * Each `RawSignals` record describes what was observed about a candidate
- * during the 7-step walk: where it was found, at what depth, whether
- * anything corroborates it. This module turns those raw facts into the
- * typed evidence list attached to the outgoing `Resolution`.
- *
- * **Every weight comes from `EvidenceWeights`.** No inline magic numbers.
- * Extends issue #429 (centralize hardcoded confidence values).
- *
- * **Confidence compose rule.** Signals add; the sum is capped at 1.0 at
- * the call site (inside `lookupCore`). This module only emits the list;
- * it does NOT compute the capped sum so callers can inspect per-signal
- * contributions for debugging.
- */
-
-import type { BindingRef, ResolutionEvidence } from '../types.js';
-import { EvidenceWeights, typeBindingWeightAtDepth } from '../evidence-weights.js';
-
-/**
- * Raw signals observed for a single candidate during the 7-step walk.
- * Optional fields encode "this signal did not fire"; presence encodes
- * "emit an evidence record".
- */
-export interface RawSignals {
-  // ── Where-found ────────────────────────────────────────────────────────
-  /** Visibility origin of the binding that produced this candidate. */
-  readonly origin?: BindingRef['origin'] | 'global-qualified' | 'global-name';
-  /** Depth at which the binding was found (hops up from start scope). */
-  readonly scopeChainDepth?: number;
-  /** `ImportEdge` that brought the name in; present when origin is a non-local. */
-  readonly viaUnlinkedImport?: boolean;
-
-  // ── Type-binding path ──────────────────────────────────────────────────
-  /** Set when the candidate came via the receiver's type-binding MRO walk. */
-  readonly typeBindingMroDepth?: number;
-
-  // ── Corroborators ──────────────────────────────────────────────────────
-  /** `def.ownerId === resolvedReceiver.def.nodeId`. */
-  readonly ownerMatch?: boolean;
-  /** Always fires for candidates that pass `acceptedKinds`; weight 0. */
-  readonly kindMatch: true;
-
-  // ── Arity ──────────────────────────────────────────────────────────────
-  readonly arityVerdict?: 'compatible' | 'unknown' | 'incompatible';
-
-  // ── Dynamic-unresolved passthrough ─────────────────────────────────────
-  /** Candidate flows through a `kind: 'dynamic-unresolved'` ImportEdge. */
-  readonly dynamicUnresolved?: boolean;
-}
-
-/**
- * Compose the raw signals into a stable `ResolutionEvidence[]` list.
- *
- * Emission order mirrors the `EvidenceWeights` layout: where-found →
- * type-binding → corroborators → arity → degraded. Stable order makes
- * the per-signal contributions easy to reason about in tests and in the
- * shadow-mode parity dashboard.
- */
-export function composeEvidence(signals: RawSignals): readonly ResolutionEvidence[] {
-  const out: ResolutionEvidence[] = [];
-
-  // ── Where-found visibility ─────────────────────────────────────────────
-  if (signals.origin !== undefined) {
-    const baseWeight = getOriginWeight(signals.origin);
-    const capped = signals.viaUnlinkedImport
-      ? baseWeight * EvidenceWeights.unlinkedImportMultiplier
-      : baseWeight;
-    const evidenceKind = whereFoundEvidenceKind(signals.origin);
-    out.push({
-      kind: evidenceKind,
-      weight: capped,
-      ...(signals.viaUnlinkedImport
-        ? { note: `via unresolved import (${EvidenceWeights.unlinkedImportMultiplier}× cap)` }
-        : {}),
-    });
-  }
-
-  // ── Scope-chain depth deduction (per-hop, only meaningful for lexical
-  // hits where scopeChainDepth ≥ 1). Depth 0 = no deduction; depth N ≥ 1
-  // emits a single `scope-chain` evidence with the accumulated penalty.
-  if (signals.scopeChainDepth !== undefined && signals.scopeChainDepth > 0) {
-    out.push({
-      kind: 'scope-chain',
-      weight: EvidenceWeights.scopeChainPerDepth * signals.scopeChainDepth,
-      note: `depth=${signals.scopeChainDepth}`,
-    });
-  }
-
-  // ── Type-binding / MRO path ────────────────────────────────────────────
-  if (signals.typeBindingMroDepth !== undefined) {
-    out.push({
-      kind: 'type-binding',
-      weight: typeBindingWeightAtDepth(signals.typeBindingMroDepth),
-      note: `mroDepth=${signals.typeBindingMroDepth}`,
-    });
-  }
-
-  // ── Owner match (explanatory for debug) ────────────────────────────────
-  if (signals.ownerMatch === true) {
-    out.push({
-      kind: 'owner-match',
-      weight: EvidenceWeights.ownerMatch,
-    });
-  }
-
-  // ── Kind match (always present; weight 0; retained for debuggability) ──
-  out.push({
-    kind: 'kind-match',
-    weight: EvidenceWeights.kindMatch,
-  });
-
-  // ── Arity ──────────────────────────────────────────────────────────────
-  if (signals.arityVerdict !== undefined) {
-    const weight =
-      signals.arityVerdict === 'compatible'
-        ? EvidenceWeights.arityMatchCompatible
-        : signals.arityVerdict === 'incompatible'
-          ? EvidenceWeights.arityMatchIncompatible
-          : EvidenceWeights.arityMatchUnknown;
-    out.push({
-      kind: 'arity-match',
-      weight,
-      note: signals.arityVerdict,
-    });
-  }
-
-  // ── Dynamic-unresolved (degraded signal) ───────────────────────────────
-  if (signals.dynamicUnresolved === true) {
-    out.push({
-      kind: 'dynamic-import-unresolved',
-      weight: EvidenceWeights.dynamicImportUnresolved,
-    });
-  }
-
-  return out;
-}
-
-/**
- * Sum evidence weights and clamp to `[0, 1]`. Separate from `composeEvidence`
- * so tests and the parity dashboard can inspect the raw evidence list.
- */
-export function confidenceFromEvidence(evidence: readonly ResolutionEvidence[]): number {
-  let sum = 0;
-  for (const e of evidence) sum += e.weight;
-  if (sum < 0) return 0;
-  if (sum > 1) return 1;
-  return sum;
-}
-
-// ─── Internal ───────────────────────────────────────────────────────────────
-
-function getOriginWeight(origin: NonNullable<RawSignals['origin']>): number {
-  switch (origin) {
-    case 'local':
-      return EvidenceWeights.local;
-    case 'import':
-      return EvidenceWeights.import;
-    case 'reexport':
-      return EvidenceWeights.reexport;
-    case 'namespace':
-      return EvidenceWeights.namespace;
-    case 'wildcard':
-      return EvidenceWeights.wildcard;
-    case 'global-qualified':
-      return EvidenceWeights.globalQualified;
-    case 'global-name':
-      // Reserved for Ring 3 byName global index. `lookupCore` today only
-      // emits `'global-qualified'` (via `lookupQualified`, dotted-name
-      // fallback); no code path constructs `origin: 'global-name'` yet.
-      // Kept here so the Appendix A weight stays live and `composeEvidence`
-      // remains exhaustive over the origin union.
-      return EvidenceWeights.globalName;
-  }
-}
-
-function whereFoundEvidenceKind(
-  origin: NonNullable<RawSignals['origin']>,
-): ResolutionEvidence['kind'] {
-  switch (origin) {
-    case 'local':
-      return 'local';
-    case 'import':
-    case 'reexport':
-    case 'namespace':
-    case 'wildcard':
-      return 'import';
-    case 'global-qualified':
-      return 'global-qualified';
-    case 'global-name':
-      return 'global-name';
-  }
-}

gitnexus-shared/src/scope-resolution/registries/field-registry.ts

@@ -1,43 +0,0 @@
-/**
- * `FieldRegistry` — scope-aware lookup for field / property / variable
- * access (RFC §4.4; Ring 2 SHARED #917).
- *
- * Thin wrapper over `lookupCore`, specialized for data-member kinds:
- *
- *   - `acceptedKinds` = Variable / Property / Const / Static.
- *   - `useReceiverTypeBinding` is **true** — fields are resolved against
- *     the receiver type's MRO first, then via the lexical chain for
- *     free variables.
- *   - `callsite` is not meaningful for field access (no arity), but the
- *     `explicitReceiver` and `ownerScopedContributor` knobs are.
- */
-
-import type { Resolution, ScopeId } from '../types.js';
-import { lookupCore, type CoreLookupParams } from './lookup-core.js';
-import type { OwnerScopedContributor, RegistryContext } from './context.js';
-import { FIELD_KINDS } from './context.js';
-
-export interface FieldLookupOptions {
-  readonly explicitReceiver?: { readonly name: string };
-  readonly ownerScopedContributor?: OwnerScopedContributor;
-}
-
-export interface FieldRegistry {
-  lookup(name: string, scope: ScopeId, options?: FieldLookupOptions): readonly Resolution[];
-}
-
-export function buildFieldRegistry(ctx: RegistryContext): FieldRegistry {
-  return {
-    lookup(name: string, scope: ScopeId, options: FieldLookupOptions = {}) {
-      const params: CoreLookupParams = {
-        acceptedKinds: FIELD_KINDS,
-        useReceiverTypeBinding: true,
-        ownerScopedContributor: options.ownerScopedContributor ?? null,
-        ...(options.explicitReceiver !== undefined
-          ? { explicitReceiver: options.explicitReceiver }
-          : {}),
-      };
-      return lookupCore(name, scope, params, ctx);
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/registries/lookup-core.ts

@@ -1,461 +0,0 @@
-/**
- * `lookupCore` — the shared 7-step canonical resolution algorithm
- * (RFC §4.2; Ring 2 SHARED #917).
- *
- * Pure function. Given a name, a starting scope, and per-kind parameters,
- * walks lexical scopes + optional type-binding MRO + optional owner
- * contributor + global qualified-name fallback, and returns a ranked
- * `Resolution[]` with per-candidate evidence.
- *
- * All three public registries (`ClassRegistry` / `MethodRegistry` /
- * `FieldRegistry`) dispatch into this function, differing only in the
- * parameters they pass. The CHOICE of which steps fire is expressed
- * through `LookupParams`, not through different algorithms per kind.
- *
- * ## Algorithm (RFC §4.2, verbatim names)
- *
- * **Step 1 — Lexical scope-chain walk.** From `startScope`, walk
- *   parent-ward. At each scope, consult `scope.bindings.get(name)`:
- *     - Filter candidates whose `def.type ∈ acceptedKinds`.
- *     - For each surviving candidate, record a raw signal with the
- *       binding's origin + the current scope-chain depth.
- *     - **Hard shadow.** If `bindings.get(name)` is non-empty (including
- *       non-kind-matching candidates), stop walking. The name is
- *       lexically bound here; outer scopes are not consulted.
- *
- * **Step 2 — Type-binding resolution.** When `useReceiverTypeBinding`
- *   is true, resolve the receiver's type at `startScope` (from
- *   `scope.typeBindings`), then walk the MRO via
- *   `MethodDispatchIndex.mroFor(ownerDefId)`. Membership per owner comes
- *   through `RegistryContext.methodDispatch` + owner lookups into
- *   `scope.ownedDefs`; each hit records a raw signal with the owner's
- *   MRO depth.
- *
- * **Step 3 — Owner-scoped contributor.** When
- *   `params.ownerScopedContributor` is present, merge its `byName(name)`
- *   hits with `origin: 'local'` (they are declared directly on the
- *   receiver). Distinct from Step 2 — Step 2 walks the MRO; Step 3 only
- *   looks at the directly-declared owner members.
- *
- * **Step 4 — Kind filter (emit `kind-match` evidence).** Already
- *   applied during Steps 1-3; this step just adds a `kind-match` signal
- *   at weight 0 to every candidate for debuggability (so the evidence
- *   array is self-describing).
- *
- * **Step 5 — Arity filter.** Call `providers.arityCompatibility(callsite,
- *   def)` per surviving candidate. Verdicts: `compatible` / `unknown` /
- *   `incompatible`. If at least one candidate is `compatible`, drop
- *   `incompatible` ones. Otherwise keep all (the penalty weight alone
- *   will rank them lower but they remain in the result).
- *
- * **Step 6 — Global fallback.** When Steps 1-3 produced **no**
- *   candidates and the name contains a `.`, consult the
- *   `QualifiedNameIndex` via `lookupQualified` — see §4.5. The `scope`
- *   argument is NOT passed here because global lookup is scope-agnostic.
- *
- * **Step 7 — Rank + tie-break.** Compose evidence, compute confidence
- *   (sum capped at 1.0), sort by the RFC Appendix B cascade.
- *
- * ## What this module does NOT do
- *
- *   - No AST reads (pure data in, pure data out).
- *   - No `gitnexus/` imports.
- *   - No language switches. Language-specific behavior flows exclusively
- *     through `providers.*` and the `params` object.
- *   - No caching. Callers that want memoization can wrap this function.
- */
-
-import type { NodeLabel } from '../../graph/types.js';
-import type { SymbolDefinition } from '../symbol-definition.js';
-import type {
-  BindingRef,
-  Callsite,
-  DefId,
-  LookupParams,
-  Resolution,
-  Scope,
-  ScopeId,
-} from '../types.js';
-import type { OriginForTieBreak } from '../origin-priority.js';
-import { composeEvidence, confidenceFromEvidence, type RawSignals } from './evidence.js';
-import { compareByConfidenceWithTiebreaks, type TieBreakKey } from './tie-breaks.js';
-import { lookupQualified } from './lookup-qualified.js';
-import type { ArityVerdict, OwnerScopedContributor, RegistryContext } from './context.js';
-
-// ─── Public entry point ─────────────────────────────────────────────────────
-
-/** Extended `LookupParams` narrowing `ownerScopedContributor` to the concrete shape. */
-export interface CoreLookupParams extends Omit<LookupParams, 'ownerScopedContributor'> {
-  readonly ownerScopedContributor: OwnerScopedContributor | null;
-  /** Call-site description forwarded to `arityCompatibility`. Optional — for non-call lookups. */
-  readonly callsite?: Callsite;
-}
-
-/**
- * Run the 7-step lookup. Returns a non-empty `Resolution[]` when any
- * candidate was found; an empty array otherwise. Callers consume `[0]`
- * for the best answer and optionally inspect the rest for alternates.
- */
-export function lookupCore(
-  name: string,
-  startScope: ScopeId,
-  params: CoreLookupParams,
-  ctx: RegistryContext,
-): readonly Resolution[] {
-  const acceptedKinds = new Set<NodeLabel>(params.acceptedKinds);
-  const perCandidate = new Map<DefId, CandidateState>();
-
-  // ── Step 1: lexical scope-chain walk ──────────────────────────────────
-  const lexicalShadowed = walkLexicalChain(name, startScope, acceptedKinds, ctx, perCandidate);
-
-  // ── Step 2: type-binding / MRO walk (methods/fields) ──────────────────
-  if (params.useReceiverTypeBinding && ctx.methodDispatch !== undefined) {
-    walkReceiverTypeBinding(name, startScope, acceptedKinds, params, ctx, perCandidate);
-  }
-
-  // ── Step 3: owner-scoped contributor ──────────────────────────────────
-  if (params.ownerScopedContributor !== null) {
-    seedFromOwnerScopedContributor(
-      name,
-      params.ownerScopedContributor,
-      acceptedKinds,
-      perCandidate,
-    );
-  }
-
-  // ── Step 4: kind-match evidence (emitted by composeEvidence directly) ──
-  // Handled inside `composeEvidence`.
-
-  // ── Step 5: arity filter ──────────────────────────────────────────────
-  if (params.callsite !== undefined) {
-    applyArityFilter(params.callsite, perCandidate, ctx);
-  }
-
-  // ── Step 6: global fallback (only when Steps 1-3 produced nothing) ──
-  if (perCandidate.size === 0 && !lexicalShadowed && name.includes('.')) {
-    const globals = lookupQualified(name, { acceptedKinds: params.acceptedKinds }, ctx);
-    if (globals.length > 0) return globals;
-  }
-
-  if (perCandidate.size === 0) return EMPTY;
-
-  // ── Step 7: compose evidence + rank ──────────────────────────────────
-  return rankCandidates(perCandidate);
-}
-
-// ─── Internal state ────────────────────────────────────────────────────────
-
-interface CandidateState {
-  readonly def: SymbolDefinition;
-  readonly signals: MutableRawSignals;
-  readonly tieBreakKey: MutableTieBreakKey;
-}
-
-interface MutableRawSignals {
-  origin?: BindingRef['origin'] | 'global-qualified' | 'global-name';
-  scopeChainDepth?: number;
-  viaUnlinkedImport?: boolean;
-  typeBindingMroDepth?: number;
-  ownerMatch?: boolean;
-  kindMatch: true;
-  arityVerdict?: ArityVerdict;
-  dynamicUnresolved?: boolean;
-}
-
-interface MutableTieBreakKey {
-  scopeDepth: number;
-  mroDepth: number;
-  origin: OriginForTieBreak;
-}
-
-function ensureCandidate(
-  perCandidate: Map<DefId, CandidateState>,
-  def: SymbolDefinition,
-): CandidateState {
-  const existing = perCandidate.get(def.nodeId);
-  if (existing !== undefined) return existing;
-  const fresh: CandidateState = {
-    def,
-    signals: { kindMatch: true },
-    tieBreakKey: { scopeDepth: 0, mroDepth: 0, origin: 'local' },
-  };
-  perCandidate.set(def.nodeId, fresh);
-  return fresh;
-}
-
-// ─── Step 1 implementation ─────────────────────────────────────────────────
-
-/**
- * Walk the lexical scope chain from `startScope` upward. Returns `true`
- * iff a scope with any `bindings.get(name)` entries was found — the
- * caller uses this to decide whether to run the global fallback.
- */
-function walkLexicalChain(
-  name: string,
-  startScope: ScopeId,
-  acceptedKinds: ReadonlySet<NodeLabel>,
-  ctx: RegistryContext,
-  perCandidate: Map<DefId, CandidateState>,
-): boolean {
-  let currentId: ScopeId | null = startScope;
-  let depth = 0;
-  const visited = new Set<ScopeId>();
-
-  while (currentId !== null) {
-    if (visited.has(currentId)) return false;
-    visited.add(currentId);
-
-    const scope: Scope | undefined = ctx.scopes.getScope(currentId);
-    if (scope === undefined) return false;
-
-    const bindings = scope.bindings.get(name);
-    if (bindings !== undefined && bindings.length > 0) {
-      for (const binding of bindings) {
-        if (!acceptedKinds.has(binding.def.type)) continue;
-        recordLexicalHit(perCandidate, binding, depth);
-      }
-      return true; // hard shadow regardless of kind-filter survivorship
-    }
-
-    currentId = scope.parent;
-    depth++;
-  }
-
-  return false;
-}
-
-function recordLexicalHit(
-  perCandidate: Map<DefId, CandidateState>,
-  binding: BindingRef,
-  scopeChainDepth: number,
-): void {
-  const state = ensureCandidate(perCandidate, binding.def);
-  state.signals.origin = binding.origin;
-  state.signals.scopeChainDepth = scopeChainDepth;
-  if (binding.via?.linkStatus === 'unresolved') {
-    state.signals.viaUnlinkedImport = true;
-  }
-  if (binding.via?.kind === 'dynamic-unresolved') {
-    state.signals.dynamicUnresolved = true;
-  }
-  state.tieBreakKey.scopeDepth = scopeChainDepth;
-  state.tieBreakKey.origin = binding.origin as OriginForTieBreak;
-}
-
-// ─── Step 2 implementation ─────────────────────────────────────────────────
-
-function walkReceiverTypeBinding(
-  name: string,
-  startScope: ScopeId,
-  acceptedKinds: ReadonlySet<NodeLabel>,
-  params: CoreLookupParams,
-  ctx: RegistryContext,
-  perCandidate: Map<DefId, CandidateState>,
-): void {
-  const ownerDefId = resolveReceiverOwner(startScope, params, ctx);
-  if (ownerDefId === undefined) return;
-
-  if (ctx.methodDispatch === undefined) return;
-
-  const ownerDef = ctx.defs.get(ownerDefId);
-  if (ownerDef === undefined) return;
-
-  // Walk the owner itself at depth 0, then its MRO chain.
-  const walk: DefId[] = [ownerDefId, ...ctx.methodDispatch.mroFor(ownerDefId)];
-
-  for (let mroDepth = 0; mroDepth < walk.length; mroDepth++) {
-    const currentOwnerId = walk[mroDepth]!;
-    const members = collectOwnedMembers(currentOwnerId, name, ctx);
-    for (const def of members) {
-      if (!acceptedKinds.has(def.type)) continue;
-      recordTypeBindingHit(perCandidate, def, mroDepth, ownerDefId);
-    }
-  }
-}
-
-function resolveReceiverOwner(
-  startScope: ScopeId,
-  params: CoreLookupParams,
-  ctx: RegistryContext,
-): DefId | undefined {
-  // Explicit receiver: consult the callsite scope's typeBindings for the
-  // named receiver; the attached TypeRef identifies the owner. Without a
-  // ready resolveTypeRef call (that module is separate), we do a direct
-  // lookup and trust the caller to have populated the binding.
-  if (params.explicitReceiver !== undefined) {
-    return lookupReceiverType(startScope, params.explicitReceiver.name, ctx);
-  }
-
-  // Implicit `self` / `this` — the scope's typeBindings should carry it.
-  for (const implicitName of IMPLICIT_RECEIVERS) {
-    const owner = lookupReceiverType(startScope, implicitName, ctx);
-    if (owner !== undefined) return owner;
-  }
-  return undefined;
-}
-
-const IMPLICIT_RECEIVERS: readonly string[] = Object.freeze(['self', 'this']);
-
-function lookupReceiverType(
-  startScope: ScopeId,
-  receiverName: string,
-  ctx: RegistryContext,
-): DefId | undefined {
-  let currentId: ScopeId | null = startScope;
-  const visited = new Set<ScopeId>();
-  while (currentId !== null) {
-    if (visited.has(currentId)) return undefined;
-    visited.add(currentId);
-
-    const scope = ctx.scopes.getScope(currentId);
-    if (scope === undefined) return undefined;
-
-    const typeRef = scope.typeBindings.get(receiverName);
-    if (typeRef !== undefined) {
-      // rawName must resolve to a def via qualifiedNames; if it doesn't, we
-      // can't claim the receiver type. No fallback — that's what
-      // `resolveTypeRef` would do, but we keep this path lean and let
-      // callers pre-resolve if they want the richer semantics.
-      const candidateIds = ctx.qualifiedNames.get(typeRef.rawName);
-      if (candidateIds.length === 1) return candidateIds[0];
-      // Ambiguous (≥ 2) or missing (0) — caller must pre-resolve via
-      // `resolveTypeRef` (#916) if they want the richer semantics. We
-      // intentionally do NOT re-implement a simple-name fallback here.
-      return undefined;
-    }
-    currentId = scope.parent;
-  }
-  return undefined;
-}
-
-function collectOwnedMembers(
-  ownerDefId: DefId,
-  memberName: string,
-  ctx: RegistryContext,
-): readonly SymbolDefinition[] {
-  // An owner's members are defs whose `ownerId === ownerDefId` and whose
-  // simple name matches `memberName`. We iterate `defs.byId` — O(D) per
-  // call today. A future by-owner index would make this O(K); tracked as
-  // a follow-up optimization before Ring 3 flips go production.
-  const out: SymbolDefinition[] = [];
-  for (const def of ctx.defs.byId.values()) {
-    if (def.ownerId !== ownerDefId) continue;
-    if (simpleNameOf(def) !== memberName) continue;
-    out.push(def);
-  }
-  return out;
-}
-
-function simpleNameOf(def: SymbolDefinition): string | undefined {
-  if (def.qualifiedName === undefined || def.qualifiedName.length === 0) return undefined;
-  const dot = def.qualifiedName.lastIndexOf('.');
-  return dot === -1 ? def.qualifiedName : def.qualifiedName.slice(dot + 1);
-}
-
-function recordTypeBindingHit(
-  perCandidate: Map<DefId, CandidateState>,
-  def: SymbolDefinition,
-  mroDepth: number,
-  receiverOwner: DefId,
-): void {
-  const state = ensureCandidate(perCandidate, def);
-  const existingMroDepth = state.signals.typeBindingMroDepth;
-  const firstHit = existingMroDepth === undefined;
-  // Only replace if this hit is shallower (smaller MRO depth). The local
-  // const lets TS narrow to `number` in the `else` branch so no `!`
-  // assertion is needed.
-  if (firstHit || mroDepth < existingMroDepth) {
-    state.signals.typeBindingMroDepth = mroDepth;
-    state.tieBreakKey.mroDepth = mroDepth;
-  }
-  if (def.ownerId === receiverOwner) {
-    state.signals.ownerMatch = true;
-  }
-  // Pure type-binding candidates (no lexical hit) would otherwise keep the
-  // `ensureCandidate` default `tieBreakKey.origin === 'local'`, making the
-  // Appendix B cascade lump them with local-origin candidates. Demote them
-  // to `'import'` — the strongest non-local origin — only when no earlier
-  // phase set an origin for this candidate. Lexical hits from Step 1 set
-  // `signals.origin` before Step 2 runs, so the guard skips them; Step 3
-  // (`seedFromOwnerScopedContributor`) runs AFTER Step 2 and unconditionally
-  // overrides `tieBreakKey.origin` back to `'local'` for direct-owner
-  // members, so any same-def overlap still ends up ranked correctly.
-  if (firstHit && state.signals.origin === undefined) {
-    state.tieBreakKey.origin = 'import';
-  }
-}
-
-// ─── Step 3 implementation ─────────────────────────────────────────────────
-
-function seedFromOwnerScopedContributor(
-  name: string,
-  contributor: OwnerScopedContributor,
-  acceptedKinds: ReadonlySet<NodeLabel>,
-  perCandidate: Map<DefId, CandidateState>,
-): void {
-  for (const def of contributor.byName(name)) {
-    if (!acceptedKinds.has(def.type)) continue;
-    const state = ensureCandidate(perCandidate, def);
-    // Treat the contributor's direct membership as `origin: 'local'` —
-    // strongest visibility, no scope-chain penalty.
-    state.signals.origin = 'local';
-    state.signals.scopeChainDepth = 0;
-    state.signals.ownerMatch = def.ownerId === contributor.ownerDefId;
-    state.tieBreakKey.origin = 'local';
-  }
-}
-
-// ─── Step 5 implementation ─────────────────────────────────────────────────
-
-function applyArityFilter(
-  callsite: Callsite,
-  perCandidate: Map<DefId, CandidateState>,
-  ctx: RegistryContext,
-): void {
-  const arityFn = ctx.providers.arityCompatibility;
-  if (arityFn === undefined) {
-    // No provider → record 'unknown' for every candidate; keeps signal
-    // shape uniform for composeEvidence.
-    for (const state of perCandidate.values()) {
-      state.signals.arityVerdict = 'unknown';
-    }
-    return;
-  }
-
-  let anyCompatible = false;
-  for (const state of perCandidate.values()) {
-    const verdict = arityFn(callsite, state.def);
-    state.signals.arityVerdict = verdict;
-    if (verdict === 'compatible') anyCompatible = true;
-  }
-
-  if (!anyCompatible) return;
-
-  // Filter: when at least one compatible candidate exists, drop incompatibles.
-  for (const [defId, state] of perCandidate) {
-    if (state.signals.arityVerdict === 'incompatible') {
-      perCandidate.delete(defId);
-    }
-  }
-}
-
-// ─── Step 7 implementation ─────────────────────────────────────────────────
-
-function rankCandidates(perCandidate: Map<DefId, CandidateState>): readonly Resolution[] {
-  const resolutions: Resolution[] = [];
-  const tieKeys = new Map<string, TieBreakKey>();
-
-  for (const state of perCandidate.values()) {
-    const evidence = composeEvidence(state.signals as RawSignals);
-    const confidence = confidenceFromEvidence(evidence);
-    resolutions.push({ def: state.def, confidence, evidence });
-    tieKeys.set(state.def.nodeId, { ...state.tieBreakKey });
-  }
-
-  resolutions.sort((a, b) => compareByConfidenceWithTiebreaks(a, b, tieKeys));
-  return Object.freeze(resolutions);
-}
-
-// ─── Constants ──────────────────────────────────────────────────────────────
-
-const EMPTY: readonly Resolution[] = Object.freeze([]);

gitnexus-shared/src/scope-resolution/registries/lookup-qualified.ts

@@ -1,71 +0,0 @@
-/**
- * `lookupQualified` — qualified-name fast path (RFC §4.5; Ring 2 SHARED #917).
- *
- * Consults `QualifiedNameIndex` directly, filters by `acceptedKinds`, and
- * returns `Resolution[]` with `origin: 'global-qualified'` evidence. Used by:
- *
- *   - `resolveTypeRef` dotted fallback (#916)
- *   - `Registry.lookup` Step 6 when no lexical candidate survived
- *   - Explicit dotted identifiers in Cypher / MCP tools where the caller
- *     knows the target's canonical qualified name
- *
- * **Strict + deterministic.** No receiver-type resolution, no scope walk.
- * Every surviving candidate gets the same base confidence (from
- * `EvidenceWeights.globalQualified`), then the tie-break cascade
- * disambiguates.
- */
-
-import type { NodeLabel } from '../../graph/types.js';
-import type { Resolution } from '../types.js';
-import { composeEvidence, confidenceFromEvidence } from './evidence.js';
-import { compareByConfidenceWithTiebreaks, type TieBreakKey } from './tie-breaks.js';
-import type { RegistryContext } from './context.js';
-
-export interface LookupQualifiedParams {
-  readonly acceptedKinds: readonly NodeLabel[];
-}
-
-/**
- * Look up a canonical qualified name (e.g., `app.models.User`) across all
- * defs, filtered by `acceptedKinds`. Returns an empty array when the name
- * is not indexed or no candidate matches the kind filter.
- *
- * Callers consume `[0]` for the strict single-return answer; the remainder
- * carries alternate candidates (partial classes, overloads, accidental
- * cross-kind hits) ordered by the tie-break cascade.
- */
-export function lookupQualified(
-  qualifiedName: string,
-  params: LookupQualifiedParams,
-  ctx: RegistryContext,
-): readonly Resolution[] {
-  const defIds = ctx.qualifiedNames.get(qualifiedName);
-  if (defIds.length === 0) return EMPTY;
-
-  const acceptedKinds = new Set<NodeLabel>(params.acceptedKinds);
-
-  const resolutions: Resolution[] = [];
-  const tieKeys = new Map<string, TieBreakKey>();
-
-  for (const defId of defIds) {
-    const def = ctx.defs.get(defId);
-    if (def === undefined) continue;
-    if (!acceptedKinds.has(def.type)) continue;
-
-    const evidence = composeEvidence({ origin: 'global-qualified', kindMatch: true });
-    const confidence = confidenceFromEvidence(evidence);
-    resolutions.push({ def, confidence, evidence });
-    tieKeys.set(def.nodeId, {
-      scopeDepth: 0,
-      mroDepth: 0,
-      origin: 'global-qualified',
-    });
-  }
-
-  if (resolutions.length === 0) return EMPTY;
-
-  resolutions.sort((a, b) => compareByConfidenceWithTiebreaks(a, b, tieKeys));
-  return Object.freeze(resolutions);
-}
-
-const EMPTY: readonly Resolution[] = Object.freeze([]);

gitnexus-shared/src/scope-resolution/registries/method-registry.ts

@@ -1,54 +0,0 @@
-/**
- * `MethodRegistry` — scope-aware lookup for method / function / constructor
- * dispatch (RFC §4.4; Ring 2 SHARED #917).
- *
- * Thin wrapper over `lookupCore`, specialized for callable kinds:
- *
- *   - `acceptedKinds` = Method / Function / Constructor.
- *   - `useReceiverTypeBinding` is **true** — the type-binding + MRO walk
- *     (Step 2) is the primary evidence path for receiver-dispatched calls.
- *   - `callsite.arity` flows through to `provider.arityCompatibility`
- *     when provided. When the provider is absent, arity evidence is
- *     `unknown` (neutral signal).
- */
-
-import type { Callsite, Resolution, ScopeId } from '../types.js';
-import { lookupCore, type CoreLookupParams } from './lookup-core.js';
-import type { OwnerScopedContributor, RegistryContext } from './context.js';
-import { METHOD_KINDS } from './context.js';
-
-/**
- * Extra per-call parameters that vary across call sites but NOT across
- * registries. Kept as a separate shape so `MethodRegistry.lookup` stays
- * concise while still exposing the explicit-receiver + owner-contributor +
- * arity knobs the RFC algorithm needs.
- */
-export interface MethodLookupOptions {
-  /** Call-site arity for `provider.arityCompatibility`. */
-  readonly callsite?: Callsite;
-  /** Explicit receiver (e.g., `user` in `user.save()`). See §4.1. */
-  readonly explicitReceiver?: { readonly name: string };
-  /** Optional per-owner contributor (Step 3). */
-  readonly ownerScopedContributor?: OwnerScopedContributor;
-}
-
-export interface MethodRegistry {
-  lookup(name: string, scope: ScopeId, options?: MethodLookupOptions): readonly Resolution[];
-}
-
-export function buildMethodRegistry(ctx: RegistryContext): MethodRegistry {
-  return {
-    lookup(name: string, scope: ScopeId, options: MethodLookupOptions = {}) {
-      const params: CoreLookupParams = {
-        acceptedKinds: METHOD_KINDS,
-        useReceiverTypeBinding: true,
-        ownerScopedContributor: options.ownerScopedContributor ?? null,
-        ...(options.callsite !== undefined ? { callsite: options.callsite } : {}),
-        ...(options.explicitReceiver !== undefined
-          ? { explicitReceiver: options.explicitReceiver }
-          : {}),
-      };
-      return lookupCore(name, scope, params, ctx);
-    },
-  };
-}

gitnexus-shared/src/scope-resolution/registries/tie-breaks.ts

@@ -1,76 +0,0 @@
-/**
- * `compareByConfidenceWithTiebreaks` — the RFC §4.2 Step 7 total order
- * over `Resolution` candidates (Ring 2 SHARED #917).
- *
- * Primary key is confidence (DESC). Remaining ties within `CONFIDENCE_EPSILON`
- * fall through a deterministic cascade so the same inputs always produce
- * the same winner, independent of insertion order.
- *
- * Tie-break cascade (per RFC Appendix B):
- *
- *   1. confidence DESC                       (primary)
- *   2. scope depth ASC                       (nearer lexical scope wins)
- *   3. MRO depth ASC                         (nearer class in hierarchy wins)
- *   4. `ORIGIN_PRIORITY` ASC                 (local > import > … > global-name)
- *   5. DefId.localeCompare                   (final deterministic tiebreaker)
- *
- * The per-candidate inputs needed beyond `Resolution.confidence` —
- * `scopeDepth`, `mroDepth`, `origin` — are supplied via a sidecar
- * `TieBreakKey` so the comparator stays pure and `Resolution` itself
- * doesn't need to carry book-keeping fields.
- */
-
-import { ORIGIN_PRIORITY, type OriginForTieBreak } from '../origin-priority.js';
-import type { Resolution } from '../types.js';
-
-export const CONFIDENCE_EPSILON = 0.001;
-
-/** Side-information per candidate used for secondary tie-breaks. */
-export interface TieBreakKey {
-  readonly scopeDepth: number;
-  readonly mroDepth: number;
-  readonly origin: OriginForTieBreak;
-}
-
-/**
- * Pure comparator suitable for `Array.prototype.sort`. Return value follows
- * the JavaScript convention: negative → `a` wins, positive → `b` wins.
- *
- * **Important:** `keys` is keyed by `Resolution.def.nodeId`, not by array
- * index — stable across reorderings. Missing keys fall back to neutral
- * values (`scopeDepth: 0`, `mroDepth: 0`, `origin: 'local'`), which means
- * the tie-break degrades gracefully to defId-lexicographic ordering when
- * side-info is unavailable. That keeps the total order deterministic
- * even on malformed inputs.
- */
-export function compareByConfidenceWithTiebreaks(
-  a: Resolution,
-  b: Resolution,
-  keys: ReadonlyMap<string, TieBreakKey>,
-): number {
-  // Primary: confidence DESC, treating values within epsilon as equal.
-  const delta = b.confidence - a.confidence;
-  if (Math.abs(delta) >= CONFIDENCE_EPSILON) return delta < 0 ? -1 : 1;
-
-  const ka = keys.get(a.def.nodeId) ?? DEFAULT_KEY;
-  const kb = keys.get(b.def.nodeId) ?? DEFAULT_KEY;
-
-  // Secondary: scope depth ASC.
-  if (ka.scopeDepth !== kb.scopeDepth) return ka.scopeDepth - kb.scopeDepth;
-
-  // Tertiary: MRO depth ASC.
-  if (ka.mroDepth !== kb.mroDepth) return ka.mroDepth - kb.mroDepth;
-
-  // Quaternary: ORIGIN_PRIORITY ASC.
-  const po = ORIGIN_PRIORITY[ka.origin] - ORIGIN_PRIORITY[kb.origin];
-  if (po !== 0) return po;
-
-  // Final: DefId lexicographic, locale-aware for deterministic cross-platform output.
-  return a.def.nodeId.localeCompare(b.def.nodeId);
-}
-
-const DEFAULT_KEY: TieBreakKey = Object.freeze({
-  scopeDepth: 0,
-  mroDepth: 0,
-  origin: 'local',
-});

gitnexus-shared/src/scope-resolution/resolve-type-ref.ts

@@ -1,148 +0,0 @@
-/**
- * `resolveTypeRef` — strict single-return resolver for `TypeRef`s
- * (RFC §4.6; Ring 2 SHARED #916).
- *
- * Narrower contract than `Registry.lookup`: no name-only global fallback, no
- * confidence ranking, no arity check. Used by `Registry.lookup` Step 2 (type-
- * binding propagation) and by any caller that wants the single best type-
- * target for an annotation without paying for the full evidence pipeline.
- *
- * **Algorithm (strict).** Walk the scope chain from `ref.declaredAtScope`:
- *
- *   1. At each scope, inspect `bindings.get(ref.rawName)`:
- *      - If one of the bindings is a **type-kind** def with a **strict origin**
- *        (`'local' | 'import' | 'namespace' | 'reexport'`), return it.
- *      - If any binding for this name exists at this scope but none qualifies
- *        (e.g., a local variable named `User` shadows an outer import of class
- *        `User`), return `null`. The nearer binding shadows; we do NOT fall
- *        through to the global qualified-name index.
- *      - Otherwise continue to the parent scope.
- *   2. If the raw name is a dotted path (e.g., `'models.User'`) and the scope
- *      walk produced no match, consult `QualifiedNameIndex.byQualifiedName`.
- *      Only accept **exactly one** type-kind hit — anything ambiguous returns
- *      `null` rather than a guess.
- *   3. Return `null`.
- *
- * **What `'strict' origins' means.** `'wildcard'` is intentionally excluded.
- * A wildcard-expanded name (`from x import *`) is too loose to use as an
- * anchor for type resolution — it gives no signal about whether the name was
- * actually imported. `Registry.lookup` may accept wildcard bindings at its
- * own discretion (with lower evidence weight); `resolveTypeRef` does not.
- *
- * **What 'type-kind' means.** The subset of `NodeLabel` that a type annotation
- * may legitimately reference: class-like, interface-like, enum-like, and
- * alias-like kinds. See `TYPE_KINDS` below.
- *
- * Pure function — safe to call repeatedly; no side effects.
- */
-
-import type { NodeLabel } from '../graph/types.js';
-import type { SymbolDefinition } from './symbol-definition.js';
-import type { BindingRef, ScopeId, ScopeLookup, TypeRef } from './types.js';
-import type { DefIndex } from './def-index.js';
-import type { QualifiedNameIndex } from './qualified-name-index.js';
-
-// ─── Public contracts ───────────────────────────────────────────────────────
-
-/**
- * All inputs `resolveTypeRef` needs from the semantic model. Bundled into a
- * context object so the call site stays short and the interface is stable as
- * additional indexes get threaded through in later rings.
- */
-export interface ResolveTypeRefContext {
-  readonly scopes: ScopeLookup;
-  readonly defIndex: DefIndex;
-  readonly qualifiedNameIndex: QualifiedNameIndex;
-}
-
-// ─── Strict policy constants ────────────────────────────────────────────────
-
-/** `'wildcard'` is deliberately absent. See file header. */
-const STRICT_ORIGINS: ReadonlySet<BindingRef['origin']> = new Set<BindingRef['origin']>([
-  'local',
-  'import',
-  'namespace',
-  'reexport',
-]);
-
-/**
- * `NodeLabel` values that may appear on the RHS of a type annotation.
- *
- * Includes the usual class-like and interface-like kinds plus the alias-like
- * ones (`TypeAlias`, `Typedef`). `Namespace` is excluded — it is a scope
- * container, not a value type. `Function` / `Method` / `Variable` are
- * excluded by design: a `rawName` bound to them at a strict origin is a
- * *shadowing* binding, which the algorithm short-circuits to `null`.
- *
- * `'Type'` (the generic `NodeLabel` value) is also excluded — verified
- * against `gitnexus/src/core/ingestion/` at the time of writing, no
- * production extractor emits `type: 'Type'` for annotation-relevant
- * symbols. Should a future extractor start emitting it, add `'Type'`
- * here and add a test asserting the new path.
- */
-const TYPE_KINDS: ReadonlySet<NodeLabel> = new Set<NodeLabel>([
-  'Class',
-  'Interface',
-  'Enum',
-  'Struct',
-  'Union',
-  'Trait',
-  'TypeAlias',
-  'Typedef',
-  'Record',
-  'Delegate',
-  'Annotation',
-  'Template',
-]);
-
-// ─── Main entry point ──────────────────────────────────────────────────────
-
-export function resolveTypeRef(ref: TypeRef, ctx: ResolveTypeRefContext): SymbolDefinition | null {
-  // Phase 1: scope-chain walk anchored at the declaration site.
-  let currentId: ScopeId | null = ref.declaredAtScope;
-  const visited = new Set<ScopeId>();
-
-  while (currentId !== null) {
-    // Cycle guard — a well-formed scope tree never loops, but a bug in the
-    // construction path should fail fast here rather than hanging.
-    if (visited.has(currentId)) return null;
-    visited.add(currentId);
-
-    const scope = ctx.scopes.getScope(currentId);
-    if (scope === undefined) return null; // broken chain = unresolvable
-
-    const bindings = scope.bindings.get(ref.rawName);
-    if (bindings !== undefined && bindings.length > 0) {
-      // At least one binding exists at this scope → it is the shadowing site.
-      // Either one of them qualifies, or the name is shadowed by a non-type.
-      for (const binding of bindings) {
-        if (!STRICT_ORIGINS.has(binding.origin)) continue;
-        if (TYPE_KINDS.has(binding.def.type)) {
-          return binding.def;
-        }
-      }
-      // Shadowed by a non-type / non-strict-origin binding. Fail fast — no
-      // global fallback, no walk to the parent.
-      return null;
-    }
-
-    currentId = scope.parent;
-  }
-
-  // Phase 2: dotted fallback via `QualifiedNameIndex`. Only accept a unique
-  // type-kind hit; anything ambiguous returns null (strict: no guesses).
-  if (ref.rawName.includes('.')) {
-    const candidates = ctx.qualifiedNameIndex.get(ref.rawName);
-    let onlyTypeDef: SymbolDefinition | null = null;
-    for (const defId of candidates) {
-      const def = ctx.defIndex.get(defId);
-      if (def === undefined) continue;
-      if (!TYPE_KINDS.has(def.type)) continue;
-      if (onlyTypeDef !== null) return null; // ambiguous
-      onlyTypeDef = def;
-    }
-    if (onlyTypeDef !== null) return onlyTypeDef;
-  }
-
-  return null;
-}

gitnexus-shared/src/scope-resolution/scope-id.ts

@@ -1,57 +0,0 @@
-/**
- * `ScopeId` canonical constructor + string intern pool
- * (RFC §2.2; Ring 2 SHARED #912).
- *
- * `ScopeId` is a deterministic string derived from the scope's file path,
- * byte range, and kind:
- *
- *   scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}
- *
- * Two scopes produced by reparsing the same file at the same positions are
- * `===`-equal as strings. Beyond the canonical shape, `makeScopeId` also
- * **interns** the string through a process-local pool, so repeated calls
- * with structurally identical inputs return the same string reference —
- * making `Map<ScopeId, ...>` lookups and cache keys identity-fast.
- *
- * The intern pool is unbounded. The number of distinct `ScopeId`s across a
- * single indexing run is O(total scopes in workspace), which is bounded by
- * source-text size and already in memory; interning adds no asymptotic
- * pressure. `clearScopeIdInternPool` is exported for test isolation.
- */
-
-import type { Range } from './types.js';
-import type { ScopeId, ScopeKind } from './types.js';
-
-/** Inputs required to construct a canonical `ScopeId`. */
-export interface ScopeIdInput {
-  readonly filePath: string;
-  readonly range: Range;
-  readonly kind: ScopeKind;
-}
-
-/**
- * Build a canonical `ScopeId` from its structural parts and intern it.
- *
- * Pure + referentially transparent: given the same input shape, always
- * returns the same string reference for the lifetime of the pool.
- */
-export function makeScopeId(input: ScopeIdInput): ScopeId {
-  const raw = `scope:${input.filePath}#${input.range.startLine}:${input.range.startCol}-${input.range.endLine}:${input.range.endCol}:${input.kind}`;
-  const existing = INTERN_POOL.get(raw);
-  if (existing !== undefined) return existing;
-  INTERN_POOL.set(raw, raw);
-  return raw;
-}
-
-/**
- * Drop the intern pool. Intended for test setup/teardown — production code
- * should not need this, since the pool's memory usage is bounded by the
- * number of live scopes and cleaning it mid-run would break identity
- * equality for existing scope ids.
- */
-export function clearScopeIdInternPool(): void {
-  INTERN_POOL.clear();
-}
-
-/** Internal: shared intern pool (process-local). */
-const INTERN_POOL = new Map<string, string>();

gitnexus-shared/src/scope-resolution/scope-tree.ts

@@ -1,295 +0,0 @@
-/**
- * `ScopeTree` — the lexical-scope spine of the `SemanticModel`
- * (RFC §2.2 + §3.1; Ring 2 SHARED #912).
- *
- * Generalizes the `enclosingFunctions` pattern from closed PR #902 to
- * arbitrary `ScopeKind`s. Owns the (parent ↔ children) relationship
- * derived from each `Scope.parent` pointer, and validates the structural
- * invariants a well-formed scope tree must satisfy.
- *
- * Invariants enforced at build time (throw on violation):
- *
- *   - Every non-`Module` scope has a non-null parent.
- *   - Every parent pointer references a scope that was also supplied to
- *     `buildScopeTree`.
- *   - Parent range **strictly contains** child range.
- *   - Sibling ranges under the same parent do not overlap.
- *   - Parent and child live in the same `filePath`. (Cross-file parent
- *     pointers would be a category error — a `File` scope is not the
- *     parent of another file's scopes; imports do that job.)
- *
- * Satisfies the `ScopeLookup` contract (defined in `./types.js`), so
- * `resolveTypeRef` (#916) and the scope-aware registries (#917) can take a
- * `ScopeTree` directly without adapters.
- *
- * Immutable surface: `byId` is a `ReadonlyMap`; children arrays are
- * `Object.freeze`d; miss lookups return a shared frozen empty array.
- */
-
-import type { Scope, ScopeId, ScopeLookup, Range } from './types.js';
-
-// ─── Public contract ────────────────────────────────────────────────────────
-
-export interface ScopeTree extends ScopeLookup {
-  readonly size: number;
-  readonly byId: ReadonlyMap<ScopeId, Scope>;
-
-  getScope(id: ScopeId): Scope | undefined;
-  getParent(id: ScopeId): Scope | undefined;
-  /** Child `ScopeId`s of `id`, in input order. Frozen empty array on miss. */
-  getChildren(id: ScopeId): readonly ScopeId[];
-  /**
-   * Ancestor chain from the immediate parent up to (and including) the
-   * root module scope. Excludes the starting scope itself. Frozen empty
-   * array on miss / for a root scope.
-   */
-  getAncestors(id: ScopeId): readonly ScopeId[];
-  has(id: ScopeId): boolean;
-}
-
-// ─── Build errors ───────────────────────────────────────────────────────────
-
-/**
- * Thrown by `buildScopeTree` when the input violates a structural
- * invariant. Carries the offending ids + the invariant name so failed
- * extraction pipelines can report actionable diagnostics.
- */
-export class ScopeTreeInvariantError extends Error {
-  constructor(
-    readonly invariant:
-      | 'non-module-requires-parent'
-      | 'parent-not-found'
-      | 'parent-must-contain-child'
-      | 'sibling-ranges-overlap'
-      | 'parent-must-share-filepath'
-      | 'duplicate-scope-id',
-    message: string,
-  ) {
-    super(message);
-    this.name = 'ScopeTreeInvariantError';
-  }
-}
-
-// ─── Builder ───────────────────────────────────────────────────────────────
-
-/**
- * Build an immutable `ScopeTree` from a flat list of `Scope` records.
- *
- * Throws `ScopeTreeInvariantError` on the first invariant violation; a
- * malformed tree is a bug in the extraction pipeline, not a data case for
- * consumers to handle, so fail-fast is the correct posture.
- */
-export function buildScopeTree(scopes: readonly Scope[]): ScopeTree {
-  const byId = new Map<ScopeId, Scope>();
-  const childrenById = new Map<ScopeId, ScopeId[]>();
-
-  // ── Pass 1: collect by id + duplicate check ───────────────────────────
-  for (const scope of scopes) {
-    if (byId.has(scope.id)) {
-      throw new ScopeTreeInvariantError(
-        'duplicate-scope-id',
-        `Two scopes share id '${scope.id}'. Scope ids must be unique per tree.`,
-      );
-    }
-    byId.set(scope.id, scope);
-  }
-
-  // ── Pass 2: validate parent pointers + build children buckets ─────────
-  for (const scope of scopes) {
-    if (scope.parent === null) {
-      if (scope.kind !== 'Module') {
-        throw new ScopeTreeInvariantError(
-          'non-module-requires-parent',
-          `Scope '${scope.id}' has kind '${scope.kind}' but no parent. Only 'Module' scopes may be root-level.`,
-        );
-      }
-      continue;
-    }
-
-    const parent = byId.get(scope.parent);
-    if (parent === undefined) {
-      throw new ScopeTreeInvariantError(
-        'parent-not-found',
-        `Scope '${scope.id}' references parent '${scope.parent}' which is not part of this tree.`,
-      );
-    }
-    if (parent.filePath !== scope.filePath) {
-      throw new ScopeTreeInvariantError(
-        'parent-must-share-filepath',
-        `Scope '${scope.id}' (${scope.filePath}) has parent '${parent.id}' in a different file (${parent.filePath}). Parent/child scopes must share filePath.`,
-      );
-    }
-    if (!canParentScope(parent.range, scope.range, parent.kind, scope.kind)) {
-      throw new ScopeTreeInvariantError(
-        'parent-must-contain-child',
-        `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not contain child '${scope.id}' at ${formatRange(scope.range)} (allowed: strict containment, or equal-range Module-as-parent).`,
-      );
-    }
-
-    let bucket = childrenById.get(parent.id);
-    if (bucket === undefined) {
-      bucket = [];
-      childrenById.set(parent.id, bucket);
-    }
-    bucket.push(scope.id);
-  }
-
-  // ── Pass 3: sibling-overlap check ─────────────────────────────────────
-  for (const [parentId, childIds] of childrenById) {
-    if (childIds.length < 2) continue;
-    // Sort siblings by (startLine, startCol) for an O(n log n) pairwise
-    // scan instead of O(n²) all-pairs.
-    const children = childIds.map((id) => byId.get(id)!).slice();
-    children.sort((a, b) => comparePosition(a.range, b.range));
-    for (let i = 1; i < children.length; i++) {
-      const prev = children[i - 1]!;
-      const curr = children[i]!;
-      if (rangesOverlap(prev.range, curr.range)) {
-        throw new ScopeTreeInvariantError(
-          'sibling-ranges-overlap',
-          `Sibling scopes under parent '${parentId}' overlap: '${prev.id}' ${formatRange(prev.range)} and '${curr.id}' ${formatRange(curr.range)}.`,
-        );
-      }
-    }
-  }
-
-  // Freeze children arrays so the surface is truly read-only.
-  const frozenChildren = new Map<ScopeId, readonly ScopeId[]>();
-  for (const [parentId, childIds] of childrenById) {
-    frozenChildren.set(parentId, Object.freeze(childIds.slice()));
-  }
-
-  return freezeTree(byId, frozenChildren);
-}
-
-// ─── Internals ──────────────────────────────────────────────────────────────
-
-const EMPTY_CHILDREN: readonly ScopeId[] = Object.freeze([]);
-
-function freezeTree(
-  byId: Map<ScopeId, Scope>,
-  childrenById: Map<ScopeId, readonly ScopeId[]>,
-): ScopeTree {
-  return {
-    byId,
-    get size() {
-      return byId.size;
-    },
-    getScope(id: ScopeId): Scope | undefined {
-      return byId.get(id);
-    },
-    getParent(id: ScopeId): Scope | undefined {
-      const scope = byId.get(id);
-      if (scope === undefined || scope.parent === null) return undefined;
-      return byId.get(scope.parent);
-    },
-    getChildren(id: ScopeId): readonly ScopeId[] {
-      return childrenById.get(id) ?? EMPTY_CHILDREN;
-    },
-    getAncestors(id: ScopeId): readonly ScopeId[] {
-      const start = byId.get(id);
-      if (start === undefined || start.parent === null) return EMPTY_CHILDREN;
-      const out: ScopeId[] = [];
-      const visited = new Set<ScopeId>([id]);
-      let cursor: ScopeId | null = start.parent;
-      while (cursor !== null && !visited.has(cursor)) {
-        visited.add(cursor);
-        out.push(cursor);
-        const next = byId.get(cursor);
-        cursor = next === undefined ? null : next.parent;
-      }
-      return Object.freeze(out);
-    },
-    has(id: ScopeId): boolean {
-      return byId.has(id);
-    },
-  };
-}
-
-/**
- * `outer` strictly contains `inner` when `outer`'s start is at or before
- * `inner`'s start, `outer`'s end is at or after `inner`'s end, and they are
- * not the exact same range. Equal ranges are rejected — a child cannot
- * occupy the exact same span as its parent.
- */
-function rangeStrictlyContains(outer: Range, inner: Range): boolean {
-  if (
-    outer.startLine === inner.startLine &&
-    outer.startCol === inner.startCol &&
-    outer.endLine === inner.endLine &&
-    outer.endCol === inner.endCol
-  ) {
-    return false;
-  }
-  const outerStartsAtOrBefore =
-    outer.startLine < inner.startLine ||
-    (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
-  const outerEndsAtOrAfter =
-    outer.endLine > inner.endLine ||
-    (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
-  return outerStartsAtOrBefore && outerEndsAtOrAfter;
-}
-
-function rangesEqual(a: Range, b: Range): boolean {
-  return (
-    a.startLine === b.startLine &&
-    a.startCol === b.startCol &&
-    a.endLine === b.endLine &&
-    a.endCol === b.endCol
-  );
-}
-
-/**
- * Whether `outer` (kind `outerKind`) is a valid parent for `inner` (kind
- * `innerKind`).
- *
- * Strict containment is the general rule. The single carve-out is the
- * `Module`/non-`Module` pair whose ranges are exactly equal — this happens
- * naturally when tree-sitter reports identical byte spans for the
- * `compilation_unit` (or equivalent file-root construct) and the file's
- * single top-level scope. Common shape: a C# file consisting of nothing
- * but `namespace X { ... }` with no leading or trailing trivia outside the
- * namespace's `{}` body — `compilation_unit` and `namespace_declaration`
- * both span exactly the same byte range. The `Module` is the universal
- * outer of any file-level scope by language semantics, so coincident
- * ranges should not break the parent chain.
- *
- * The carve-out is direction-asymmetric: only `Module`-as-outer parents a
- * same-range non-`Module`, never the reverse. This preserves the
- * acyclicity buildScopeTree relies on, and matches the corresponding
- * helper in `scope-extractor.ts` so `pass1BuildScopes` and the validator
- * agree on what a well-formed parent edge looks like.
- */
-export function canParentScope(
-  outer: Range,
-  inner: Range,
-  outerKind: Scope['kind'],
-  innerKind: Scope['kind'],
-): boolean {
-  if (rangeStrictlyContains(outer, inner)) return true;
-  if (outerKind === 'Module' && innerKind !== 'Module' && rangesEqual(outer, inner)) return true;
-  return false;
-}
-
-/**
- * Two ranges overlap when neither finishes before the other begins. Ranges
- * that merely touch at a single boundary point (`a.end === b.start`) do
- * NOT overlap — this matches tree-sitter's half-open-like range semantics
- * and the typical "sibling blocks meet but don't overlap" pattern.
- */
-function rangesOverlap(a: Range, b: Range): boolean {
-  const aEndsBeforeB =
-    a.endLine < b.startLine || (a.endLine === b.startLine && a.endCol <= b.startCol);
-  const bEndsBeforeA =
-    b.endLine < a.startLine || (b.endLine === a.startLine && b.endCol <= a.startCol);
-  return !(aEndsBeforeB || bEndsBeforeA);
-}
-
-function comparePosition(a: Range, b: Range): number {
-  if (a.startLine !== b.startLine) return a.startLine - b.startLine;
-  return a.startCol - b.startCol;
-}
-
-function formatRange(r: Range): string {
-  return `${r.startLine}:${r.startCol}-${r.endLine}:${r.endCol}`;
-}