fix(group): drop macro-style #include from consumer contracts

Tree-sitter's `(_) @import.source` wildcard matches the identifier node of `#include PLATFORM_HEADER`, so the cleaned value `PLATFORM_HEADER` slipped past the system-header / `..` filters and was emitted as a permanently orphaned consumer contract (no file is named after a macro identifier, so no provider can ever match). Add a shape guard that skips cleaned values lacking both a path separator and an extension dot, plus regression tests for single and multi-macro files. Also document `IncludeExtractor.canExtract()` as unused by sync.ts (gated via `config.detect.includes` instead) and kept solely for ContractExtractor interface uniformity. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
merge: bring fix/windows-lbug-lock-retry (PR #1430 ) — closes Windows lbug lock flakes on cli-e2e
2026-05-09 06:49:18 +01:00 · 2026-05-08 15:24:12 +01:00 · 2026-05-08 15:22:19 +01:00 · 2026-05-08 13:44:49 +01:00 · 2026-05-08 13:32:58 +01:00 · 2026-05-08 13:07:21 +01:00
1948 changed files with 35198 additions and 1609898 deletions
@@ -11,7 +11,7 @@
  "plugins": [
    {
      "name": "gitnexus",
-      "version": "1.6.8",
+      "version": "1.3.3",
      "source": "./gitnexus-claude-plugin",
      "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase."
    }
@@ -1,43 +0,0 @@
-# GitNexus PR Reviewer Swarm — Claude Code adapter
-
-This is the **Claude Code** entrypoint for the cross-CLI GitNexus PR reviewer swarm. The
-review logic itself is CLI-neutral and lives in **[`pr-swarm-review/`](../pr-swarm-review/README.md)**
-— that README is the canonical guide and covers every CLI (Claude Code, Gemini, Copilot,
-Cursor, Codex, and any AGENTS.md-aware agent).
-
-## Invocation (Claude Code)
-
-```
-/gitnexus-pr-swarm-review <PR URL or PR number>
-```
-
-Runs in **Swarm mode**: the coordinator skill dispatches the seven `gitnexus-*` subagents in
-parallel (lanes 1–2 first, 3–6 in parallel, lane 7 last as a hard gate).
-
-## Files in this adapter
-
-| File | Role |
-|------|------|
-| `.claude/skills/gitnexus-pr-swarm-review/SKILL.md` | Coordinator — runs Swarm mode per `pr-swarm-review/orchestration.md` |
-| `.claude/agents/gitnexus-*.md` | Seven thin subagent wrappers; each reads its canonical persona in `pr-swarm-review/personas/` |
-
-Each subagent keeps valid Claude Code frontmatter (model, tools, etc.); the mechanical
-verifier lanes (`test-ci-verifier`, `branch-hygiene-reviewer`) run on Haiku, the analytical
-lanes on Sonnet.
-
-## Key properties
-
- **Read-only.** Tools limited to Read/Grep/Glob/Bash, and every persona enforces an
-  explicit permitted/prohibited Bash list. No agent edits files, commits, or posts.
- **Evidence-grounded**; **missing visibility becomes verification work**; **manually invoked.**
-
-## Editing
-
-Edit review behavior in the canonical files under `pr-swarm-review/` (orchestration +
-personas), **not** in these wrappers. After adding or editing files in `.claude/agents/`,
-restart Claude Code so it reloads the agent definitions.
-
-## Relationship to `/gitnexus-pr-review`
-
-Coexists with the single-agent `/gitnexus-pr-review` skill (a linear checklist using GitNexus
-MCP tools). This swarm is the multi-persona deep production-readiness review.
@@ -1,24 +0,0 @@
---
-name: gitnexus-branch-hygiene-reviewer
-description: "GitNexus branch hygiene and mergeability reviewer. Use to classify merge state, conflicts, stale branches, merge-from-main commits, unrelated churn, mixed domains, and whether rebase or split is required."
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
-model: claude-haiku-4-5-20251001
-maxTurns: 30
---
-
-# GitNexus Branch Hygiene & Mergeability Reviewer
-
-Your complete operating spec — role, what to inspect, classifications, and the required output sections — lives in the canonical, CLI-neutral persona file:
-
-**`pr-swarm-review/personas/02-branch-hygiene-reviewer.md`**
-
-Read that file now with the Read tool and follow it exactly. It is the single source of truth shared across all AI CLIs; this subagent only adapts it to Claude Code. The orchestration contract (lane order, Swarm vs Solo execution, output structure) is in `pr-swarm-review/orchestration.md`.
-
-## Rules (always enforced)
-
- **Do not edit files.** You are read-only.
- **Bash is read-only.** Permitted: `git log`, `git diff`, `git show`, `git grep`, `git ls-files`, `gh pr view`, `gh pr diff`, `gh pr checks`, `gh issue view`, and inspection tools (`grep`, `cat`, `find`, `ls`). Prohibited: any command that writes files, modifies git state (`git commit`, `git add`, `git checkout -- <path>`), posts to GitHub (`gh pr comment`, `gh pr review`, `gh issue comment`), installs packages, or runs arbitrary scripts.
@@ -1,24 +0,0 @@
---
-name: gitnexus-docs-dod-reviewer
-description: "GitNexus docs and Definition-of-Done reviewer. Use to translate repo guidance, linked issues, changed domains, docs requirements, release notes, and acceptance criteria into a PR-specific DoD."
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
-model: claude-sonnet-4-6
-maxTurns: 30
---
-
-# GitNexus Docs & Definition-of-Done Reviewer
-
-Your complete operating spec — role, what to inspect, classifications, and the required output sections — lives in the canonical, CLI-neutral persona file:
-
-**`pr-swarm-review/personas/06-docs-dod-reviewer.md`**
-
-Read that file now with the Read tool and follow it exactly. It is the single source of truth shared across all AI CLIs; this subagent only adapts it to Claude Code. The orchestration contract (lane order, Swarm vs Solo execution, output structure) is in `pr-swarm-review/orchestration.md`.
-
-## Rules (always enforced)
-
- **Do not edit files.** You are read-only.
- **Bash is read-only.** Permitted: `git log`, `git diff`, `git show`, `git grep`, `git ls-files`, `gh pr view`, `gh pr diff`, `gh pr checks`, `gh issue view`, and inspection tools (`grep`, `cat`, `find`, `ls`). Prohibited: any command that writes files, modifies git state (`git commit`, `git add`, `git checkout -- <path>`), posts to GitHub (`gh pr comment`, `gh pr review`, `gh issue comment`), installs packages, or runs arbitrary scripts.
@@ -1,24 +0,0 @@
---
-name: gitnexus-pr-facts-historian
-description: "GitNexus PR facts and repository-history investigator. Use to gather PR identity, visible GitHub state, changed files, commits, linked issues, related PRs, historical fixes, regressions, stale follow-ups, and missing visibility."
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
-model: claude-sonnet-4-6
-maxTurns: 40
---
-
-# GitNexus PR Facts & Repository-History Investigator
-
-Your complete operating spec — role, what to inspect, classifications, and the required output sections — lives in the canonical, CLI-neutral persona file:
-
-**`pr-swarm-review/personas/01-pr-facts-historian.md`**
-
-Read that file now with the Read tool and follow it exactly. It is the single source of truth shared across all AI CLIs; this subagent only adapts it to Claude Code. The orchestration contract (lane order, Swarm vs Solo execution, output structure) is in `pr-swarm-review/orchestration.md`.
-
-## Rules (always enforced)
-
- **Do not edit files.** You are read-only.
- **Bash is read-only.** Permitted: `git log`, `git diff`, `git show`, `git grep`, `git ls-files`, `gh pr view`, `gh pr diff`, `gh pr checks`, `gh issue view`, and inspection tools (`grep`, `cat`, `find`, `ls`). Prohibited: any command that writes files, modifies git state (`git commit`, `git add`, `git checkout -- <path>`), posts to GitHub (`gh pr comment`, `gh pr review`, `gh issue comment`), installs packages, or runs arbitrary scripts.
@@ -1,24 +0,0 @@
---
-name: gitnexus-risk-architect
-description: "GitNexus production-risk reviewer. Use for risk-model-first review of changed files, runtime behavior, multi-domain changes, user impact, failure modes, compatibility, and merge-blocking risk."
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
-model: claude-sonnet-4-6
-maxTurns: 40
---
-
-# GitNexus Production-Risk Architect
-
-Your complete operating spec — role, what to inspect, classifications, and the required output sections — lives in the canonical, CLI-neutral persona file:
-
-**`pr-swarm-review/personas/03-risk-architect.md`**
-
-Read that file now with the Read tool and follow it exactly. It is the single source of truth shared across all AI CLIs; this subagent only adapts it to Claude Code. The orchestration contract (lane order, Swarm vs Solo execution, output structure) is in `pr-swarm-review/orchestration.md`.
-
-## Rules (always enforced)
-
- **Do not edit files.** You are read-only.
- **Bash is read-only.** Permitted: `git log`, `git diff`, `git show`, `git grep`, `git ls-files`, `gh pr view`, `gh pr diff`, `gh pr checks`, `gh issue view`, and inspection tools (`grep`, `cat`, `find`, `ls`). Prohibited: any command that writes files, modifies git state (`git commit`, `git add`, `git checkout -- <path>`), posts to GitHub (`gh pr comment`, `gh pr review`, `gh issue comment`), installs packages, or runs arbitrary scripts.
@@ -1,24 +0,0 @@
---
-name: gitnexus-security-boundary-reviewer
-description: "GitNexus security and trust-boundary reviewer. Use for auth, permissions, secrets, injection, unsafe parsing, external input handling, hidden Unicode, YAML/Docker/workflow risks, and suspicious non-ASCII hygiene."
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
-model: claude-sonnet-4-6
-maxTurns: 35
---
-
-# GitNexus Security & Trust-Boundary Reviewer
-
-Your complete operating spec — role, what to inspect, classifications, and the required output sections — lives in the canonical, CLI-neutral persona file:
-
-**`pr-swarm-review/personas/05-security-boundary-reviewer.md`**
-
-Read that file now with the Read tool and follow it exactly. It is the single source of truth shared across all AI CLIs; this subagent only adapts it to Claude Code. The orchestration contract (lane order, Swarm vs Solo execution, output structure) is in `pr-swarm-review/orchestration.md`.
-
-## Rules (always enforced)
-
- **Do not edit files.** You are read-only.
- **Bash is read-only.** Permitted: `git log`, `git diff`, `git show`, `git grep`, `git ls-files`, `gh pr view`, `gh pr diff`, `gh pr checks`, `gh issue view`, and inspection tools (`grep`, `cat`, `find`, `ls`). Prohibited: any command that writes files, modifies git state (`git commit`, `git add`, `git checkout -- <path>`), posts to GitHub (`gh pr comment`, `gh pr review`, `gh issue comment`), installs packages, or runs arbitrary scripts.
@@ -1,24 +0,0 @@
---
-name: gitnexus-synthesis-critic
-description: "GitNexus final review synthesis critic. Use to check whether the final PR review is evidence-grounded, risk-prioritized, GitNexus-specific, non-generic, and follows required verdict rules."
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
-model: claude-sonnet-4-6
-maxTurns: 25
---
-
-# GitNexus Final-Review Synthesis Critic
-
-Your complete operating spec — role, what to inspect, classifications, and the required output sections — lives in the canonical, CLI-neutral persona file:
-
-**`pr-swarm-review/personas/07-synthesis-critic.md`**
-
-Read that file now with the Read tool and follow it exactly. It is the single source of truth shared across all AI CLIs; this subagent only adapts it to Claude Code. The orchestration contract (lane order, Swarm vs Solo execution, output structure) is in `pr-swarm-review/orchestration.md`.
-
-## Rules (always enforced)
-
- **Do not edit files.** You are read-only.
- **Bash is read-only.** Permitted: `git log`, `git diff`, `git show`, `git grep`, `git ls-files`, `gh pr view`, `gh pr diff`, `gh pr checks`, `gh issue view`, and inspection tools (`grep`, `cat`, `find`, `ls`). Prohibited: any command that writes files, modifies git state (`git commit`, `git add`, `git checkout -- <path>`), posts to GitHub (`gh pr comment`, `gh pr review`, `gh issue comment`), installs packages, or runs arbitrary scripts.
@@ -1,24 +0,0 @@
---
-name: gitnexus-test-ci-verifier
-description: "GitNexus test and CI reviewer. Use to verify whether changed behavior is covered by targeted tests, whether CI actually runs those tests, and whether workflow changes weaken validation."
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Bash
-model: claude-haiku-4-5-20251001
-maxTurns: 35
---
-
-# GitNexus Test & CI Verifier
-
-Your complete operating spec — role, what to inspect, classifications, and the required output sections — lives in the canonical, CLI-neutral persona file:
-
-**`pr-swarm-review/personas/04-test-ci-verifier.md`**
-
-Read that file now with the Read tool and follow it exactly. It is the single source of truth shared across all AI CLIs; this subagent only adapts it to Claude Code. The orchestration contract (lane order, Swarm vs Solo execution, output structure) is in `pr-swarm-review/orchestration.md`.
-
-## Rules (always enforced)
-
- **Do not edit files.** You are read-only.
- **Bash is read-only.** Permitted: `git log`, `git diff`, `git show`, `git grep`, `git ls-files`, `gh pr view`, `gh pr diff`, `gh pr checks`, `gh issue view`, and inspection tools (`grep`, `cat`, `find`, `ls`). Prohibited: any command that writes files, modifies git state (`git commit`, `git add`, `git checkout -- <path>`), posts to GitHub (`gh pr comment`, `gh pr review`, `gh issue comment`), installs packages, or runs arbitrary scripts.
@@ -1,31 +0,0 @@
---
-name: gitnexus-pr-swarm-review
-description: "Run a GitNexus production-readiness pull request review using a coordinated reviewer swarm."
---
-
-# GitNexus PR Swarm Review (Claude Code adapter)
-
-Use this skill to review a GitNexus pull request and produce a production-readiness review.
-
-```
-/gitnexus-pr-swarm-review <PR URL or PR number>
-```
-
-You are the **swarm coordinator**. The full review contract — lanes, dependencies,
-classifications, output structure, finding format, hidden-Unicode checks, and behavior
-rules — is the canonical, CLI-neutral spec:
-
-**`pr-swarm-review/orchestration.md`** — read it now and follow it.
-
-This adapter only pins the Claude Code specifics:
-
- **Run in Swarm mode.** Dispatch each lane as its own subagent via the Agent tool. The
-  seven subagents are the project agents named `gitnexus-*` (one per persona); each reads
-  its canonical persona under `pr-swarm-review/personas/`. Run lanes 1–2 first, lanes 3–6
-  in parallel after, and lane 7 last on the draft.
- **Lane 7 is a hard gate.** Do not emit the final review while the synthesis critic's
-  "Required corrections before posting" section is non-empty — revise and re-run it.
- Stay **read-only**: investigate and report; never edit, commit, or post.
-
-Do not flatten the review into a generic checklist; delegate to the subagents and
-synthesize per `orchestration.md`.
@@ -5,32 +5,30 @@ description: "Use when the user needs to run GitNexus CLI commands like analyze/

 # GitNexus CLI Commands

-Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `npx`), so no package-manager assumption and no global install is required.
-
-> **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`) or use `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
+All commands work via `npx` — no global install required.

 ## Commands

 ### analyze — Build or refresh the index

 ```bash
-node .gitnexus/run.cjs analyze
+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)                                        |
+| `--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. 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.

 ### status — Check index freshness

 ```bash
-node .gitnexus/run.cjs status
+npx gitnexus status
 ```

 Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
@@ -38,7 +36,7 @@ Shows whether the current repo has a GitNexus index, when it was last updated, a
 ### clean — Delete the index

 ```bash
-node .gitnexus/run.cjs clean
+npx gitnexus clean
 ```

 Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
@@ -51,7 +49,7 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
 ### wiki — Generate documentation from the graph

 ```bash
-node .gitnexus/run.cjs wiki
+npx gitnexus wiki
 ```

 Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
@@ -68,7 +66,7 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 ### list — Show all indexed repos

 ```bash
-node .gitnexus/run.cjs list
+npx gitnexus list
 ```

 Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
@@ -16,23 +16,23 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 ## Workflow

 ```
-1. query({search_query: "<error or symptom>"})            → Find related execution flows
-2. context({name: "<suspect>"})                    → See callers/callees/processes
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
 ```

-> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.

 ## Checklist

 ```
 - [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
+- [ ] gitnexus_query for error text or related code
 - [ ] Identify the suspect function from returned processes
- [ ] context to see callers and callees
+- [ ] gitnexus_context to see callers and callees
 - [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
+- [ ] gitnexus_cypher for custom call chain traces if needed
 - [ ] Read source files to confirm root cause
 ```

@@ -40,58 +40,46 @@ description: "Use when the user is debugging a bug, tracing an error, or asking

 | Symptom              | GitNexus Approach                                          |
 | -------------------- | ---------------------------------------------------------- |
-| Error message        | `query` for error text → `context` on throw sites |
+| Error message        | `gitnexus_query` for error text → `context` on throw sites |
 | Wrong return value   | `context` on the function → trace callees for data flow    |
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
 | Recent regression    | `detect_changes` to see what your changes affect           |
-| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |

 ## Tools

-**query** — find code related to error:
+**gitnexus_query** — find code related to error:

 ```
-query({search_query: "payment validation error"})
+gitnexus_query({query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```

-**context** — full context for a suspect:
+**gitnexus_context** — full context for a suspect:

 ```
-context({name: "validatePayment"})
+gitnexus_context({name: "validatePayment"})
 → Incoming calls: processCheckout, webhookHandler
 → Outgoing calls: verifyCard, fetchRates (external API!)
 → Processes: CheckoutFlow (step 3/7)
 ```

-**cypher** — custom call chain traces:
+**gitnexus_cypher** — custom call chain traces:

 ```cypher
 MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
 RETURN [n IN nodes(path) | n.name] AS chain
 ```

-**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
-
-```
-trace({ from: "processCheckout", to: "fetchRates" })
-→ status: ok, hopCount: 3
-→ hops: processCheckout → validatePayment → verifyCard → fetchRates
-→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
-```
-
-When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
-
 ## Example: "Payment endpoint returns 500 intermittently"

 ```
-1. query({search_query: "payment error handling"})
+1. gitnexus_query({query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

-2. context({name: "validatePayment"})
+2. gitnexus_context({name: "validatePayment"})
   → Outgoing calls: verifyCard, fetchRates (external API!)

 3. READ gitnexus://repo/my-app/process/CheckoutFlow
@@ -18,20 +18,20 @@ description: "Use when the user asks how code works, wants to understand archite
 ```
 1. READ gitnexus://repos                          → Discover indexed repos
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({search_query: "<what you want to understand>"})  → Find related execution flows
-4. context({name: "<symbol>"})            → Deep dive on specific symbol
+3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
+4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```

-> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.

 ## Checklist

 ```
 - [ ] READ gitnexus://repo/{name}/context
- [ ] query for the concept you want to understand
+- [ ] gitnexus_query for the concept you want to understand
 - [ ] Review returned processes (execution flows)
- [ ] context on key symbols for callers/callees
+- [ ] gitnexus_context on key symbols for callers/callees
 - [ ] READ process resource for full execution traces
 - [ ] Read source files for implementation details
 ```
@@ -47,18 +47,18 @@ description: "Use when the user asks how code works, wants to understand archite

 ## Tools

-**query** — find execution flows related to a concept:
+**gitnexus_query** — find execution flows related to a concept:

 ```
-query({search_query: "payment processing"})
+gitnexus_query({query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```

-**context** — 360-degree view of a symbol:
+**gitnexus_context** — 360-degree view of a symbol:

 ```
-context({name: "validateUser"})
+gitnexus_context({name: "validateUser"})
 → Incoming calls: loginHandler, apiMiddleware
 → Outgoing calls: checkToken, getUserById
 → Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
@@ -68,10 +68,10 @@ context({name: "validateUser"})

 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. query({search_query: "payment processing"})
+2. gitnexus_query({query: "payment processing"})
   → CheckoutFlow: processPayment → validateCard → chargeStripe
   → RefundFlow: initiateRefund → calculateRefund → processRefund
-3. context({name: "processPayment"})
+3. gitnexus_context({name: "processPayment"})
   → Incoming: checkoutHandler, webhookHandler
   → Outgoing: validateCard, chargeStripe, saveTransaction
 4. Read src/payments/processor.ts for implementation details
@@ -15,7 +15,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**

-> If step 1 warns the index is stale, run `node .gitnexus/run.cjs analyze` in the terminal first.
+> If step 1 warns the index is stale, run `npx gitnexus analyze` in the terminal first.

 ## Skills

@@ -35,74 +35,10 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `query`          | Process-grouped code intelligence — execution flows related to a concept |
 | `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
 | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
-| `trace`          | Shortest path between two symbols — "how does A reach B?" in one call     |
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
-| `explain`        | Persisted taint findings — source→sink data flows (needs `analyze --pdg`) |
-| `pdg_query`      | Control/data dependence — what gates X (CDG) / where Y flows (REACHING_DEF); needs `analyze --pdg` |
-| `check`          | Check graph invariants such as circular imports                          |
-| `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                    |
-
-### Paginating `list_repos`
-
-`list_repos` is paginated so a large registry is not truncated by MCP/LLM token limits. It takes optional `limit` (default **50**, max **200**) and `offset`, and returns:
-
-```jsonc
-{
-  "repositories": [
-    { "name": "...", "path": "...", "indexedAt": "...", "lastCommit": "...", "stats": { } }
-  ],
-  "pagination": {
-    "total": 437,
-    "limit": 50,
-    "offset": 0,
-    "returned": 50,
-    "hasMore": true,
-    "nextOffset": 50
-  }
-}
-```
-
-To enumerate **every** repository, keep calling with `offset` set to `pagination.nextOffset` until `hasMore` is `false`:
-
-```text
-list_repos {}               → repos 1–50,    nextOffset 50,  hasMore true
-list_repos { offset: 50 }   → repos 51–100,  nextOffset 100, hasMore true
-…
-list_repos { offset: 400 }  → repos 401–437,                 hasMore false   (done)
-```
-
-Notes: `offset` ≥ `total` returns an empty page (with `total` still reported). Out-of-range or malformed `limit`/`offset` (non-integer, `limit` outside `[1, 200]`, `offset < 0`) are rejected with a clear error — `limit` above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.
-
-### Taint findings (`explain`)
-
-`explain` returns intra-procedural taint findings (`TAINTED` edges) recorded by `gitnexus analyze --pdg` — each with a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.
-
- `explain {}` — enumerate all findings for the repo (bounded by `limit`, deterministic order)
- `explain { target: "src/vuln.ts" }` — findings in a file (suffix path match accepted)
- `explain { target: "runUserCommand" }` — findings in a function (resolved like `context`; ambiguous names return ranked candidates)
-
-A repo indexed without `--pdg` returns a clear "no taint layer" note. Caveats: findings are intra-procedural only — cross-function, closure/callback, property/field, and implicit flows are not modeled, so the absence of a finding is **not** proof of safety. `SANITIZES` (sanitizer-kill) edges are queryable via `cypher`.
-
-### Control & data dependence (`pdg_query`)
-
-`pdg_query` reads the control/data-dependence layers `gitnexus analyze --pdg` records (CDG + REACHING_DEF, basic-block granular) — the control/data analog of `explain`. It is **always anchored** (a `target` file path or symbol, resolved like `context`) and has two modes:
-
- `pdg_query { mode: "controls", target: "..." }` — CDG: "under what condition does X run?". Each edge is a controlling predicate block → dependent block with the branch sense (`'T'`/`'F'`) in `reason`; an edge into an early `return`/`throw` is flagged `guard: true` (guard-clause discovery — the sense depends on the predicate, so don't filter guards by a fixed label).
- `pdg_query { mode: "flows", target: "...", variable?: "..." }` — REACHING_DEF def→use edges within the function; pass `variable` to trace one binding.
-
-A repo indexed without `--pdg` returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra-procedural only — cross-function flow is taint's domain (`explain`). The raw CDG/REACHING_DEF edges are also queryable via `cypher`. See the `gitnexus-pdg-query` skill for the full query surface.
-
-### Shortest path between two symbols (`trace`)
-
-`trace` answers "how does A reach B?" in one call — the shortest directed path over `CALLS` (plus `HAS_METHOD`, so a class-rooted trace descends into its methods) instead of chaining 3–8 `context`/`impact` hops by hand.
-
- `trace { from: "validateUser", to: "executeQuery" }` — shortest path between two symbols.
- Disambiguate common names with `from_uid`/`to_uid` (zero-ambiguity) or `from_file`/`to_file`; an ambiguous name returns ranked candidates.
- `maxDepth` (default 10, max 30) bounds the search; `includeTests` (default false) lets the traversal pass through test-file symbols.
-
-Returns ordered `hops` (each `{ name, filePath, startLine }`) and an aligned `edges[]` of `{ relType, confidence }`, so call hops and containment (`HAS_METHOD`) hops stay distinguishable. When no path exists it reports the **furthest** reachable node (where the chain breaks) and sets `truncated: true` if a traversal cap was hit first. Every result carries a `status`: `ok` / `no_path` / `ambiguous` / `not_found` / `error`.
+| `list_repos`     | Discover indexed repos                                                   |

 ## Resources Reference

@@ -17,22 +17,22 @@ description: "Use when the user wants to know what will break if they change som
 ## Workflow

 ```
-1. impact({target: "X", direction: "upstream"})  → What depends on this
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
 2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
-3. detect_changes()                               → Map current git changes to affected flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
 4. Assess risk and report to user
 ```

-> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.

 ## Checklist

 ```
- [ ] impact({target, direction: "upstream"}) to find dependents
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
 - [ ] Review d=1 items first (these WILL BREAK)
 - [ ] Check high-confidence (>0.8) dependencies
 - [ ] READ processes to check affected execution flows
- [ ] detect_changes() for pre-commit check
+- [ ] gitnexus_detect_changes() for pre-commit check
 - [ ] Assess risk level and report to user
 ```

@@ -55,10 +55,10 @@ description: "Use when the user wants to know what will break if they change som

 ## Tools

-**impact** — the primary tool for symbol blast radius:
+**gitnexus_impact** — the primary tool for symbol blast radius:

 ```
-impact({
+gitnexus_impact({
  target: "validateUser",
  direction: "upstream",
  minConfidence: 0.8,
@@ -73,10 +73,10 @@ impact({
  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
 ```

-**detect_changes** — git-diff based impact analysis:
+**gitnexus_detect_changes** — git-diff based impact analysis:

 ```
-detect_changes({scope: "staged"})
+gitnexus_detect_changes({scope: "staged"})

 → Changed: 5 symbols in 3 files
 → Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
@@ -86,7 +86,7 @@ detect_changes({scope: "staged"})
 ## Example: "What breaks if I change validateUser?"

 ```
-1. impact({target: "validateUser", direction: "upstream"})
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
   → d=1: loginHandler, apiMiddleware (WILL BREAK)
   → d=2: authRouter, sessionManager (LIKELY AFFECTED)

@@ -1,89 +0,0 @@
---
-name: gitnexus-pdg-query
-description: "Use when querying or extending GitNexus's PDG control/data-dependence surface (the `pdg_query` MCP tool, CDG/REACHING_DEF edges), or reasoning about \"what controls X\" / \"where does Y flow\" / guard clauses. Examples: \"what guards this statement?\", \"trace this variable within the function\", \"why is the pdg_query result empty?\", \"add a CDG query\"."
---
-
-# PDG query surface with GitNexus
-
-Expert knowledge for the `pdg_query` MCP tool and the control/data-dependence
-edges it reads — the opt-in `--pdg` program-dependence layers. Read this before
-touching `gitnexus/src/mcp/local/local-backend.ts` (`_pdgQueryImpl`) or the
-`pdg_query` tool def, or when explaining a `pdg_query` result.
-
-## When to Use
-
- "Under what condition does this statement run?" (guarding predicates).
- "Where does this variable flow inside the function?" (def→use).
- Guard-clause discovery (early-return guards — subsumes the #559 heuristic).
- Extending or reviewing `pdg_query` / the CDG / REACHING_DEF read path.
- Debugging an empty or surprising `pdg_query` result.
-
-## The layered substrate (build order)
-
-`pdg_query` runs **on** the same graph taint runs on. Each layer is opt-in
-behind `--pdg`; a default `analyze` run records none of them (byte-identical).
-
-```
-L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
-L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
-L5  CDG            Ferrante control dependence (post-dominators)    (M5 #2085)
-```
-
-All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table
-(keyed by the `type` property). There is **no** `Function → BasicBlock` edge.
-
-## The two modes
-
- `pdg_query({ mode: 'controls', target })` — CDG. For the anchored function,
-  each edge: controlling predicate block → dependent block + branch sense in
-  `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An
-  edge into an early-return/throw block is flagged `guard: true`.
- `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use
-  edges; `variable` filters to one binding.
-
-`target` is **required** — a file path or a symbol/function name (resolved like
-`context()`). There is no anchorless mode (see below).
-
-## The corrected guard-clause Cypher
-
-The RFC #567 §2 form (`[:CDG {label:'F'}]`) does **not** run as written. Edges
-are values of the single `CodeRelation` table's `type` property, and the branch
-sense is in `reason`, NOT a `label` column:
-
-```cypher
-MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock)
-WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw'
-RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text
-```
-
-`r.reason` is the sense the predicate took to reach the early exit. For
-`if (!ok) return;` the return rides the predicate's **true** arm (`'T'`) and the
-protected body rides the **false** arm (`'F'`) — polarity depends on the guard,
-so don't hard-code one sense.
-
-## Gotchas (the load-bearing ones)
-
- **Always anchored + LIMIT-bounded.** LadybugDB has no rel-property index, so
-  an unanchored `[:CDG*]`/`[:REACHING_DEF*]` path scan is unbounded. `pdg_query`
-  requires `target` and bounds the page; raw `cypher` callers must anchor on a
-  file id-prefix or symbol span themselves.
- **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge:
-  the block is matched by its id-prefix (`BasicBlock:<file>:<fnStartLine>:…`)
-  plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based**
-  while the symbol node's `startLine`/`endLine` are **0-based**, so **both** bounds
-  are shifted `+1` (`[symStart+1, symEnd+1]`): the upper `+1` keeps a guard/def/use
-  on the function's **final line**, the lower `+1` excludes an adjacent function's
-  block on the line directly **above**. Same-line / nested functions anchor coarsely.
- **No PDG layer ⇒ a note, not an error.** If the repo wasn't indexed with
-  `--pdg` the tool returns `{ results: [], note: "no PDG layer …" }` (cheap meta
-  probe on `RepoMeta.pdg.maxCdgEdgesPerFunction` / `maxReachingDefEdgesPerFunction`).
- **CDG labels are binary in M5/M6.** Every `switch`-case arm is `'T'`; per-case
-  conditions are not yet distinguished.
- **Intra-procedural only.** Cross-function flow is taint's domain (`explain`).
-
-## Mirror, don't fork
-
-`_pdgQueryImpl` is the front half of `_explainImpl` (WAL wrapper, meta no-layer
-probe, limit validation, `resolveSymbolCandidates` anchoring) with CDG/
-REACHING_DEF instead of TAINTED — and none of taint's path-codec / interproc
-`TAINT_PATH` machinery. Reuse those shared helpers; do not re-implement them.
@@ -18,24 +18,24 @@ description: "Use when the user wants to review a pull request, understand what

 ```
 1. gh pr diff <number>                                    → Get the raw diff
-2. detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
 3. For each changed symbol:
-   impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
-4. context({name: "<key symbol>"})               → Understand callers/callees
+   gitnexus_impact({target: "<symbol>", direction: "upstream"})    → Blast radius per change
+4. gitnexus_context({name: "<key symbol>"})               → Understand callers/callees
 5. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
 6. Summarize findings with risk assessment
 ```

-> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal before reviewing.
+> If "Index is stale" → run `npx gitnexus analyze` in terminal before reviewing.

 ## Checklist

 ```
 - [ ] Fetch PR diff (gh pr diff or git diff base...head)
- [ ] detect_changes to map changes to affected execution flows
- [ ] impact on each non-trivial changed symbol
+- [ ] gitnexus_detect_changes to map changes to affected execution flows
+- [ ] gitnexus_impact on each non-trivial changed symbol
 - [ ] Review d=1 items (WILL BREAK) — are callers updated?
- [ ] context on key changed symbols to understand full picture
+- [ ] gitnexus_context on key changed symbols to understand full picture
 - [ ] Check if affected processes have test coverage
 - [ ] Assess overall risk level
 - [ ] Write review summary with findings
@@ -63,20 +63,20 @@ description: "Use when the user wants to review a pull request, understand what

 ## Tools

-**detect_changes** — map PR diff to affected execution flows:
+**gitnexus_detect_changes** — map PR diff to affected execution flows:

 ```
-detect_changes({scope: "compare", base_ref: "main"})
+gitnexus_detect_changes({scope: "compare", base_ref: "main"})

 → Changed: 8 symbols in 4 files
 → Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Risk: MEDIUM
 ```

-**impact** — blast radius per changed symbol:
+**gitnexus_impact** — blast radius per changed symbol:

 ```
-impact({target: "validatePayment", direction: "upstream"})
+gitnexus_impact({target: "validatePayment", direction: "upstream"})

 → d=1 (WILL BREAK):
  - processCheckout (src/checkout.ts:42) [CALLS, 100%]
@@ -86,20 +86,20 @@ impact({target: "validatePayment", direction: "upstream"})
  - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
 ```

-**impact with tests** — check test coverage:
+**gitnexus_impact with tests** — check test coverage:

 ```
-impact({target: "validatePayment", direction: "upstream", includeTests: true})
+gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})

 → Tests that cover this symbol:
  - validatePayment.test.ts [direct]
  - checkout.integration.test.ts [via processCheckout]
 ```

-**context** — understand a changed symbol's role:
+**gitnexus_context** — understand a changed symbol's role:

 ```
-context({name: "validatePayment"})
+gitnexus_context({name: "validatePayment"})

 → Incoming calls: processCheckout, webhookHandler
 → Outgoing calls: verifyCard, fetchRates
@@ -112,20 +112,20 @@ context({name: "validatePayment"})
 1. gh pr diff 42 > /tmp/pr42.diff
   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts

-2. detect_changes({scope: "compare", base_ref: "main"})
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
   → Changed symbols: validatePayment, PaymentInput, formatAmount
   → Affected processes: CheckoutFlow, RefundFlow
   → Risk: MEDIUM

-3. impact({target: "validatePayment", direction: "upstream"})
+3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
   → d=1: processCheckout, webhookHandler (WILL BREAK)
   → webhookHandler is NOT in the PR diff — potential breakage!

-4. impact({target: "PaymentInput", direction: "upstream"})
+4. gitnexus_impact({target: "PaymentInput", direction: "upstream"})
   → d=1: validatePayment (in PR), createPayment (NOT in PR)
   → createPayment uses the old PaymentInput shape — breaking change!

-5. context({name: "formatAmount"})
+5. gitnexus_context({name: "formatAmount"})
   → Called by 12 functions — but change is backwards-compatible (added optional param)

 6. Review summary:
@@ -16,78 +16,78 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 ## Workflow

 ```
-1. impact({target: "X", direction: "upstream"})  → Map all dependents
-2. query({search_query: "X"})                            → Find execution flows involving X
-3. context({name: "X"})                           → See all incoming/outgoing refs
+1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
+2. gitnexus_query({query: "X"})                            → Find execution flows involving X
+3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```

-> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.

 ## Checklists

 ### Rename Symbol

 ```
- [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
+- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
 - [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
- [ ] If satisfied: rename({..., dry_run: false}) — apply edits
- [ ] detect_changes() — verify only expected files changed
+- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
 - [ ] Run tests for affected processes
 ```

 ### Extract Module

 ```
- [ ] context({name: target}) — see all incoming/outgoing refs
- [ ] impact({target, direction: "upstream"}) — find all external callers
+- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
+- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
 - [ ] Define new module interface
 - [ ] Extract code, update imports
- [ ] detect_changes() — verify affected scope
+- [ ] gitnexus_detect_changes() — verify affected scope
 - [ ] Run tests for affected processes
 ```

 ### Split Function/Service

 ```
- [ ] context({name: target}) — understand all callees
+- [ ] gitnexus_context({name: target}) — understand all callees
 - [ ] Group callees by responsibility
- [ ] impact({target, direction: "upstream"}) — map callers to update
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
 - [ ] Create new functions/services
 - [ ] Update callers
- [ ] detect_changes() — verify affected scope
+- [ ] gitnexus_detect_changes() — verify affected scope
 - [ ] Run tests for affected processes
 ```

 ## Tools

-**rename** — automated multi-file rename:
+**gitnexus_rename** — automated multi-file rename:

 ```
-rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
 → 12 edits across 8 files
 → 10 graph edits (high confidence), 2 ast_search edits (review)
 → Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
 ```

-**impact** — map all dependents first:
+**gitnexus_impact** — map all dependents first:

 ```
-impact({target: "validateUser", direction: "upstream"})
+gitnexus_impact({target: "validateUser", direction: "upstream"})
 → d=1: loginHandler, apiMiddleware, testUtils
 → Affected Processes: LoginFlow, TokenRefresh
 ```

-**detect_changes** — verify your changes after refactoring:
+**gitnexus_detect_changes** — verify your changes after refactoring:

 ```
-detect_changes({scope: "all"})
+gitnexus_detect_changes({scope: "all"})
 → Changed: 8 files, 12 symbols
 → Affected processes: LoginFlow, TokenRefresh
 → Risk: MEDIUM
 ```

-**cypher** — custom reference queries:
+**gitnexus_cypher** — custom reference queries:

 ```cypher
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
@@ -98,24 +98,24 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath

 | Risk Factor         | Mitigation                                |
 | ------------------- | ----------------------------------------- |
-| Many callers (>5)   | Use rename for automated updates |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
 | Cross-area refs     | Use detect_changes after to verify scope  |
-| String/dynamic refs | query to find them               |
+| String/dynamic refs | gitnexus_query to find them               |
 | External/public API | Version and deprecate properly            |

 ## Example: Rename `validateUser` to `authenticateUser`

 ```
-1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
+1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
   → 12 edits: 10 graph (safe), 2 ast_search (review)
   → Files: validator.ts, login.ts, middleware.ts, config.json...

 2. Review ast_search edits (config.json: dynamic reference!)

-3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
   → Applied 12 edits across 8 files

-4. detect_changes({scope: "all"})
+4. gitnexus_detect_changes({scope: "all"})
   → Affected: LoginFlow, TokenRefresh
   → Risk: MEDIUM — run tests for these flows
 ```
@@ -1,178 +0,0 @@
---
-name: gitnexus-taint-analysis
-description: "Use when working on, reviewing, or extending GitNexus's CFG/taint/PDG subsystem (the `--pdg` layers), or when reasoning about source→sink data-flow findings. Examples: \"How does taint analysis work here?\", \"Why didn't explain find this flow?\", \"Add a new sink/source\", \"Review the interprocedural taint code\"."
---
-
-# CFG & Taint Analysis with GitNexus
-
-Expert knowledge for the opt-in `--pdg` program-analysis subsystem: control-flow
-graphs, reaching definitions, and intra- + inter-procedural taint. Read this
-before touching `gitnexus/src/core/ingestion/cfg/**` or
-`gitnexus/src/core/ingestion/taint/**`, or when explaining a finding.
-
-## When to Use
-
- "How does the taint engine work / why is this flow (not) reported?"
- Adding a source, sink, or sanitizer to the model.
- Extending or reviewing the CFG / reaching-defs / taint / summary code.
- Understanding the `explain` MCP tool's findings (intra- vs inter-procedural).
- Debugging a false positive or false negative in `--pdg` output.
-
-## The layered substrate (build order)
-
-Taint runs **on** the graph, not beside it. Each layer is opt-in behind `--pdg`
-and a default `analyze` run is **byte-identical** (the golden parity gate is the
-hard floor for every change here).
-
-```
-L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
-L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
-L3  Taint (intra)  source→sink over RD facts, minus sanitizers      (M3 #2083)
-L4  Taint (inter)  per-function summaries composed over CALLS       (M4 #2084)
-```
-
- **Worker-built, main-thread-solved.** The parse worker builds each function's
-  CFG + harvests def/use + call-site facts onto `ParsedFile.cfgSideChannel`
-  (plain, structured-clone-safe data — never AST nodes). The main thread runs
-  the pure solvers. NEVER re-parse on the main thread (re-introduces the #1983
-  OOM).
- **In-phase emit (KTD1).** L1–L4-harvest all run INSIDE the scope-resolution
-  pdg window (`scope-resolution/pipeline/run.ts`, gated `input.pdg === true`),
-  because the disk-backed ParsedFile store is cleared when that phase ends — a
-  standalone post-`mro` phase would read empty data. The cross-function fixpoint
-  (L4) is the exception: it runs in its OWN registered phase (`taintSummaries`)
-  AFTER scope-resolution, because it needs the COMPLETE call graph, and consumes
-  small plain summary data threaded out via `ScopeResolutionOutput`.
- **Pure-solver contract.** `computeReachingDefs`, `computeTaintFlows`,
-  `harvestFunctionSummary`, and `solveInterprocTaint` are pure and deterministic
-  (no graph, no I/O, no logger; sorted outputs). Snapshot tests and
-  content-derived edge ids depend on it.
-
-## Intra-procedural taint (L3)
-
-Forward reachability over RD facts from matched **sources** to matched **sinks**,
-killed by **sanitizers**. Key design points worth internalizing:
-
- **Occurrence-tagged sites.** A flat per-arg binding set cannot tell
-  `exec(escape(x))` (safe) from `exec(x)` (finding); the harvest records nested
-  call structure (`SiteRecord.parent`/via-tags) so sanitizer interposition is
-  precise.
- **Kind-set sanitizer model.** A taint carries a set of *neutralized*
-  `SinkKind`s; a sink fires unless its kind is in the set. So `escape(req.body)`
-  suppresses `res.send` (xss) but STILL fires `db.query` (sql) — a kind-blind
-  kill would be a suppressed live injection (the forbidden FN direction).
-  `path.basename(t)` neutralizes path-traversal only, not command-injection.
- **Statement-level finding identity.** NOT block-pair (block conflation drops
-  distinct findings; `exec(req.body, req.query)` is two findings).
- Persisted as `TAINTED` edges (BasicBlock→BasicBlock); the path rides the
-  `reason` column via the shared versioned codec (`taint/path-codec.ts`).
-
-## Interprocedural taint (L4) — the functional/summary method
-
-The production approach (Sharir-Pnueli 1981; the same shape as Meta's Pysa and
-Mariana Trench, and FB Infer) — NOT full IFDS tabulation. Each function is
-reduced to a compact **summary**, and summaries are composed over the already-
-resolved `CALLS` graph.
-
-**Summary shape** (`taint/summary-model.ts`, whole-parameter granularity):
-
-| Edge | Meaning | Analogue |
-|------|---------|----------|
-| `param→return` | a param flows to the return value | TITO — **reserved** (the floor already covers its recall; precision pass deferred) |
-| `param→callee-arg` | a param flows into arg *j* of a call (carries the path's neutralized sink kinds) | TITO into callee |
-| `param→sink` | a param reaches a modelled sink | partial/triggered sink |
-| `source→return` | the function generates+returns a source | generative — **composed** via the caller's `callResults` |
-| `source→callee-arg` | a generated source flows into a call | fixpoint SEED |
-| `callResults` | a user-function call's result flows to a sink/return/callee-arg in the caller | composes with callee `source→return` |
-
-**The fixpoint** (`taint/interproc-solver.ts`): the unit is `(function,
-parameter, source)`. Seed from `source→callee-arg`, propagate via
-`param→callee-arg`, fire a finding when a tainted param meets `param→sink`.
-
- **Cycle-safe by monotonicity.** The tainted-set is monotone over a finite
-  lattice (`fn × param × source`), so the worklist converges — a recursive call
-  just re-proposes an already-visited entry. SCC condensation would only refine
-  processing order; correctness/termination don't require it.
- **Source-discriminated state (load-bearing).** Key the state by the SOURCE
-  too. Keying only by `(fn, param)` collapses multi-source flows: a sink param
-  tainted by source A is marked visited and a later flow from source B is dropped
-  before firing — the recurring multi-source bug class. (Bit M3; bit M4 U9.)
- **Name-based call join.** Match a summary's call-arg edge to a `CALLS` edge by
-  CALLEE NAME, not call-site line — line-base parity (CFG 1-based vs reference
-  site) is fragile; the callee identity is exact and context-insensitivity
-  taints the callee's param identically at every call site.
- Persisted as `TAINT_PATH` edges (Function→Function), function-level hop chain
-  in `reason` via the same codec; confidence < the intra-procedural 1.0.
-
-**Context-insensitivity** is the accepted trade-off at this tier: one summary
-per function, return/call-site merging accepted (security-conservative). Expect
-some FP from merging; the bigger FN sources are unmodeled features (below).
-
-## Known false-negative classes (documented, deferred)
-
-The largest is **closures/callbacks** (`arr.forEach(() => sink(y))`) — taint
-into a callback is dropped without per-library models (true of CodeQL's JS libs
-too). Also deferred: field/property flows (`obj.x = taint; sink(obj.y)`),
-field-sensitive access paths, guard-style sanitizers, implicit/control-dependence
-flows, promise/async-await threading, and **destructured/rest params before a
-tainted simple param** (the summary port index is the binding ordinal, not the
-formal arg position — needs a formal-param index threaded from the worker
-`BindingEntry`). The interprocedural join is also context-insensitive: when one
-caller invokes two distinct **same-named callees**, a flow into one
-over-attributes to both (sound — over-report, never a missed flow). Absence of a
-finding is NOT proof of safety.
-
-## GitNexus-specific gotchas
-
- **Function↔CFG join.** `FunctionCfg.functionStartLine` is 1-based; `Function`/
-  `Method` node `startLine` is 0-based — join at `startLine - 1`. Function nodes
-  have no column, so same-line functions (`{a:()=>x(), b:()=>y()}`) are
-  ambiguous → drop (the summary driver counts `unresolved`) rather than
-  cross-wire.
- **No rel-property index (S1).** Kuzu has no secondary index on relationship
-  properties, and unanchored `[:TAINTED*]`/`[:TAINT_PATH*]` queries explode.
-  TAINT_PATH is therefore MATERIALIZED + anchored at analyze time, never
-  traversed live; `explain` reads it source-anchored + LIMIT-guarded.
- **`explain` is the only discovery surface.** `TAINTED`/`TAINT_PATH` are
-  deliberately OUT of `VALID_RELATION_TYPES` (impact's allow-list) and the web
-  schema (pinned in `security.test.ts`). `explain` enumerates both layers
-  (cross-function findings carry `interprocedural: true`).
- **One shared codec.** Both the emit path and `explain` import
-  `taint/path-codec.ts`. Two hand-rolled copies of a wire format drift — never
-  fork it. New metadata extends the format WITHIN the version when writer +
-  reader ship together.
- **Cache versioning.** A worker-harvest shape change bumps the parse-cache pdg
-  NAMESPACE (`pdg:N`), NOT `SCHEMA_BUMP` (which cold-invalidates every user).
-  Persisted-graph/config changes ride `RepoMeta.pdg`'s key-union mismatch →
-  full writeback. Model content rides `taintModelVersion`.
-
-## Adding a source / sink / sanitizer
-
-Edit the language model in `taint/typescript-model.ts` (registered via the
-explicit `registerBuiltinTaintModels` seam, keyed by `SupportedLanguages`). The
-spec is hashable data (no functions). A sanitizer's `neutralizes` lists the
-EXACT sink kinds it defends — never a blanket kill. Add a fixture + assert the
-finding (or its absence) in `test/unit/taint/` (real-source harness:
-`test/helpers/ts-cfg-harness.ts`); the end-to-end proof is
-`test/integration/cfg/`.
-
-## Validation checklist for any `--pdg` change
-
-```
-1. tsc clean (schema additions are exhaustiveness-checked; watch the
-   api.ts getNodeQuery runtime read-path if a node label is added).
-2. Targeted vitest by directory (test/unit/taint, test/unit/cfg,
-   test/integration/cfg) — verify by ISOLATION, not full-suite exit
-   (known load-flakes). `node scripts/build.js` before worker/integration runs.
-3. Flag-off golden byte-identical (pipeline-graph-golden.test.ts).
-4. bench/cfg/measure.mjs --check (no fingerprint drift / budget regression).
-5. detect_changes() before commit; impact({direction:'upstream'}) before
-   editing shared symbols (KnowledgeGraph, RepoMeta, RelationshipType, codec).
-```
-
-## Prior art (for deeper design questions)
-
-Sharir & Pnueli 1981 (functional approach); Reps-Horwitz-Sagiv IFDS (POPL 1995);
-FlowDroid/StubDroid (access-path summaries); Pysa & Mariana Trench (TITO /
-propagations, parallel SCC fixpoint); CodeQL Models-as-Data (the richest port
-notation, incl. callback ports); Infer (content-keyed incremental summaries).
@@ -1,17 +0,0 @@
-# GitNexus PR Swarm Review
-
-You are the GitNexus PR review coordinator. Review the pull request named after this command
-(a PR URL or number for `https://github.com/abhigyanpatwari/GitNexus`). If none was given,
-ask for one.
-
-Read `pr-swarm-review/orchestration.md` in this repository and follow it exactly — it is the
-canonical, CLI-neutral review contract (lanes, classifications, output structure, finding
-format, hidden-Unicode checks, behavior rules).
-
-Run in **Solo mode**: you are a single agent, so perform all seven lanes yourself in
-dependency order, adopting each persona in `pr-swarm-review/personas/0N-*.md` in turn
-(lanes 1–2 first, then 3–6, then lane 7). Keep every lane's findings in context. Lane 7
-(synthesis critic) is a hard gate: do not emit the final review until its "Required
-corrections before posting" section is empty.
-
-Stay strictly read-only: investigate and report; never edit files, commit, or post to GitHub.
@@ -1,102 +0,0 @@
-# syntax=docker/dockerfile:1
-
-# Base image: Microsoft's TypeScript+Node devcontainer image. It works on both
-# linux/amd64 and linux/arm64, gets monthly security patches, and ships the
-# non-root `node` user (UID 1000, i.e. user ID 1000), zsh + Oh My Zsh, eslint
-# global, and the `gh` CLI.
-#
-# We pin the image by digest, not by tag. That way a silent upstream retag can't
-# change the build under us. This matches the Dockerfile.cli /
-# gitnexus/Dockerfile.test convention and issue #1451.
-#
-# We pin it as a bare `name@digest` with NO `:tag` prefix on purpose. The
-# production Dockerfiles use plain `docker build`, but this one is built by
-# `@devcontainers/cli` / the VS Code Dev Containers resolver. That resolver's
-# image-name parser rejects the combined `name:tag@sha256:...` form.
-#
-# The digest below is for the `1-22-bookworm` tag. It is the multi-arch
-# manifest-list digest, so it still picks the right platform. To refresh it when
-# bumping the readable tag, run:
-#   docker buildx imagetools inspect \
-#     mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm \
-#     --format '{{json .Manifest.Digest}}'
-FROM mcr.microsoft.com/devcontainers/typescript-node@sha256:7c2e711a4f7b02f32d2da16192d5e05aa7c95279be4ce889cff5df316f251c1d
-
-# Bun is installed via the official remote script (bun.sh/install), pinned by
-# version. Claude Code and Cursor also use official install scripts (no version
-# to pin). To harden Bun: switch to a pinned tarball + per-arch sha256
-# (release artifacts at github.com/oven-sh/bun/releases).
-ARG BUN_VERSION
-ARG TZ=UTC
-ARG USERNAME=node
-
-# Copy the build-only ARGs into runtime ENV so shells and lifecycle scripts can
-# read them. We deliberately do not set CLAUDE_CONFIG_DIR here. Its one true
-# value lives in devcontainer.json `containerEnv`, and the runtime value wins
-# anyway.
-ENV BUN_VERSION=${BUN_VERSION} \
-    BUN_INSTALL=/home/${USERNAME}/.bun \
-    TZ=${TZ} \
-    DEVCONTAINER=true \
-    NODE_OPTIONS=--max-old-space-size=4096 \
-    POWERLEVEL9K_DISABLE_GITSTATUS=true
-
-# Native build toolchain that gitnexus/postinstall needs. It compiles
-# tree-sitter native bindings, the vendored Dart/Proto/Swift grammars, and the
-# @ladybugdb/core N-API addon (a native Node add-on). python3, make, and g++ are
-# required. This mirrors the apt block in the existing Dockerfile.cli /
-# gitnexus/Dockerfile.test images.
-RUN apt-get update \
-    && apt-get install -y --no-install-recommends \
-        python3 make g++ git curl ca-certificates bash unzip \
-    && rm -rf /var/lib/apt/lists/*
-
-# Create and chown the named-volume mount points (~/.npm, ~/.local,
-# /commandhistory) up front. That way an empty volume inherits `node:node`
-# ownership the first time it is mounted. The three CLI config dirs (~/.claude,
-# ~/.codex, ~/.cursor) are bind-mounted from the host instead. A bind mount
-# completely hides the image-side ownership, so those paths need no chown here.
-RUN mkdir -p \
-        /home/${USERNAME}/.npm \
-        /home/${USERNAME}/.local/bin \
-        /commandhistory \
-    && chown -R ${USERNAME}:${USERNAME} \
-        /home/${USERNAME}/.npm \
-        /home/${USERNAME}/.local \
-        /commandhistory
-
-USER ${USERNAME}
-
-# Install Claude Code via the official native installer. Downloads the latest
-# self-contained binary for the running platform and places it at
-# ~/.local/bin/claude — no Node.js runtime dependency, no version to pin.
-RUN curl -fsSL https://claude.ai/install.sh | bash
-
-# Install the Codex CLI globally via npm. No version pinned — @latest at build
-# time. (Codex has no native binary installer; npm is the canonical method.)
-RUN npm install -g @openai/codex
-
-# Install the Cursor agent CLI via the official install script. Downloads the
-# latest agent-cli-package for the running platform and places `cursor-agent`
-# and `agent` into ~/.local/bin — no version or hash to pin.
-RUN curl -fsSL https://cursor.com/install | bash
-
-# Install Bun via the official remote installer, pinned by version. The first
-# positional arg to `bash` is the release tag (`bun-vX.Y.Z`), so a specific
-# version is fetched even though the install script itself is downloaded fresh
-# on every build. NOTE: this is the ONE remote script we run unverified in
-# this image — Cursor and the base image are pinned by sha256/digest. Hardening
-# path: switch to a pinned tarball + per-arch sha256 in the Cursor style
-# (artifacts at github.com/oven-sh/bun/releases). `BUN_INSTALL` is set in ENV
-# above so the binary lands at a known path regardless of any rc-file edits
-# the installer makes (which we ignore — we own the shell rc files).
-RUN set -eux; \
-    curl -fsSL --retry 3 --max-time 120 https://bun.sh/install \
-        | bash -s "bun-v${BUN_VERSION}"; \
-    test -x "${BUN_INSTALL}/bin/bun"
-
-# Put ~/.local/bin and Bun's bin dir on PATH for interactive shells and
-# lifecycle scripts. ~/.local/bin is where Cursor's installer drops the `agent`
-# and `cursor-agent` symlinks; ${BUN_INSTALL}/bin is where the Bun installer
-# drops `bun` / `bunx`.
-ENV PATH=/home/${USERNAME}/.local/bin:${BUN_INSTALL}/bin:${PATH}
@@ -1,364 +0,0 @@
-# GitNexus Devcontainer
-
-A cross-platform Dev Container that pre-installs Claude Code, OpenAI Codex CLI, Cursor CLI, and Bun alongside the GitNexus native build chain. Supported hosts: **macOS, Linux, Windows 11 (native), and Windows 11 via WSL2.** Windows-native needs a **one-time `HOME` env var setup** — handled automatically by the `initializeCommand` on first run (see [Windows 11 setup](#windows-11-setup)).
-
-> ### ⚠️ Read this before using it on a work machine
->
-> This devcontainer **does not write to your host AI-CLI config.** Your skills, agents, commands, plugins, memory, prompts, and rules are **copied once** from a read-only host stage into a per-container volume on first create; the container edits its own copy and can never write back. So a compromised workspace dependency running in the container **cannot** drop a malicious agent, command, skill, or plugin onto your host for your next host CLI session to load — the write-through vector earlier versions had is closed. Your **credentials** (Claude/Codex/Cursor logins, plus `gh`) likewise stay in per-container volumes and are never written back, and `~/.ssh`, `~/.aws`, `~/.azure`, and `~/.docker` are mounted **read-only**.
->
-> What is **still** exposed: the read-only host stages (`/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`) and the read-only credential mounts are all **readable** inside the container. A compromised dependency can therefore READ your host CLI config, memory, SSH/cloud credentials, and GitHub token — and there is **no egress firewall yet**, so it has the network to exfiltrate what it reads. Read-only protects you from tampering and write-back, not from disclosure.
->
-> The trade-off of the copy model: host and container config **diverge after first create.** A skill or plugin you add on the host later won't appear in the container until you wipe the config volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)). Edits you make inside the container persist across rebuilds but never reach the host.
-
-## Quick start
-
-1. Install [Docker Desktop](https://docs.docker.com/desktop/) (Windows/macOS) or Docker Engine (Linux).
-2. Install [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
-3. Install [Node.js](https://nodejs.org/) on the **host** (Node 18+). This is the only host-side toolchain dependency beyond Docker and VS Code — the devcontainer's `initializeCommand` runs `node .devcontainer/ensure-host-config-dirs.cjs` to set up the bind-mount source directories before container create. If you already use Claude Code or another Node-based CLI on the host, you're already set.
-4. Open the repo in VS Code → Command Palette → **Dev Containers: Reopen in Container**.
-5. Wait for the first build (~3–6 minutes) and `postCreateCommand` to finish installing workspace dependencies.
-6. Authenticate the three CLIs once — see [First-time CLI authentication](#first-time-cli-authentication) below.
-
-## Windows 11 setup
-
-### Windows-native (one-time setup, then "just works")
-
-The host bind mounts use `${localEnv:HOME}/.claude` (and `.codex`, `.cursor`, `.ssh`, `.config/git`, `.config/gh`, `.gitconfig`). VS Code resolves `${localEnv:HOME}` by reading its own process env, and Windows doesn't set `HOME` by default — it uses `USERPROFILE`. So the bind mounts can't resolve until you tell Windows to also expose your profile as `HOME`.
-
-The `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`) handles this automatically:
-
-1. **First time you Reopen in Container**, the script detects the missing `HOME`, runs `setx HOME "%USERPROFILE%"` (which writes to your user-level Windows env — no admin needed), prints a one-time setup banner, and exits.
-2. **Close all VS Code windows** (File → Exit) and reopen. VS Code picks up the new `HOME` at startup.
-3. **Reopen in Container again.** The script now sees `HOME=C:\Users\<you>`, skips the setup block, creates the bind-mount source dirs, and Docker brings the container up.
-
-Subsequent rebuilds work normally with no extra steps. The `HOME` env var is set persistently in your Windows user environment, so it'll be there for every future VS Code session (and any other tool that wants `HOME`).
-
-If you'd rather set it manually before opening the container:
-
-```powershell
-setx HOME "%USERPROFILE%"
-# Close & reopen VS Code
-```
-
-### Known trade-offs of Windows-native vs WSL2
-
-Windows-native works, but Docker Desktop's Windows bind-mount layer has rough edges that WSL2 avoids:
-
- **File watchers can miss events.** Vite / jest `--watch` running inside the container watching workspace files mounted from `D:\...` may miss changes — chokidar polling (`CHOKIDAR_USEPOLLING=true`) is the usual workaround.
- **`npm install` is 3-5× slower** through the Windows-to-Linux bind-mount translation than on a WSL2-native filesystem.
- **Permission edge cases.** The husky `.husky/_/h` EPERM class we hit earlier in this PR is specific to Windows-side bind mounts changing UID ownership between container runs. `post-create.sh` clears the cache defensively to keep this from being fatal, but it's still a real source of friction.
-
-If you hit any of those and want to migrate to WSL2 later, the steps are below.
-
-### WSL2 (faster, fewer edge cases)
-
-To clone and open the repo inside WSL2:
-
-```bash
-# 1. Install WSL2 and a Linux distro if you haven't already.
-wsl --install -d Ubuntu
-
-# 2. Enter WSL.
-wsl
-
-# 3. Clone the repo inside your WSL2 home directory.
-cd ~
-git clone https://github.com/abhigyanpatwari/GitNexus.git
-cd GitNexus
-
-# 4. Launch VS Code from inside WSL — this opens VS Code attached to the WSL2
-#    filesystem, so `${localEnv:HOME}` resolves to the WSL user's home and
-#    subsequent "Reopen in Container" uses the WSL2-side path.
-code .
-```
-
-Then run **Dev Containers: Reopen in Container**. The workspace will be bind-mounted from `\\wsl$\Ubuntu\home\<user>\GitNexus`, which is fast and gives reliable file-system events. **Make sure Docker Desktop's WSL integration is enabled** for your distro: Docker Desktop → Settings → Resources → WSL Integration → toggle on the distro you cloned into.
-
-## macOS
-
-Open the repo folder in VS Code → **Reopen in Container**. The image is multi-arch; on Apple Silicon you'll pull the `linux/arm64` variant automatically.
-
-## Linux
-
-Same as macOS — open in VS Code and reopen in container. `updateRemoteUserUID: true` (default) shifts the container's `node` user UID/GID to match your host user, so bind-mounted files stay writable without extra setup.
-
-## How CLI state flows from your host
-
-### AI CLIs (Claude Code, Codex, Cursor): copy-once from a read-only host stage + per-container credentials
-
-The three AI CLIs use a **copy-from-read-only-stage topology**: the host's `~/.<cli>` folders (and `~/.claude-mem`) are mounted **read-only** at `/host/.<cli>`, and `post-create.sh` copies out of them into per-container named volumes. Credentials, identity, and single config files are copied on **every** create; the shareable subdirs (plugins, skills, agents, memory, commands, prompts, rules) are copied **once** on first create and then owned by the container. Nothing is bind-mounted read-write into the host's CLI config, so the container can never modify your host setup. Session sub-paths overlay the config volume via their own named volumes (Docker mount precedence — more specific path wins).
-
-| Mount                                              | Source                                                                                                                  | Target                                                    | Mode          | Purpose                                                                                                                             |
-| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Container Claude config dir                        | _named volume_ `claude-config-${devcontainerId}`                                                                        | `/home/node/.claude`                                      | rw            | Per-container credentials + identity                                                                                                |
-| Container Codex config dir                         | _named volume_ `codex-config-${devcontainerId}`                                                                         | `/home/node/.codex`                                       | rw            | Per-container credentials                                                                                                           |
-| Container Cursor config dir                        | _named volume_ `cursor-config-${devcontainerId}`                                                                        | `/home/node/.cursor`                                      | rw            | Per-container credentials                                                                                                           |
-| Container gh config dir                            | _named volume_ `gh-config-${devcontainerId}`                                                                            | `/home/node/.config/gh`                                   | rw            | Per-container `gh` auth (`hosts.yml`/`config.yml`) seeded from host stage; in-container login persists                              |
-| **Claude sessions** (overlay on the config volume) | _named volume_ `…-claude-sessions-${devcontainerId}`                                                                    | `/home/node/.claude/projects`                             | rw            | `--resume` transcripts; survives the `<cli>-config` volume wipe — see [Session resume](#session-resume-across-container-recreation) |
-| **Codex sessions**                                 | _named volume_ `…-codex-sessions-${devcontainerId}`                                                                     | `/home/node/.codex/sessions`                              | rw            | `codex resume` rollouts; SQLite index backfills on recreation                                                                       |
-| **Cursor sessions**                                | _named volumes_ `…-cursor-sessions-${devcontainerId}`, `…-cursor-projects-${devcontainerId}`                            | `/home/node/.cursor/chats`, `/home/node/.cursor/projects` | rw            | `cursor-agent resume` store (best-effort — layout reverse-engineered)                                                               |
-| **claude-mem store**                               | _named volume_ `claude-mem-${devcontainerId}`                                                                           | `/home/node/.claude-mem`                                  | rw            | claude-mem's SQLite DB + Chroma vector store; **seeded once** from `/host/.claude-mem`, then container-private — see note below     |
-| Host Claude state, read-only stage                 | `$HOME/.claude`                                                                                                         | `/host/.claude`                                           | **read-only** | `post-create.sh` reads credentials + identity from here on container-create                                                         |
-| claude-mem store, read-only stage                  | `$HOME/.claude-mem`                                                                                                     | `/host/.claude-mem`                                       | **read-only** | `post-create.sh` seeds the claude-mem volume from here on first create                                                              |
-| Host Codex state, read-only stage                  | `$HOME/.codex`                                                                                                          | `/host/.codex`                                            | **read-only** | Same purpose for Codex                                                                                                              |
-| Host Cursor state, read-only stage                 | `$HOME/.cursor`                                                                                                         | `/host/.cursor`                                           | **read-only** | Same purpose for Cursor                                                                                                             |
-| **Claude shareable subdirs**                       | _seeded into the config volume from_ `$HOME/.claude/{plugins/marketplaces,plugins/cache,skills,agents,memory,commands}` | same under `/home/node/.claude/`                          | n/a (copy)    | **Seed-once** copy from the read-only stage; container owns its copy after                                                          |
-| **Codex shareable subdirs**                        | _seeded from_ `$HOME/.codex/{plugins,prompts,memories,skills}`                                                          | same under `/home/node/.codex/`                           | n/a (copy)    | **Seed-once** copy (whole `plugins/` dir — no path-bearing registry inside it)                                                      |
-| **Cursor shareable subdirs**                       | _seeded from_ `$HOME/.cursor/{plugins/marketplaces,plugins/local,rules,commands,agents,skills}`                         | same under `/home/node/.cursor/`                          | n/a (copy)    | **Seed-once** copy of the Cursor 2.5 plugin/rules/commands surface                                                                  |
-
-**What gets seeded once from the host (copy, not bind):**
-
- **Claude**: `plugins/marketplaces`, `plugins/cache`, `skills/`, `agents/`, `memory/`, `commands/`
- **Codex**: `plugins/` (whole dir), `prompts/`, `memories/`, `skills/`
- **Cursor**: `plugins/marketplaces`, `plugins/local`, `rules/`, `commands/`, `agents/`, `skills/`
-
-On the **first** container-create, `post-create.sh` copies each of these out of the read-only `/host/.<cli>` stage into the per-container config volume, then writes a `.devcontainer-shareable-seeded` marker. On every later rebuild the marker is present, so the copy is skipped and the container keeps whatever it has accumulated. A plugin/skill/agent you install **inside** the container persists across rebuilds; one you add on the **host** after first create won't appear in the container until you remove the config volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)). Nothing here is writable back to the host — `/plugin marketplace add` inside the container installs into the container's own volume copy, not your host `~/.<cli>/plugins/`.
-
-**Single config files are copied on container-create, not bind-mounted** — on Docker Desktop Windows a single-file bind is 9p while the named volume is ext4, and atomic config writes (`tmp` → rename onto target) trip EXDEV (this is what caused Codex's `config/batchWrite failed in TUI`). So these are synced from host on rebuild and the container rewrites its own copy until the next rebuild: `settings.json` + `$HOME/.claude.json` (Claude), `config.toml` (Codex), `cli-config.json` + `mcp.json` (Cursor). `hooks.json` (Cursor) is deliberately **not** synced — Cursor hooks execute shell commands, so sharing them would widen the supply-chain attack surface; add it yourself if you want it.
-
-**Plugin registry files with absolute paths are translated, not copied verbatim** — Claude's `known_marketplaces.json` / `installed_plugins.json` / `plugin-catalog-cache.json` and Cursor's `installed_plugins.json` bake in `C:\Users\…` (Windows) or `/Users/…` (macOS) install paths. `post-create.sh` rewrites those to `/home/node/.<cli>/plugins/…` and writes the result into the named volume, so plugins resolve inside Linux instead of failing with `cache-miss`. This translation is **also seed-once per CLI** — it runs only for a CLI being seeded that create (`translate-plugin-registries.cjs claude cursor`), so it stays consistent with the seed-once `cache/` copy and won't overwrite a plugin you installed inside the container on a later rebuild. Codex needs no translation — its enablement registry is `config.toml` (git URLs + logical keys, no filesystem paths), so its whole `plugins/` dir is copied as-is.
-
-**What stays per-container (in the named volume) and is synced from host on container-create:**
-
- `.credentials.json` (Claude OAuth tokens), `auth.json` (Codex), `cli-config.json` (Cursor) — credentials
- `~/.claude/.claude.json` (Claude's identity-only file: `userID`, `oauthAccount`, migration tracking) — kept per-container so logging in via container doesn't overwrite host's stored identity
-
-`post-create.sh` runs on every container-create, copies host's credentials into the volume if present, then container manages refresh from there. Sync is "always overwrite if host has the file, otherwise leave container alone". So:
-
- Host has credentials → container starts logged in.
- Host has no credentials → `claude login` / `codex login --device-auth` / `cursor-agent login` inside container; credentials stay in the named volume across rebuilds (volume is keyed by `${devcontainerId}`, stable for the workspace path).
- `claude logout` inside container clears volume credentials only; host is untouched.
-
-**Why CLAUDE_CONFIG_DIR is intentionally NOT set:** Claude's default `~/.claude` matches the named-volume mount target, so the env var added no behavior — but setting it changed which file Claude reads `hasCompletedOnboarding` from. With it set, Claude reads `$CLAUDE_CONFIG_DIR/.claude.json` (the small identity-only file) and re-onboards every container; without it, Claude reads `$HOME/.claude.json` (copied from the read-only `/host/.claude.json` stage on container-create via `seed-claude-config.cjs`, with `hasCompletedOnboarding: true`).
-
-**Host CLI config is protected from write-through.** The shareable dirs are copied out of a **read-only** stage into the container's own volume, so a compromised npm package in the workspace dep tree — running inside the container — **cannot** write a malicious agent, command, skill, or plugin back to `~/.claude/`, `~/.codex/`, or `~/.cursor/` on the host. The earlier design bind-mounted these read-write and accepted that write-through as the cost of live sync; this design closes it. An even earlier alternative (read-only stage + symlinks) made `/plugin marketplace add` inside the container fail with EROFS; copying into a writable volume avoids that, because the container writes to its own copy rather than a read-only mount. What a compromised dependency can still do is **read** the read-only host stages (`/host/.<cli>`, `/host/.claude-mem`) and the read-only credential mounts and exfiltrate them — there is [no egress firewall yet](#whats-not-included-yet). The cost of the copy model is **divergence**: host edits made after first create don't reach the container until you wipe the config volume and rebuild.
-
-**Refresh-token divergence between rebuilds.** Container's credentials match host's at container-create time; after that, container manages its own refresh until the next rebuild. Anthropic rotates refresh tokens on every use, so an unattended container that hasn't talked to the API in weeks can hit a silent 401 if the host has refreshed since. Re-run `claude login` inside the container, or rebuild, to recover.
-
-**claude-mem is seeded once, then container-private.** The [claude-mem](https://github.com/thedotmack/claude-mem) store (`$HOME/.claude-mem` — a multi-GB SQLite DB `claude-mem.db` + `-wal`/`-shm`, plus a Chroma vector store `chroma/chroma.sqlite3` and its HNSW index binaries) is the one shareable-looking folder that is **deliberately not a host bind**, for the same SQLite reason as sessions below: a multi-GB WAL database over the 9p/virtiofs bind risks unreliable `fcntl` locking and corruption — sharply so if claude-mem ran on the host and in the container against the same DB at once. So it gets its own per-container named volume (`claude-mem-${devcontainerId}`), and `post-create.sh` **seeds it once** from the read-only `/host/.claude-mem` stage _only when the volume has no DB yet_. The first container-create copies the host's store in (a one-time copy, possibly several GB); every later rebuild keeps whatever the container accumulated and skips the copy. The container's memory and the host's **diverge from that seed point** — writes do not flow back — which is the price of keeping SQLite off a shared bind. To re-seed from the host's current store, remove the volume (`docker volume rm claude-mem-<id>`) and rebuild. `ensure-host-config-dirs.cjs` creates an empty `~/.claude-mem` on hosts that never installed claude-mem, so the read-only stage bind always resolves; the seed then finds no DB and the container simply starts with empty memory.
-
-### Session resume across container recreation
-
-`claude --resume`, `codex resume`, and `cursor-agent resume` all read **local** transcript files. Those live _inside_ each CLI's config dir, which is a per-container named volume — so they already survive an ordinary **Rebuild Container**. What they did _not_ survive were the very things this README tells you to do: `docker volume rm <cli>-config-${devcontainerId}` to force a re-login or clear an `EACCES`, a `${devcontainerId}` change, or a full delete-and-recreate. Each of those drops the config volume and takes your session history with it.
-
-So the resume/transcript directories get their **own** named volumes (mount group 6 in `devcontainer.json`), keyed like the `node_modules` volumes (`${localWorkspaceFolderBasename}-…-${devcontainerId}`) and mounted _over_ the config volume at the session sub-paths:
-
-| Resume command                   | Persisted volume → target                                                               | What's stored                                                                                                                                                                                                                                          |
-| -------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `claude --resume` / `--continue` | `…-claude-sessions-…` → `~/.claude/projects`                                            | `<encoded-cwd>/<uuid>.jsonl` transcripts + `sessions-index.json`. Container cwd is always `/workspace`, so only that slice is stored. Pure JSONL/JSON — no SQLite.                                                                                     |
-| `codex resume` / `resume --last` | `…-codex-sessions-…` → `~/.codex/sessions`                                              | `YYYY/MM/DD/rollout-*.jsonl`. The `state_5.sqlite` thread index stays on the config volume (a single WAL file we don't split out); when it's absent after a recreation, Codex rebuilds it from these rollouts on the next start (a one-time backfill). |
-| `cursor-agent resume` / `ls`     | `…-cursor-sessions-…` → `~/.cursor/chats`; `…-cursor-projects-…` → `~/.cursor/projects` | `chats/{hash}/{uuid}/store.db` (one SQLite db per session, each in its own dir) + `projects/.../agent-transcripts`. cursor-agent's layout is reverse-engineered, so treat this as best-effort.                                                         |
-
-Because these are **separate** volumes from `<cli>-config-${devcontainerId}`, the re-login fix (`docker volume rm claude-config-…`) no longer destroys your sessions — that was the point.
-
-**Survives:** Rebuild Container, Rebuild Without Cache, a full delete-and-recreate of the container, and the `docker volume rm <cli>-config-…` re-login / `EACCES` fix.
-
-**Does _not_ survive** (same durability tier as the `node_modules` volumes): `docker volume prune`, a `${devcontainerId}` change (moving the checkout to a new path, or switching between Windows-native and WSL2), or moving to a new machine. To deliberately wipe sessions, remove the session volumes too — see [Rebuild / reset](#rebuild--reset). Two checkouts with the **same folder name** on one host would share session volumes only if they also share a `${devcontainerId}`; they don't, so they stay separate.
-
-**First rebuild after adopting this, one-time:** if a container created _before_ these volumes existed already had sessions on the config volume (`~/.claude/projects`, `~/.codex/sessions`, …), the new empty session volume mounts _over_ that sub-path and **masks** the old content — same Docker-precedence shadowing described for plugins above. The old sessions are hidden, not deleted. To carry them forward once, copy them out of the config volume into the session volume; or just start fresh — new sessions land on the session volume from then on.
-
-**Why sessions are container-private and not even seeded from the host.** The shareable config dirs are _seeded once_ from the host (you want your skills/agents/plugins in the container). Sessions are deliberately _not_ seeded and never touch the host, because a transcript can contain anything you pasted or the agent read — API keys, file contents, connection strings. Binding or copying them to/from the host would (a) spill that to host disk, (b) add a write-through surface a compromised dependency can reach (there's still [no egress firewall](#whats-not-included-yet)), and (c) leak _every other project's_ transcripts into the container (Codex `sessions/` and Cursor `chats/` aren't project-scoped). Container-private volumes avoid all three while still surviving recreation. And Claude/Codex transcripts embed the container cwd (`/workspace`), so even if you _did_ bind them to the host, the host CLI wouldn't natively `--resume` them — its encoded-cwd folder differs.
-
-**Opt in to host-shared sessions anyway.** If you want transcripts visible/portable on the host and accept the trade-offs above, uncomment the host-bind block in `devcontainer.json` (just below the group-6 volumes) and add the matching source dirs to `ensure-host-config-dirs.cjs`'s `DIRS` so Docker can resolve the binds. That block scopes Claude to `/workspace`'s encoded subdir to limit the cross-project leak; the Codex and Cursor stores can't be scoped that way, so they expose every project's transcripts.
-
-### Other host bind mounts
-
-| Container path  | Host source         | Mode          | Why                                                                                    |
-| --------------- | ------------------- | ------------- | -------------------------------------------------------------------------------------- |
-| `~/.config/git` | `$HOME/.config/git` | **read-only** | XDG-style git config / ignore / attributes                                             |
-| `~/.ssh`        | `$HOME/.ssh`        | **read-only** | SSH commit signing + git push over SSH                                                 |
-| `~/.config/gh`  | `$HOME/.config/gh`  | **copy → volume** | `gh` CLI auth (PR/issue create, checks) — seeded from your host login on create into a per-container volume; in-container `gh auth login` persists across rebuilds and never writes back to the host |
-| `~/.docker`     | `$HOME/.docker`     | **read-only** | Container registry auth + buildx config (inert until you add Docker CLI via a Feature) |
-| `~/.aws`        | `$HOME/.aws`        | **read-only** | AWS CLI / SDK credentials (forward-compat — empty by default)                          |
-| `~/.azure`      | `$HOME/.azure`      | **read-only** | Azure CLI credentials (forward-compat — empty by default)                              |
-
-**Why `ssh`/`aws`/`azure`/`docker` are read-only, and why `gh` is copied into a volume:** `ssh`/`aws`/`azure` are consumed read-only by their clients (the SSH client and the AWS/Azure SDKs only read their credential files), so a one-way mount loses nothing. `docker` _can_ write its own state (`docker login` / buildx write `config.json`), but a read-write host bind would let a compromised in-container dependency rewrite your host `~/.docker/config.json` (point a `credHelper` at an attacker-controlled binary) — a credential-takeover vector. The common case is _reading_ an existing host login, so `docker` stays **read-only**: registry pulls/pushes using your host creds work, only a `docker login` inside the container won't persist back. `gh` used to be read-only for the same reason, but that meant an in-container `gh auth login` had nowhere to write and silently failed. So `gh` now uses the **copy-into-volume** model (the same one the AI-CLI credentials use): the host `~/.config/gh` is a read-only _stage_ at `/host/.config/gh`, and `post-create.sh` copies `hosts.yml`/`config.yml` out of it into the per-container `gh-config` volume on create. The container gets a **writable** copy — `gh auth login` / `gh auth refresh` inside the container now work and persist across rebuilds — while the read-only stage guarantees nothing is ever written back to the host's token. If you want `docker` to behave the same way, give it the same treatment (a `/host/.docker` stage + a docker-config volume + a copy step in `post-create.sh`).
-
-`~/.gitconfig` is **not** bind-mounted — VS Code's Dev Containers extension auto-copies the host's gitconfig into the container at attach time (this is built-in behavior, not something this devcontainer configures). The bind-mount approach conflicts with that auto-copy mechanism, so we let VS Code own it. The end result is the same: your host's `user.name` / `user.email` are available inside the container.
-
-If a host source dir doesn't exist when the container is first created, the `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`) creates it empty — so the bind mount always has a valid source.
-
-### Per-CLI quirks worth knowing
-
- **Claude Code on macOS** stores credentials in the system Keychain, not in `~/.claude/.credentials.json`. The sync silently no-ops; run `claude login` inside the container once and the named volume persists it.
- **Codex on macOS / Linux with `cli_auth_credentials_store = "keyring"`** stores auth in the OS keyring (Keychain / Secret Service), so `~/.codex/auth.json` may not exist on host. Same fallback: `codex login --device-auth` inside the container.
- **Cursor CLI inside containers** has [known upstream auth issues](https://forum.cursor.com/t/cursor-agent-authentication-issue-inside-docker/143995) — even with a correctly-synced `cli-config.json`, you may need to re-run `cursor-agent login` inside the container.
- **Stale named volumes from old rebuilds can carry forward.** If you delete and re-create the same workspace, or if a prior container left interim state with a different `userID`, deleting the named volumes before rebuild guarantees a clean sync: `docker volume rm claude-config-${devcontainerId} codex-config-${devcontainerId} cursor-config-${devcontainerId}` (look them up with `docker volume ls | grep -config-`).
- **User-scope MCP servers with absolute host paths won't resolve in-container.** `~/.claude.json` (Claude), `~/.codex/config.toml` (Codex), and `~/.cursor/mcp.json` (Cursor) are copied from host on container-create, so their user-scope `mcpServers` entries come along. But an entry whose `command` is an absolute host path (`C:\tools\foo.exe`, `/usr/local/bin/foo`) points at a binary that doesn't exist in the container — that server silently fails to launch. Only registry/`npx`-based servers (like this repo's `.mcp.json`, which uses `npx -y gitnexus@latest mcp`) and remote/URL servers work unchanged. The path-translation pass only rewrites `*/.<cli>/plugins/*` registry paths, **not** arbitrary `mcpServers` command paths (there's no correct container target for a host-local binary). Install such MCP servers inside the container, or use `npx`/remote ones.
- **Host config is seeded once per devcontainer, then diverges — this now applies to everything.** A `mcpServers` entry, setting, plugin, skill, agent, or command you add **on the host after** the container was created is not visible in the container until you remove the config volume and rebuild. Single config files (`mcpServers`, `settings.json`, …) are copy-on-create; the shareable dirs (plugins/skills/agents/memory/commands/prompts/rules) are copy-on-**first**-create (they persist across ordinary rebuilds and aren't even re-copied). Both diverge from the host after their copy. To pull host-side changes in, wipe the relevant volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)).
- **Plugins/skills/agents installed in-container persist; they do not reach the host.** A `/plugin marketplace add` (or `codex plugin add`, or a new skill/agent) inside the container writes to the container's own config volume and survives ordinary rebuilds. It never appears on the host — the host dirs are read-only sources, not bind targets. To get a plugin onto the host, install it on the host (then wipe + rebuild to seed it into the container).
- **No cross-checkout plugin contention.** Because each container copies plugins into its own per-`${devcontainerId}` volume rather than sharing one host bind source, two containers (or checkouts) installing plugins at the same time no longer interleave git clones/extractions against a shared host dir. Each writes only its own copy.
-
-### What you still don't have inside the container
-
-These are commonly-needed CLIs that aren't installed by default — adding them would be follow-up work, not in this PR's scope:
-
- **Docker CLI** (for `docker push` / `docker build` from inside the container). Add via `ghcr.io/devcontainers/features/docker-outside-of-docker:1` to the `features` block — `~/.docker/` is already mounted **read-only**, so your host `docker login` state works immediately for pulls/pushes; an in-container `docker login` won't persist to the host (drop `,readonly` on that mount if you need it to).
- **AWS CLI / Azure CLI / gcloud / kubectl** — same pattern: add the matching Feature, the host config dirs already flow through.
- **Private npm registry auth** (`~/.npmrc`) — you don't have a global one on this host. If you ever start using private packages, add `source=${localEnv:HOME}/.npmrc,target=/home/node/.npmrc,type=bind,readonly` to the mounts.
-
-That means:
-
- **Authentication is shared.** If you're already logged in on the host (`claude login`, `codex login`, `cursor-agent login`, `gh auth login`), you're already logged in inside the container. No second login step.
- **Plugins, skills, agents, memory, and commands are seeded from the host once, then container-private.** On first create the container copies your host's plugins/skills/agents/memory/commands (and Codex prompts/memories, Cursor rules) into its own volume. After that they're independent: install or edit inside the container and it stays in the container (persists across rebuilds); add a plugin or agent on the host and the container won't see it until you wipe the config volume and rebuild. Nothing the container does reaches the host. (`settings.json` and the user-scope `~/.claude.json` are copy-on-create the same way; `~/.claude/projects/` is container-local by design.)
- **Git identity comes from the host.** Commits from inside the container use your host's `user.name` / `user.email` — VS Code's Dev Containers extension auto-copies your `~/.gitconfig` into the container at attach time. Any XDG-style config under `~/.config/git/` flows through via the read-only bind mount. To change git identity, edit `~/.gitconfig` on the host (container-side `git config --global` writes to a container-local file that's discarded on rebuild).
- **SSH keys flow through (read-only).** Push over SSH remotes and SSH commit signing work inside the container using your host keys. The mount is read-only so container code can't exfiltrate or modify private keys — agent-perspective, this means you get git operations but the keys stay vendor-side.
- **`gh` auth is shared, and in-container logins persist.** If you're logged in on the host, `gh pr create`, `gh pr checks`, `gh issue create` work inside the container without re-authenticating. If you're not, run `gh auth login` inside the container once — because `gh` config lives in a writable per-container volume (seeded from the host stage), that login persists across rebuilds and never touches the host's token.
- **No per-workspace duplication.** All your devcontainers across all your projects see the same host CLI state, just like all your host shells do.
-
-The bind mount source directories are guaranteed to exist by the `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`), which runs on the host before container create. It's a Node script (not a shell one-liner) so the same command works on Windows `cmd.exe` and POSIX shells. It creates the top-level bind-mount source dirs — `~/.claude`, `~/.codex`, `~/.cursor`, `~/.claude-mem`, plus `~/.ssh`, `~/.docker`, `~/.aws`, `~/.azure`, `~/.config/{gh,git}`. It deliberately does **not** pre-create the shareable subdirs (skills/agents/plugins/…): those are no longer bind sources (they're copied out of the whole-`~/.<cli>` read-only stage), and pre-creating empty ones would needlessly write into the host of someone who never used that CLI.
-
-### Trust boundary, concretely
-
-Host and container share a single trust boundary by design — fine for personal-dev, but the consequence is concrete. Any malicious npm package or `postinstall` script in the workspace dep tree, running inside the container, has direct **read** access to:
-
- **Host AI CLI state** — the read-only stage at `/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`, which exposes your **entire** host `~/.<cli>` tree (credentials, identity, AND the shareable skills/agents/plugins/memory/commands) for _reading_. The container copies what it needs out of this stage; a compromised dep can read all of it. It is read-only, so none of it can be written back
- The **container's own credential snapshots** at `/home/node/.claude/.credentials.json` etc. (copied from host on container-create)
- `~/.claude/memory/` / per-project memory (which may contain user-stored secrets if you've used the `/remember` skill)
- The **current container's own session transcripts** (`~/.claude/projects`, `~/.codex/sessions`, `~/.cursor/chats`/`projects` — the group-6 volumes), which can hold anything pasted into or read during a session. These are container-private (see one-way note below), so this is read access to _this_ container's sessions only, not the host's or other projects'
- Your **`gh` token** (`~/.config/gh`)
- Your **SSH private keys** (`~/.ssh/`)
- Docker registry tokens in **`~/.docker/config.json`** (if you've `docker login`-ed)
- AWS/Azure CLI credentials if you've populated `~/.aws/` or `~/.azure/`
-
-It does **not** have write-through to the host's CLI config. The shareable dirs are copied out of the read-only stage into the container's own volume, so a compromised in-container dep **cannot** write into your host `~/.claude/{plugins,agents,skills,commands,memory}/`, `~/.codex/{plugins,prompts,memories,skills}/`, or `~/.cursor/{plugins,rules,commands,agents,skills}/`. The persistence vector earlier versions had — drop a malicious auto-loaded agent/command/skill/rule onto the host, have it run in your next **host** session — is closed: there is no writable path from the container to those host folders. (Cursor's `hooks.json` is still additionally withheld from even the _container's_ copy, because hooks fire without an agent invoking them.) The boundary is now one-way for **all** of the host CLI config, not just credentials.
-
-**What stays one-way (genuinely protected):** everything. Credentials never flow back to host — `.credentials.json` / `auth.json` / `cli-config.json` live only in the per-container named volumes, and the `/host/.<cli>` stage they're copied from is mounted **read-only**, so the snapshot can't be overwritten back. The shareable AI-CLI dirs (skills/agents/plugins/memory/commands/prompts/rules) are now copy-on-create from that same read-only stage, so they have the one-way property too — readable for the copy, never writable back. `~/.ssh`, `~/.config/git`, `~/.aws`, `~/.azure`, and **`~/.docker`** are read-only binds with the same property — a compromised dep can _read_ your registry tokens but cannot _rewrite_ them to hijack your future host auth. **`~/.config/gh`** is now a read-only _stage_ copied into a per-container volume, so it keeps that same one-way property: the container reads it once to seed its own writable copy, and the read-only stage means an in-container `gh auth login` can never overwrite your host token. **Session transcripts** live in per-workspace named volumes (mount group 6) and are never seeded from or written back to the host, and the container can't see any _other_ project's transcripts. The opt-in host-bind block in `devcontainer.json` reverses that for sessions only — enable it only if you accept transcripts on host disk; see [Session resume across container recreation](#session-resume-across-container-recreation).
-
-**The egress firewall is the key compensating control that is still missing.** It's deferred (see "What's not included (yet)" below), so a compromised package currently has unrestricted outbound network to exfiltrate anything in the read list above. Until it lands, treat that read surface as exposed to any code you run in the container — don't use this devcontainer on a machine whose host credentials you couldn't afford to rotate. The isolated-volume setup below removes host AI-CLI config/credentials from that surface entirely.
-
-**If a workspace dep is ever found compromised**, rotate credentials at the vendor side — local file deletion is insufficient because tokens may have already left:
-
- Anthropic: [console.anthropic.com → Settings → Keys](https://console.anthropic.com/settings/keys), revoke the OAuth session under Account
- OpenAI / Codex: [platform.openai.com/api-keys](https://platform.openai.com/api-keys), revoke session under Profile
- Cursor: dashboard → Integrations, rotate API key + revoke CLI session
- GitHub: `gh auth refresh` or revoke the token at github.com/settings/tokens
-
-For high-trust enterprise environments where the container should not even be able to **read** host CLI state, remove the three read-only stage binds (`/host/.claude`, `/host/.codex`, `/host/.cursor`) — plus `/host/.claude-mem` and `/host/.claude.json` — from `.devcontainer/devcontainer.json`. With no stage to copy from, `post-create.sh`'s seed and credential-sync steps quietly do nothing (their `[ -f ]` / `[ -d ]` guards), and each devcontainer starts with empty, fully isolated config and credentials (Anthropic's reference pattern). You give up seeding your host setup into the container in exchange for removing host config/credentials from the container's read surface entirely; log in inside each container instead.
-
-## First-time CLI authentication
-
-Each CLI works either way:
-
- **Log in on host first** → the container picks it up automatically on the next rebuild (`sync_from_host` copies the credential file into the named volume during `post-create.sh`). Host stays the source of truth.
- **Log in inside the container** → credentials write to the named volume. They persist across ordinary rebuilds (volume is keyed by `${devcontainerId}`, which is stable for a given workspace folder). The host's credentials are untouched.
-
-You can mix and match per-CLI. A common setup is "Claude logged in on host, Codex/Cursor logged in inside container".
-
-### Claude Code
-
-```bash
-claude login
-```
-
-Opens a browser auth flow. VS Code's port forwarding handles the OAuth callback automatically. After auth, `~/.claude/` is populated and visible from both host and container. The `DISABLE_AUTOUPDATER=1` env var prevents the in-container CLI from auto-updating — rebuild the container to pick up a newer Claude Code.
-
-### OpenAI Codex CLI
-
-```bash
-codex login --device-auth
-```
-
-The device-code flow prints a URL and a one-time code. Visit the URL on your host browser, paste the code, and the CLI authenticates without needing a callback listener — this is the most reliable path inside containers. Credentials land in `~/.codex/auth.json` (shared with host).
-
-`codex login` (browser-callback variant) also works but can be flaky in some headless contexts; prefer `--device-auth`.
-
-### Cursor CLI
-
-```bash
-cursor-agent login
-```
-
-Opens a browser auth flow; VS Code's port forwarding handles the callback. Credentials persist in `~/.cursor/cli-config.json` (shared with host).
-
-Verify any time with `cursor-agent status`.
-
-## Alternative: API key authentication (CI / headless)
-
-For non-interactive use (CI runners, automated scripts), all three CLIs accept API keys via env vars:
-
-| CLI         | Env var             | Where to get the key                          |
-| ----------- | ------------------- | --------------------------------------------- |
-| Claude Code | `ANTHROPIC_API_KEY` | <https://console.anthropic.com/settings/keys> |
-| Codex       | `OPENAI_API_KEY`    | <https://platform.openai.com/api-keys>        |
-| Cursor      | `CURSOR_API_KEY`    | Cursor dashboard → Integrations               |
-
-These env vars are intentionally **not** injected into the container from the host. `${localEnv:VAR}` resolves an unset host variable to an empty string, and some CLIs (Cursor in particular) treat a set-but-empty key as "use this key" rather than "fall back to stored login" — which would silently break the login flow for everyone who hasn't pre-set the host var.
-
-To use an API key inside the container, export it in your terminal session:
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-# or OPENAI_API_KEY, or CURSOR_API_KEY
-```
-
-For persistence across container shells, carry the export via your VS Code [dotfiles repository](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories). VS Code clones the dotfiles repo into the container on attach and runs your install command, so the export lands in `~/.bashrc` / `~/.zshrc` per your own setup — and your API keys stay out of this repo's committed `devcontainer.json`.
-
-A non-empty API key env var takes precedence over stored login credentials for each CLI.
-
-## Port forwarding
-
-| Port   | Service                          | Notes                                                                                                  |
-| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `5173` | Vite dev server (`gitnexus-web`) | Auto-forwarded with notification                                                                       |
-| `4747` | `gitnexus serve` HTTP API        | **Must not be remapped** — `gitnexus-web` hardcodes `http://localhost:4747` as the default backend URL |
-| `4173` | Static web (Vite preview)        | Silently forwarded                                                                                     |
-
-VS Code's Ports panel shows forwarded ports once their listener starts.
-
-## Known gotchas
-
- **LadybugDB integration tests may fail in containers** (file-locking, `AGENTS.md` § Testing). Default to `npm run test:unit` inside the container; run integration tests on the host. Tracking issue: documented as a known limitation.
- **Single-writer LadybugDB constraint** (`GUARDRAILS.md` § LadybugDB lock). Don't run `gitnexus analyze` on the host and inside the container against the same `.gitnexus/` directory simultaneously — the second writer will get `database busy`.
- **Native grammar builds add ~30s to first install.** Tree-sitter Dart/Proto/Swift/Kotlin are all vendored uniformly: `node-gyp-build` picks a committed GitNexus-built prebuilt `.node` at install time (no compile), and only falls back to compiling from the vendored source during `postinstall` if no prebuild matches the host (then a toolchain is needed). Set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` (in your shell or `remoteEnv`, then rebuild) to skip all four; each loses parsing for the affected language(s), and the install still succeeds.
- **`tree-sitter-kotlin`/`tree-sitter-swift` warnings on install** only appear when no prebuild matches the platform-arch (per `AGENTS.md`); they are non-fatal — parsing for that language is simply unavailable.
- **`.mcp.json` works inside the container**: `npx -y gitnexus@latest mcp` resolves cleanly because npm registry is reachable and the workspace bind mount exposes the same `.mcp.json` the host sees.
- **Husky pre-commit fires inside the container** without extra setup. The root `npm install` (run automatically in `postCreateCommand`) installs the hook via `package.json` `prepare`.
-
-## Rebuild / reset
-
- **Rebuild Container** (Command Palette) — re-runs the Dockerfile build and `postCreateCommand` against the existing named volumes (auth, history, **and sessions** persist).
- **Rebuild Container Without Cache** — fresh image layers, same volumes.
- **To force a re-login / clear an `EACCES`** — remove the per-container _config_ volumes and rebuild. As of the session-volume change this **no longer drops your `--resume` history** (sessions are on separate volumes — see [Session resume](#session-resume-across-container-recreation)):
-  ```bash
-  docker volume ls | grep -- -config-          # the credential / identity volumes
-  docker volume rm claude-config-<id> codex-config-<id> cursor-config-<id> gh-config-<id>
-  ```
-  ⚠️ Since the shareable dirs are now seeded into the config volume (not bind-mounted), wiping `<cli>-config` **also discards any plugin/skill/agent/command you installed _inside_ the container** and re-seeds those dirs from the host on the next rebuild. That is the intended way to pull host-side config changes in, but if you have in-container-only plugins you want to keep, reinstall them after the rebuild (or install them on the host first so the re-seed brings them along).
- **To also wipe session history** (a true clean slate) — remove the session volumes too (`<name>` is your workspace folder name):
-  ```bash
-  docker volume ls | grep -E -- '-(sessions|cursor-projects)-'   # the group-6 volumes
-  docker volume rm <name>-claude-sessions-<id> <name>-codex-sessions-<id> \
-                   <name>-cursor-sessions-<id> <name>-cursor-projects-<id>
-  ```
-  Then rebuild.
- **To re-seed claude-mem from the host** (the container's memory has diverged and you want the host's current store back) — remove the claude-mem volume and rebuild; `post-create.sh` copies the host store in again on the next create:
-  ```bash
-  docker volume rm claude-mem-<id>
-  ```
-
-## Bumping CLI versions
-
-Bump the version pins in `.devcontainer/devcontainer.json` `build.args` and rebuild — all three are real, fail-loud pins. Claude Code installs via `npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}` and Codex via `npm install -g @openai/codex@${CODEX_VERSION}`. **Cursor is pinned too:** bump `CURSOR_VERSION` **and** both `CURSOR_SHA256_X64` / `CURSOR_SHA256_ARM64` together — the Dockerfile downloads the pinned `downloads.cursor.com/lab/<version>/linux/<arch>/agent-cli-package.tar.gz` artifact directly (no remote install script) and fails the build on a sha256 mismatch. Re-hash each arch with `curl -fSL <url> | sha256sum`. To stop Cursor from auto-updating in the running container, don't call `cursor-agent update`.
-
-## What's not included (yet)
-
- **Egress firewall — the most important hardening still outstanding.** The original plan included an opt-in iptables/ipset firewall adapted from Anthropic's reference devcontainer. It was deferred to a follow-up PR — `runArgs` is static in `devcontainer.json`, so toggling NET_ADMIN/NET_RAW capabilities cleanly requires either a separate `devcontainer-firewall.json` profile or an `initializeCommand`-generated overlay. Until it lands, the read surface in [§ Trust boundary](#trust-boundary-concretely) has no network containment — anything readable can be exfiltrated. Track at the project's issue tracker if you need this.
- **Codespaces tuning.** The current config works in Codespaces incidentally (no privileged capabilities, no host-mount assumptions), but isn't actively tested there.
- **Playwright e2e support.** `gitnexus-web`'s `npm run test:e2e` needs Chromium libs that the base image doesn't ship. Use the host for e2e until a Playwright layer is added.
-
-## Troubleshooting
-
-| Symptom                                                                                      | Likely cause                                                                                                                           | Fix                                                                                                                                                                                                                                                                         |
-| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GitNexus devcontainer one-time Windows setup` banner from `initializeCommand`               | First-time Windows-native Reopen-in-Container; `HOME` env var was missing                                                              | The script just ran `setx HOME "%USERPROFILE%"` for you. Close ALL VS Code windows (File → Exit) and reopen — see [Windows 11 setup](#windows-11-setup)                                                                                                                     |
-| `bind source path does not exist: /.claude` (or similar) from Docker                         | Windows-native `HOME` env var is still missing even after one rebuild — `setx` may have failed or VS Code wasn't fully restarted       | Run `setx HOME "%USERPROFILE%"` in a Windows shell manually, fully exit VS Code (check Task Manager that no `Code.exe` remains), reopen                                                                                                                                     |
-| `EACCES` / `EPERM` writing into `~/.claude`, `~/.codex`, or `~/.cursor` inside the container | Stale state from a previous container with a different effective UID                                                                   | Move the affected dir aside and let the CLI rebuild it (`mv ~/.claude ~/.claude.bak` and log in again). Long-term: WSL2 setup, which doesn't hit this class of issue                                                                                                        |
-| `EPERM: operation not permitted, copyfile ... '.husky/_/h'` in `postCreateCommand`           | Leftover `.husky/_/` from a previous container run on a Windows-side bind mount                                                        | `post-create.sh` already runs `rm -rf .husky/_` defensively. If you hit this on an older config, delete `.husky/_/` on the host and rebuild. Long-term: clone in WSL2                                                                                                       |
-| Vite never hot-reloads                                                                       | Repo cloned on Windows side, not WSL2                                                                                                  | Re-clone inside WSL2                                                                                                                                                                                                                                                        |
-| `gitnexus-web` can't reach the backend                                                       | `4747` was remapped or backend isn't running                                                                                           | Verify the Ports panel shows `4747` forwarded with no remap; start the backend with `cd gitnexus && npx gitnexus serve`                                                                                                                                                     |
-| `npm install` fails on tree-sitter-swift / proto / dart                                      | Native build toolchain missing                                                                                                         | This shouldn't happen in the devcontainer — verify the apt layer installed `python3 make g++`. If iterating, set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` to skip the vendored grammars                                                                                          |
-| Integration tests fail with `database busy`                                                  | LadybugDB single-writer constraint                                                                                                     | Don't run host-side `gitnexus analyze` while the container is also analyzing the same repo; choose one writer                                                                                                                                                               |
-| API key env vars not visible inside the container                                            | They are intentionally not auto-propagated from the host (so an empty/stale host var can't silently break `*-login` for everyone else) | `export ANTHROPIC_API_KEY=...` / `OPENAI_API_KEY=...` / `CURSOR_API_KEY=...` inside the container shell, or carry it via your VS Code [dotfiles repo](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories) for persistence |
-| `git commit` produces commits with empty author                                              | `~/.gitconfig` is missing or empty on the host (VS Code's auto-copy had nothing to copy)                                               | Set `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"` from the host shell, then rebuild the container                                                                                                                      |
-| `gh: not logged in` inside the container                                                     | Not logged in on the host (nothing to seed), or the `gh-config` volume is empty                                                        | Just run `gh auth login` **inside the container** — `gh` config lives in a writable per-container volume, so the login persists across rebuilds. (Logging in on the host instead also works: it seeds in on the next container create.)                                      |
@@ -1,9 +0,0 @@
-{
-  "features": {
-    "ghcr.io/devcontainers/features/github-cli:1": {
-      "version": "1.1.0",
-      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671",
-      "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
-    }
-  }
-}
@@ -1,375 +0,0 @@
-// Devcontainer for GitNexus. It pre-installs Claude Code, the OpenAI Codex
-// CLI, and the Cursor CLI, plus the Node.js native build chain. It works on
-// macOS, Linux, Windows via WSL2, and Windows native. Windows native needs a
-// one-time HOME setup. That setup runs automatically via initializeCommand.
-// See .devcontainer/README.md § Windows 11 setup. Open it with the VS Code
-// Dev Containers extension.
-//
-// For first-time setup, auth flows, and troubleshooting, see
-// .devcontainer/README.md.
-{
-  "name": "GitNexus AI CLI Devcontainer",
-
-  "build": {
-    "dockerfile": "Dockerfile",
-    "context": ".",
-    "args": {
-      // Bun: pinned by version. Installed by the official bun.sh/install
-      // script, which accepts the release tag as its first positional arg
-      // (`bash -s bun-vX.Y.Z`). UNLIKE Cursor, the install path runs an
-      // unverified remote script — chosen at request time for simplicity.
-      // To bump: pick a tag from github.com/oven-sh/bun/releases and update
-      // this value.
-      "BUN_VERSION": "1.3.14",
-      "TZ": "${localEnv:TZ:UTC}"
-    }
-  },
-
-  // Runs on the HOST, not the container, before the container is created. We
-  // write it as a single string on purpose. The spec treats the single-string
-  // form as one command that each OS runs its own way. The object form means
-  // "named parallel tasks", not per-OS dispatch. We run it with Node so the
-  // same command works in cmd.exe on Windows and in bash/zsh on Linux, macOS,
-  // and WSL. The script reads `os.homedir()`, which respects $HOME on
-  // Linux/macOS and %USERPROFILE% on Windows. It then creates the host-side
-  // bind mount source folders, and it is safe to re-run. Host prerequisite:
-  // Node on PATH. That is the only host-side tool needed beyond Docker Desktop
-  // and the VS Code Dev Containers extension.
-  "initializeCommand": "node .devcontainer/ensure-host-config-dirs.cjs",
-
-  "features": {
-    "ghcr.io/devcontainers/features/github-cli:1": {}
-  },
-
-  "remoteUser": "node",
-  "updateRemoteUserUID": true,
-
-  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
-  "workspaceFolder": "/workspace",
-
-  // Mount topology, by group:
-  //
-  // 1. AI CLI host config — a READ-ONLY stage at /host/.<cli>. On container-
-  //    create, `post-create.sh` COPIES out of it: credentials, identity, and
-  //    single config files (always), plus the shareable subfolders (Claude
-  //    plugins/skills/agents/memory/commands; Codex plugins/prompts/memories/
-  //    skills; Cursor plugins/rules/commands/agents/skills) ONCE on first create.
-  //    Everything copied lands in the per-container named volume (role 2). It is
-  //    read-only so a container process can NEVER write back to the host — there
-  //    is no read-write bind into the host's CLI config at all. This protects the
-  //    host's on-disk setup: a compromised in-container dependency cannot drop a
-  //    skill, agent, command, or plugin onto the host for the next host session
-  //    to load. The cost is that host and container DIVERGE after the first
-  //    create — host edits don't reach the container until you wipe the config
-  //    volume and rebuild. See README § "Trust boundary, concretely".
-  //
-  // 2. AI CLI container config — one named volume per devcontainer. CODEX_HOME
-  //    points here. CLAUDE_CONFIG_DIR is left unset on purpose, so it resolves
-  //    to the default ~/.claude, which is this same path. Credentials,
-  //    identity, and single config files (.credentials.json,
-  //    ~/.claude/.claude.json, settings.json, config.toml, cli-config.json,
-  //    mcp.json) live here with correct Linux permissions. They are NOT
-  //    bind-mounted, because single-file binds break on Docker Desktop Windows
-  //    (the EXDEV error — see the SINGLE-FILE note below). Container-managed
-  //    state (sessions, history, caches, IDE locks) stays separate per
-  //    devcontainer. So two GitNexus checkouts on the same host can't corrupt
-  //    each other.
-  //
-  // 3. Other host config — read-only bind mounts for credential and identity
-  //    folders that lack the permission-flattening and onboarding-state
-  //    complications Claude Code has (ssh, aws, azure, git config, plus gh and
-  //    docker). gh and docker are read-only so a compromised dependency can't
-  //    rewrite the GitHub token or the Docker credHelper. See the inline note
-  //    at those mounts. `~/.gitconfig` is not mounted here. VS Code auto-copies
-  //    it separately.
-  //
-  // 4. Per-instance state — scoped by `${devcontainerId}`: shell history and
-  //    the npm cache. These survive rebuilds and stay separate between sibling
-  //    instances.
-  //
-  // 5. Per-workspace-name AND per-instance state — the workspace `node_modules`
-  //    volumes use both `${localWorkspaceFolderBasename}` (so you can spot them
-  //    in `docker volume ls`) and `${devcontainerId}` (so sibling instances of
-  //    the same repo never collide). This keeps tree-sitter native binaries and
-  //    onnxruntime off the workspace bind mount, which is faster on Windows and
-  //    macOS.
-  //
-  // 6. Per-workspace session state — dedicated named volumes for each CLI's
-  //    resume/transcript dirs (Claude projects/, Codex sessions/, Cursor chats/
-  //    + projects/). Same `${localWorkspaceFolderBasename}` + `${devcontainerId}`
-  //    keying as group 5, but SEPARATE volumes from the group-2 config volumes.
-  //    That separation is the point: the `docker volume rm <cli>-config-*`
-  //    re-login / EACCES fix (README § Rebuild/reset) no longer wipes sessions,
-  //    so `claude --resume`, `codex resume`, and `cursor-agent resume` survive a
-  //    rebuild, a full delete-and-recreate, AND that wipe. They overlay the
-  //    config volume at the session sub-paths (Docker precedence: more specific
-  //    path wins). Container-private by design — transcripts can hold pasted
-  //    secrets, and like the group-1 config (read-only stage, copy-once) these
-  //    add NO host write-through surface and leak no other projects' transcripts.
-  //    They do
-  //    NOT survive `docker volume prune`, a `${devcontainerId}` change (moving
-  //    the checkout, WSL vs native), or a new machine — same tier as group 5.
-  //    To make sessions host-visible/portable instead, see the commented
-  //    host-bind block below and README § "Session resume across recreation".
-  "mounts": [
-    // One named volume per container for credentials and identity state. Each
-    // CLI's real `~/.<cli>` config folder lives in a volume. That keeps
-    // credentials (with correct Linux 600 permissions) and per-container
-    // session state separate from the host. Logging in inside the container
-    // and logging in on the host are independent. The bind mounts BELOW these
-    // volumes override the volume's contents at the paths they cover. Docker
-    // mount precedence is: the more specific path wins.
-    "source=claude-config-${devcontainerId},target=/home/node/.claude,type=volume",
-    "source=codex-config-${devcontainerId},target=/home/node/.codex,type=volume",
-    "source=cursor-config-${devcontainerId},target=/home/node/.cursor,type=volume",
-
-    // gh CLI config as a per-container named volume, same model as the AI CLI
-    // configs above: post-create.sh COPIES hosts.yml/config.yml out of the
-    // read-only /host/.config/gh stage into this volume on container-create.
-    // The container then owns a WRITABLE copy, so `gh auth login` /
-    // `gh auth refresh` run INSIDE the container persist across rebuilds — and
-    // still never write back to the host (the stage is read-only). If the host
-    // is logged in, that login seeds in; if not, an in-container login sticks.
-    "source=gh-config-${devcontainerId},target=/home/node/.config/gh,type=volume",
-
-    // claude-mem store. UNLIKE the shareable dirs below (skills/agents/memory),
-    // this is NOT a host bind. $HOME/.claude-mem is a large, multi-GB SQLite +
-    // Chroma vector store (claude-mem.db + -wal/-shm, chroma/chroma.sqlite3, HNSW
-    // index binaries). A read-write host bind would (a) push every byte over the
-    // 9p/virtiofs share, and (b) expose those SQLite WAL files to unreliable
-    // fcntl locking across that boundary — with a real corruption risk if
-    // claude-mem ran on the host and in the container against the same DB at
-    // once. So it gets its OWN per-container named volume here, same durability
-    // tier as the config volumes (survives Rebuild Container and a
-    // delete-and-recreate; keyed by ${devcontainerId}). post-create.sh SEEDS it
-    // ONCE from the /host/.claude-mem read-only stage when the volume is empty,
-    // then the container owns its copy — rebuilds never clobber it, and changes
-    // do NOT flow back to the host. (Container and host memory diverge from the
-    // seed point on; that is the price of safe SQLite.) Removed by the same
-    // `docker volume rm` reset flow as the other volumes — see README.
-    "source=claude-mem-${devcontainerId},target=/home/node/.claude-mem,type=volume",
-
-    // Per-workspace SESSION volumes (mount group 6). These OVERLAY the config
-    // volumes above at the session sub-paths so "resume my last session"
-    // survives container recreation the way the seeded config dirs do.
-    // They are SEPARATE volumes from <cli>-config-${devcontainerId}, so the
-    // README's `docker volume rm <cli>-config-${devcontainerId}` re-login fix
-    // does not touch them. post-create.sh chowns each one explicitly (its
-    // `find -xdev` stops at the config-volume filesystem boundary and won't
-    // descend into these).
-    //
-    // KEEP IN SYNC: if you add/rename/remove a session sub-path, update all
-    // three places that name it — (1) the mount line here, (2) the DIRS array
-    // in post-create.sh (so its chown covers the volume), and (3) the mount
-    // table + Session-resume section in README.md.
-    //
-    // Claude: projects/ holds <encoded-cwd>/<uuid>.jsonl transcripts plus the
-    // sessions-index.json that the `/resume` picker reads. The container cwd is
-    // always /workspace (encodes to the `-workspace` subdir), so this is the
-    // container's own slice only. Pure JSONL/JSON — no SQLite/WAL, so a volume
-    // here is clean. `claude --resume` / `--continue` read straight from it.
-    "source=${localWorkspaceFolderBasename}-claude-sessions-${devcontainerId},target=/home/node/.claude/projects,type=volume",
-    // Codex: sessions/ holds YYYY/MM/DD/rollout-*.jsonl transcripts. The thread
-    // index (state_5.sqlite + -wal/-shm) stays at the ~/.codex root on the
-    // config volume — it is a single WAL file we must NOT split onto a host
-    // bind. On a recreation that drops the config volume, that index is cleanly
-    // absent and Codex rebuilds it from these rollout files on the next start
-    // (backfill). See README for the one-time-rebuild and corruption caveats.
-    "source=${localWorkspaceFolderBasename}-codex-sessions-${devcontainerId},target=/home/node/.codex/sessions,type=volume",
-    // Cursor: chats/{hash}/{uuid}/store.db is one SQLite db per session, each in
-    // its own leaf dir — a DIRECTORY volume keeps each db beside its -wal/-shm
-    // sidecar, so there is no cross-filesystem single-file hazard. projects/
-    // (agent-transcripts) is added too. cursor-agent's on-disk layout is
-    // community-reverse-engineered (LOW confidence), so this is best-effort;
-    // keeping it container-private means a wrong guess can't corrupt host state.
-    "source=${localWorkspaceFolderBasename}-cursor-sessions-${devcontainerId},target=/home/node/.cursor/chats,type=volume",
-    "source=${localWorkspaceFolderBasename}-cursor-projects-${devcontainerId},target=/home/node/.cursor/projects,type=volume",
-    //
-    // OPT-IN: host-shared sessions (like the plugin/skill binds). Uncomment to
-    // put transcripts on the host — fully visible and portable, but they then
-    // land on host disk and become a write-through surface for a compromised
-    // in-container dependency, and the whole-dir binds expose OTHER projects'
-    // transcripts to the container. Claude is scoped to /workspace's encoded
-    // subdir to limit that leak; Codex/Cursor stores are not project-scoped, so
-    // they expose every project. If you enable these, also add the matching
-    // source dirs to ensure-host-config-dirs.cjs — to its DIRS array (these are
-    // directory binds), not FILES (which is only for single-file bind sources
-    // like ~/.claude.json) — so Docker can resolve the binds. Read README
-    // § "Session resume across recreation" first.
-    //   "source=${localEnv:HOME}/.claude/projects/-workspace,target=/home/node/.claude/projects/-workspace,type=bind",
-    //   "source=${localEnv:HOME}/.codex/sessions,target=/home/node/.codex/sessions,type=bind",
-    //   "source=${localEnv:HOME}/.cursor/chats,target=/home/node/.cursor/chats,type=bind",
-    //   "source=${localEnv:HOME}/.cursor/projects,target=/home/node/.cursor/projects,type=bind",
-
-    // Read-only host stage that post-create.sh copies FROM on container-create.
-    // It is read-only so a container process can never write back to host CLI
-    // state — that write-back is the attack vector we block. post-create.sh
-    // reads two kinds of thing from here: (a) the credential + identity files
-    // (copied into the volume always), and (b) the shareable dirs — skills,
-    // agents, plugins, memory, commands, prompts, rules — which it copies into
-    // the volume ONCE on first create (see step 3/4). Nothing here is bound
-    // read-write into the container, so the host's on-disk setup is protected.
-    "source=${localEnv:HOME}/.claude,target=/host/.claude,type=bind,readonly",
-    "source=${localEnv:HOME}/.codex,target=/host/.codex,type=bind,readonly",
-    "source=${localEnv:HOME}/.cursor,target=/host/.cursor,type=bind,readonly",
-    // Read-only host stage for the claude-mem store. post-create.sh COPIES it
-    // into the claude-mem named volume on first create (seed-once). Read-only so
-    // the container can never write back to the host's live DB — the seed is a
-    // one-way snapshot. ensure-host-config-dirs.cjs creates ~/.claude-mem on the
-    // host so this bind resolves even when claude-mem was never installed there.
-    "source=${localEnv:HOME}/.claude-mem,target=/host/.claude-mem,type=bind,readonly",
-
-    // NO read-write bind mounts for the shareable subfolders. They USED to be
-    // bound here (Claude skills/agents/memory/commands/plugins; Codex plugins/
-    // prompts/memories/skills; Cursor rules/commands/agents/skills/plugins) so
-    // host and container shared one copy both ways. That bind was a write-through
-    // hole: a compromised in-container dependency could drop a malicious skill,
-    // agent, command, or plugin straight onto the host, which the next HOST
-    // session would auto-load. To protect the host's on-disk setup, these are
-    // now COPIED once from the read-only /host/.<cli> stage into the per-container
-    // named volume by post-create.sh (step 3/4), exactly like claude-mem and the
-    // session volumes. Trade-offs of the copy model:
-    //   - The container gets its OWN writable copy and can never write back to
-    //     the host. Host setup is protected.
-    //   - It is seed-ONCE: host edits made after first create don't reach the
-    //     container until you remove the config volume and rebuild. Container
-    //     edits persist across rebuilds. (See README § Rebuild/reset to re-seed.)
-    //   - The plugin REGISTRY JSONs (Claude known_marketplaces.json /
-    //     installed_plugins.json / plugin-catalog-cache.json; Cursor
-    //     installed_plugins.json) carry absolute OS-native paths, so they can't
-    //     be copied verbatim — post-create.sh translates their paths to the
-    //     container's Linux paths, also seed-once, alongside the cache/ copy so
-    //     the two stay consistent. Codex needs no translation (config.toml holds
-    //     git URLs, not paths), so its whole plugins/ dir is copied as-is.
-    //   - The old read-only-stage-plus-symlink design failed `/plugin marketplace
-    //     add` in the container with EROFS; copy-into-a-writable-volume avoids
-    //     that — the container writes to its own copy, not a read-only mount.
-    //
-    // SINGLE-FILE binds for settings.json, .claude.json, and config.toml are
-    // deliberately ABSENT. On Docker Desktop Windows the named volume sits on
-    // one filesystem (ext4, /dev/sdd) and a single-file bind from the host sits
-    // on another (the 9p drvfs share). Apps save a config by writing `foo.tmp`
-    // and renaming it over `foo`. That rename can't cross filesystems: it hits
-    // the EXDEV error and fails with `Device or resource busy` or `inter-device
-    // move failed`. Codex's TUI shows this as "config/batchWrite failed in
-    // TUI"; Claude just silently loses the write the same way. Instead, we use
-    // a read-only host stage at /host/.claude, and post-create.sh copies these
-    // files into the named volume on every container-create. Host changes show
-    // up on the next rebuild. Container changes stay inside the container until
-    // a rebuild.
-    "source=${localEnv:HOME}/.claude.json,target=/host/.claude.json,type=bind,readonly",
-    "source=${localEnv:HOME}/.config/git,target=/home/node/.config/git,type=bind,readonly",
-    "source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,readonly",
-    // gh uses the COPY-INTO-VOLUME model (read-only host stage at
-    // /host/.config/gh + the gh-config named volume above). post-create.sh seeds
-    // hosts.yml/config.yml from this stage into the volume on create, so the
-    // container has a writable copy: an in-container `gh auth login` persists
-    // across rebuilds, and nothing is ever written back to the host because this
-    // stage is read-only. docker stays a direct READ-ONLY bind: the container
-    // reads your EXISTING host login (the common case), and a compromised
-    // in-container dependency can't rewrite ~/.docker/config.json (the registry
-    // credHelper, which points at a binary). A `docker login` run inside the
-    // container won't persist back to the host — re-run it on the host, or give
-    // docker the same copy-into-volume treatment as gh. See README § Trust boundary.
-    "source=${localEnv:HOME}/.config/gh,target=/host/.config/gh,type=bind,readonly",
-    "source=${localEnv:HOME}/.docker,target=/home/node/.docker,type=bind,readonly",
-    "source=${localEnv:HOME}/.aws,target=/home/node/.aws,type=bind,readonly",
-    "source=${localEnv:HOME}/.azure,target=/home/node/.azure,type=bind,readonly",
-    "source=commandhistory-${devcontainerId},target=/commandhistory,type=volume",
-    "source=npm-cache-${devcontainerId},target=/home/node/.npm,type=volume",
-    "source=${localWorkspaceFolderBasename}-root-node-modules-${devcontainerId},target=/workspace/node_modules,type=volume",
-    "source=${localWorkspaceFolderBasename}-gitnexus-node-modules-${devcontainerId},target=/workspace/gitnexus/node_modules,type=volume",
-    "source=${localWorkspaceFolderBasename}-gitnexus-web-node-modules-${devcontainerId},target=/workspace/gitnexus-web/node_modules,type=volume",
-    "source=${localWorkspaceFolderBasename}-gitnexus-shared-node-modules-${devcontainerId},target=/workspace/gitnexus-shared/node_modules,type=volume"
-  ],
-
-  // Interactive login is the default way to authenticate for all three CLIs.
-  // Credentials live in the per-container named volumes (claude-config,
-  // codex-config, cursor-config), NOT in the host bind mounts. They are copied
-  // from the read-only /host/.<cli> stage into the volume on container-create.
-  // Single-file binds would break on Docker Desktop Windows (the EXDEV error).
-  // Shareable content (plugins, skills, agents, memory, commands) is NOT bound
-  // read-write — it is copied once from the read-only /host/.<cli> stage into
-  // the volume on first create, so the host's on-disk setup stays protected.
-  // API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, CURSOR_API_KEY) are NOT
-  // injected via containerEnv. `${localEnv:VAR}` turns an unset host var into
-  // an empty string. Cursor in particular treats `CURSOR_API_KEY=""` as "use
-  // this empty key" instead of "fall back to the stored login", which would
-  // silently break `cursor-agent login`. If you need API-key auth, `export`
-  // the var in your container shell, or carry it in your VS Code dotfiles repo
-  // (see .devcontainer/README.md).
-  // CLAUDE_CONFIG_DIR is left unset on purpose. The Claude default is
-  // `$HOME/.claude` (= `/home/node/.claude`), which is exactly where the
-  // claude-config named volume mounts. Setting the env var would change which
-  // file Claude reads `hasCompletedOnboarding` from. With the var set, Claude
-  // reads `$CLAUDE_CONFIG_DIR/.claude.json`, the small identity file. Without
-  // it, Claude reads `$HOME/.claude.json`, the big onboarding-state file that
-  // actually holds `hasCompletedOnboarding`, the user-scope MCP config, and
-  // per-project trust. Leaving the var unset matches host behavior. It also
-  // lets post-create.sh's sync of `$HOME/.claude.json` skip the setup wizard
-  // on every container-create.
-  //
-  // CODEX_HOME is kept even though it matches the Codex default, as a canary.
-  // If we ever move the Codex named volume target, this env var makes the
-  // dependency explicit instead of silently following the default.
-  "containerEnv": {
-    "CODEX_HOME": "/home/node/.codex",
-    "HISTFILE": "/commandhistory/.zsh_history"
-  },
-
-  "customizations": {
-    "vscode": {
-      "extensions": [
-        "anthropic.claude-code",
-        "dbaeumer.vscode-eslint",
-        "esbenp.prettier-vscode",
-        "eamodio.gitlens"
-      ],
-      "settings": {
-        "editor.formatOnSave": true,
-        "editor.defaultFormatter": "esbenp.prettier-vscode",
-        "editor.codeActionsOnSave": {
-          "source.fixAll.eslint": "explicit"
-        },
-        "files.eol": "\n",
-        "terminal.integrated.defaultProfile.linux": "zsh",
-        "terminal.integrated.profiles.linux": {
-          "bash": { "path": "bash", "icon": "terminal-bash" },
-          "zsh": { "path": "zsh" }
-        }
-      }
-    }
-  },
-
-  // Do not remap port 4747 (gitnexus serve). gitnexus-web hardcodes
-  // http://localhost:4747 as its default backend URL.
-  "forwardPorts": [5173, 4747, 4173],
-  "portsAttributes": {
-    "5173": {
-      "label": "Vite dev (gitnexus-web)",
-      "onAutoForward": "notify"
-    },
-    "4747": {
-      "label": "gitnexus serve HTTP API",
-      "onAutoForward": "notify",
-      "requireLocalPort": true
-    },
-    "4173": {
-      "label": "Static web (Vite preview)",
-      "onAutoForward": "silent"
-    }
-  },
-
-  // Lifecycle split (from the Dev Container spec):
-  // - `updateContentCommand` runs on container-create AND whenever the
-  //   workspace content changes, such as a lockfile update. It owns installing
-  //   the workspace dependencies. Re-installing on every container-create
-  //   wastes time when nothing changed, but it must re-run when deps change.
-  // - `postCreateCommand` runs once on container-create. It owns syncing the
-  //   AI CLI credentials and identity from the host. That work should happen
-  //   exactly once per container instance, not on every content update.
-  // Run both with an explicit `bash` so they don't depend on the script's
-  // executable bit surviving the workspace bind mount.
-  "updateContentCommand": "bash .devcontainer/install-deps.sh",
-  "postCreateCommand": "bash .devcontainer/post-create.sh"
-}
@@ -1,149 +0,0 @@
-// This runs on the HOST, not inside the container, before the dev container is
-// created. devcontainer.json calls it via `initializeCommand`. Its job is to
-// make sure the bind-mount source folders listed in devcontainer.json already
-// exist on the host. Docker rejects a bind mount when its source is missing,
-// which happens if a CLI has never been used.
-//
-// It works on every platform. `os.homedir()` returns the home folder ($HOME on
-// Mac/Linux, %USERPROFILE% on Windows). `fs.mkdirSync({recursive: true})`
-// creates folders. It is safe to run repeatedly: a path that already exists is
-// left alone. We deliberately do NOT handle `~/.gitconfig` here. VS Code's Dev
-// Containers extension copies the host gitconfig into the container when you
-// attach, and a bind mount fights with that, so it was removed.
-//
-// The path-creating logic is exported (ensurePaths/DIRS/FILES) so tests can use
-// it. The Windows HOME side effect only runs when this file is run directly as
-// the initializeCommand. That keeps tests able to drive it against a temp dir
-// without touching the real home or calling `setx`.
-//
-// Host prerequisite: Node.js must be on PATH. That is the only host requirement
-// beyond Docker Desktop and the VS Code Dev Containers extension. Everything
-// else runs inside the container.
-
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-// Folders that are bind-mount sources in devcontainer.json. Docker rejects a
-// bind mount whose source is missing, so we create each one.
-//
-// We create the TOP per-CLI folders (~/.claude, ~/.codex, ~/.cursor) and
-// ~/.claude-mem. These back the /host/.<cli> and /host/.claude-mem read-only
-// STAGE mounts that post-create.sh copies from on container-create. We do NOT
-// create the shareable subfolders (skills/agents/plugins/memory/commands/...)
-// here anymore: they used to be read-write bind sources, but they are now
-// copied once out of the read-only stage into the per-container volume, so they
-// are no longer bind sources and pre-creating empty ones would needlessly write
-// into the host of someone who never used that CLI. post-create.sh's seed step
-// simply skips any subfolder the host doesn't have. The read-only stage bind is
-// the whole ~/.<cli> dir, so whatever shareable subfolders DO exist are visible
-// to the seed without being listed here.
-const DIRS = [
-  '.claude',
-  // claude-mem store ($HOME/.claude-mem). A SEPARATE top-level folder from
-  // ~/.claude, holding claude-mem's SQLite DB + Chroma vector store. It is NOT
-  // bind-mounted (a multi-GB SQLite/WAL store is unsafe over a 9p bind on Docker
-  // Desktop Windows). post-create.sh SEEDS it once into a per-container named
-  // volume from the /host/.claude-mem read-only stage. We create the source here
-  // so that stage bind resolves even for a host that never ran claude-mem
-  // (Docker rejects a missing bind source); the seed then finds no DB to copy
-  // and the container starts with empty memory.
-  '.claude-mem',
-  '.codex',
-  '.cursor',
-  '.ssh',
-  '.docker',
-  '.aws',
-  '.azure',
-  path.join('.config', 'gh'),
-  path.join('.config', 'git'),
-];
-
-// Files to pre-create. Only `~/.claude.json` is created here. It is the one
-// source that is bound as a single file (read-only at /host/.claude.json). If
-// that source is missing, Docker would create a FOLDER in its place, so it has
-// to exist as a file first. `~/.claude/settings.json` and
-// `~/.codex/config.toml` are NOT single-file binds. post-create.sh copies them
-// out of the /host/.<cli> read-only folder stage, and `sync_from_host` simply
-// does nothing when they are absent (the `[ -f ]` guard). Creating them here
-// would needlessly write to the host of someone who never ran that CLI, so we
-// don't.
-const FILES = ['.claude.json'];
-
-// Create every folder and touch every file under `home`. Safe to run again:
-// an existing path is left untouched. The root is a parameter so tests can run
-// it against a temp dir.
-function ensurePaths(home, dirs = DIRS, files = FILES) {
-  for (const dir of dirs) {
-    const full = path.join(home, dir);
-    if (!fs.existsSync(full)) {
-      fs.mkdirSync(full, { recursive: true });
-    }
-  }
-  for (const file of files) {
-    const full = path.join(home, file);
-    if (!fs.existsSync(full)) {
-      fs.closeSync(fs.openSync(full, 'a'));
-    }
-  }
-}
-
-module.exports = { ensurePaths, DIRS, FILES };
-
-if (require.main === module) {
-  // One-time setup for native Windows. VS Code fills in the bind-mount sources
-  // using `${localEnv:HOME}`, which reads its own process environment. Windows
-  // does not set `HOME` by default; it uses `USERPROFILE`. With no `HOME`, the
-  // bind sources shrink to filesystem-root paths (`/.claude`, `/.codex`, ...)
-  // and Docker rejects them with `bind source path does not exist`.
-  //
-  // The fix is to save `HOME=%USERPROFILE%` into the user's environment with
-  // `setx`. `setx` writes to `HKCU\Environment`. Every process the user starts
-  // after that inherits the new value, including VS Code once it restarts. The
-  // current VS Code process can't see the change, because its environment was
-  // set when it launched. So we tell the user to restart VS Code once.
-  //
-  // Later runs see that `HOME` is set, skip this block, and continue normally.
-  // Mac, Linux, and WSL hosts already have `HOME` set by the shell, so this
-  // block does nothing on those platforms.
-  if (process.platform === 'win32' && !process.env.HOME) {
-    const userprofile = process.env.USERPROFILE;
-    if (userprofile) {
-      try {
-        require('child_process').execFileSync('setx', ['HOME', userprofile], {
-          stdio: 'ignore',
-        });
-        console.error('');
-        console.error('='.repeat(70));
-        console.error(' GitNexus devcontainer one-time Windows setup');
-        console.error('='.repeat(70));
-        console.error('');
-        console.error(`HOME has been set to %USERPROFILE% (${userprofile}).`);
-        console.error("VS Code reads this at startup, so the current session can't pick it up.");
-        console.error('');
-        console.error(' 1. Close ALL VS Code windows (File > Exit, not just the window).');
-        console.error(' 2. Reopen VS Code, open this folder, and re-run Reopen in Container.');
-        console.error('');
-        console.error('This is a one-time setup. Subsequent rebuilds work normally.');
-        console.error('='.repeat(70));
-        process.exit(1);
-      } catch (err) {
-        console.error('ERROR: failed to set HOME automatically: ' + err.message);
-        console.error('');
-        console.error('Run this in a Windows shell, then restart VS Code:');
-        console.error('  setx HOME "%USERPROFILE%"');
-        process.exit(1);
-      }
-    } else {
-      console.error('ERROR: neither HOME nor USERPROFILE is set on this host.');
-      console.error('');
-      console.error('Set HOME to your user profile directory and restart VS Code:');
-      console.error('  setx HOME "%USERPROFILE%"');
-      process.exit(1);
-    }
-  }
-
-  ensurePaths(os.homedir());
-}
@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-# Devcontainer updateContentCommand. The Dev Container spec runs this when the
-# container is created AND whenever workspace content changes (for example a
-# lockfile update). This script installs workspace dependencies only. Syncing AI
-# CLI state lives in post-create.sh, which runs once right after this.
-#
-# Why the split: updateContentCommand re-runs on content changes, but
-# postCreateCommand runs only at container-create. Keeping `npm install` here
-# means a rebuild after pulling new dependencies refreshes them. The AI CLI
-# credential and path-translation work does not re-run each time.
-
-set -euo pipefail
-cd /workspace
-
-echo "[install-deps] 1/4: chown workspace node_modules + npm cache mount points"
-# The named volumes (workspace/*/node_modules and ~/.npm) are created at first
-# mount. They inherit ownership from the image's UID before realignment. Then
-# `updateRemoteUserUID: true` shifts the `node` user's UID. Now the volumes are
-# owned by the old, stale UID and npm install cannot write to them. So we chown
-# again here, after realignment. Running it again later changes nothing.
-#
-# We use `find -xdev -exec chown -h` (the same idiom as post-create.sh) instead
-# of a plain `chown -R`. There are two separate guards. First, `-xdev` stops
-# find from descending past each volume's own filesystem, so it won't recurse
-# into a host folder mounted underneath. Second, `-h` makes chown change the
-# symlink itself instead of following it to its target. Without `-h`, a symlink
-# in the tree (one a dependency's postinstall drops, or a dangling
-# node_modules/.bin link) would either send the chown onto a target on another
-# filesystem, or fail to follow and abort the whole script under `set -e`. For
-# regular files and directories `-h` does nothing, so the ownership fix is the
-# same.
-for d in /workspace/node_modules \
-         /workspace/gitnexus/node_modules \
-         /workspace/gitnexus-web/node_modules \
-         /workspace/gitnexus-shared/node_modules \
-         /home/node/.npm; do
-    sudo find "$d" -xdev -exec chown -h node:node {} +
-done
-
-echo "[install-deps] 2/4: clear stale .husky/_ runtime cache"
-# On Docker Desktop for Windows, the bind-mount permission translation won't let
-# the new container's `node` user overwrite a `.husky/_/h` file that an earlier
-# container wrote under a different UID. So we delete it. `.husky/_` is a
-# gitignored runtime cache, and husky rebuilds it during the root `npm install`.
-# Husky upstream has no fix for this UID clash.
-rm -rf .husky/_
-
-echo "[install-deps] 3/4: npm install at root, then gitnexus-shared (build required)"
-# Install order matters. Root goes first, for lint-staged, husky, and prettier.
-# Then gitnexus-shared, which must be built before installing gitnexus-web or
-# gitnexus. Both of those depend on it via `file:../gitnexus-shared`.
-npm install
-cd /workspace/gitnexus-shared
-npm install
-npm run build
-
-echo "[install-deps] 4/4: npm install gitnexus-web, then gitnexus"
-# gitnexus-web goes before gitnexus. The gitnexus `prepare` script runs
-# scripts/build.js, which compiles gitnexus-web when that directory is present.
-# In the devcontainer the whole workspace is bind-mounted, so gitnexus-web/ is
-# present when gitnexus installs. The production Dockerfiles COPY only selected
-# files, so the directory is not present there.
-cd /workspace/gitnexus-web
-npm install
-cd /workspace/gitnexus
-npm install
-
-echo "[install-deps] done"
@@ -1,307 +0,0 @@
-#!/usr/bin/env bash
-# Devcontainer postCreate script. It runs once, right after the container is
-# created. devcontainer.json wires it up via `postCreateCommand`. Workspace
-# dependencies are installed elsewhere, in install-deps.sh (`updateContentCommand`).
-# That script runs BEFORE this one — that is the order the devcontainer spec
-# defines. This script does one job: sync the AI CLI credentials and identity
-# from the host.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-echo "[post-create] 1/4: chown AI CLI named-volume mount points"
-# Fix ownership on the named volumes (~/.claude, ~/.codex, ~/.cursor,
-# /commandhistory). When they first mount, they take the user ID baked into the
-# image, before any realignment. Then `updateRemoteUserUID: true` shifts the
-# `node` user to a new ID. Now the volumes are owned by the old, stale ID, and
-# writes into them fail. (~/.local is a directory in the image, not a volume.
-# We chown it too, just to be safe.) install-deps.sh fixes the workspace side.
-# This script fixes the AI CLI side, so each lifecycle hook handles its own part.
-#
-# There are two separate guards here, and they do different things. `-xdev`
-# keeps find from descending into other filesystems. The shareable dirs (skills,
-# agents, plugins, memory, commands, prompts, rules) are no longer host bind
-# mounts — they now live INSIDE the config volume (seeded in step 3/4), so
-# `-xdev` correctly walks and chowns them as the container-private volume files
-# they are. What `-xdev` still stops at are the SESSION volumes (mount group 6),
-# which remain separate filesystems mounted at sub-paths (see below). `-h` tells
-# chown to act on a symlink ITSELF instead of following it, so it never lands on
-# a target across a filesystem boundary and never aborts on a broken symlink
-# under `set -e` (a legacy Option-B symlink could still exist on a carried-over
-# volume). For regular files and directories `-h` does nothing extra.
-#
-# The session volumes (mount group 6: .claude/projects, .codex/sessions,
-# .cursor/chats, .cursor/projects) are their OWN filesystems mounted at
-# sub-paths, so `-xdev` rooted at the config-volume parent deliberately skips
-# them. That is why each one is listed as its own root below: rooted there,
-# `-xdev` walks just that volume and chowns its top level, so the CLI's first
-# write doesn't hit EACCES on a stale image UID. These are container-private
-# volumes, not the host's own files — the read-only /host/.<cli> stages we copy
-# from are mounted elsewhere and are never chowned.
-DIRS=(
-    /home/node/.claude
-    /home/node/.claude/projects
-    /home/node/.codex
-    /home/node/.codex/sessions
-    /home/node/.cursor
-    /home/node/.cursor/chats
-    /home/node/.cursor/projects
-    /home/node/.config/gh
-    /home/node/.local
-    /commandhistory
-)
-# claude-mem volume: chown it ONLY on first create (its completion sentinel is
-# absent). The step-4/4 seed copies the store as the node user, so a populated
-# claude-mem volume is already node-owned on every later rebuild — a recursive
-# `find` over a multi-GB store (the 7GB+ DB plus the Chroma index) just to
-# re-stamp ownership that is already correct would add real latency to every
-# rebuild for nothing. On first create the volume is empty, so this chown of the
-# bare mount point is trivial and lets the seed write into it.
-[ -f /home/node/.claude-mem/.claude-mem-seeded ] || DIRS+=(/home/node/.claude-mem)
-for d in "${DIRS[@]}"; do
-    # Skip a root that isn't present rather than aborting the whole run under
-    # `set -e`. Docker creates every declared volume's mount point before this
-    # script runs, so in the normal case all roots exist and this is a no-op.
-    # The guard matters only if a session volume is later removed from
-    # devcontainer.json without its matching DIRS entry being removed too — then
-    # provisioning skips it instead of failing before credentials ever sync.
-    [ -d "$d" ] || continue
-    sudo find "$d" -xdev -exec chown -h node:node {} +
-done
-
-echo "[post-create] 2/4: sync AI CLI credentials + identity from host"
-# Clean up after an older devcontainer design (Option B). Back then these paths
-# were symlinks pointing into the read-only host stage
-# (e.g. /home/node/.claude/plugins -> /host/.claude/plugins). A write through
-# such a symlink would land on a read-only host file and fail. Delete any that
-# survive on a carried-over volume. The shareable dirs are now real directories
-# in the named volume, seeded from the host in step 3/4 below.
-for p in plugins skills agents memory commands; do
-    [ -L "/home/node/.claude/$p" ] && rm "/home/node/.claude/$p"
-done
-for p in plugins prompts memories skills config.toml; do
-    [ -L "/home/node/.codex/$p" ] && rm "/home/node/.codex/$p"
-done
-for p in plugins rules commands agents skills; do
-    [ -L "/home/node/.cursor/$p" ] && rm "/home/node/.cursor/$p"
-done
-mkdir -p /home/node/.claude/plugins /home/node/.cursor/plugins
-
-# Shareable content (skills, agents, plugins, memory, commands, prompts, rules)
-# is NO LONGER bind-mounted. It is COPIED once from the read-only host stage into
-# the named volume in step 3/4 below, so a compromised in-container dependency
-# can't write through to the host's on-disk CLI setup. This step handles only the
-# credentials, identity, and single config files. Those stay per-container in the
-# named volume and are COPIED from the host once when the container is created:
-#   - .credentials.json (Claude OAuth tokens)
-#   - .claude/.claude.json (Claude identity: userID, oauthAccount, and
-#     migration tracking — a different file from $HOME/.claude.json)
-#   - settings.json (Claude), config.toml (Codex), mcp.json (Cursor). These are
-#     single config files, and single files can't be bind-mounted on Windows
-#     (the EXDEV error explained below).
-#   - auth.json (Codex), cli-config.json (Cursor — which mixes auth and settings)
-#   - the plugin registry JSONs that contain absolute paths (Claude + Cursor).
-#     Those are translated below.
-#
-# How the sync behaves: it ALWAYS overwrites from the host when the container is
-# created. A fresh container then starts logged in as the host's user, if the
-# host had credentials. From that point the container manages its own login,
-# until the next rebuild copies the host files again. Logging out inside the
-# container does NOT log out the host. Per-container login is the goal, and
-# bind-mounting these files would instead make a logout shared between both.
-
-sync_from_host() {
-    local src=$1
-    local dst=$2
-    local mode=${3:-600}
-    if [ -f "$src" ]; then
-        rm -f "$dst"
-        cp "$src" "$dst"
-        chmod "$mode" "$dst"
-    fi
-}
-
-sync_from_host \
-    /host/.claude/.credentials.json /home/node/.claude/.credentials.json
-sync_from_host \
-    /host/.claude/.claude.json /home/node/.claude/.claude.json 644
-
-# These config files are COPIED from the host, not bind-mounted. We tried
-# bind-mounting them as single files and it didn't work. On Docker Desktop for
-# Windows the named volume (ext4) and the host bind mount (9p drvfs) are
-# different filesystems. Apps save a config by writing a temp file and renaming
-# it over the real one, and that rename fails across filesystems (the "EXDEV" or
-# "Device or resource busy" error). So copy the host's version into the named
-# volume when the container is created. The container can then rewrite it freely
-# until the next rebuild copies the host version again.
-sync_from_host /host/.claude/settings.json /home/node/.claude/settings.json 644
-sync_from_host /host/.codex/config.toml   /home/node/.codex/config.toml   644
-
-# Seed $HOME/.claude.json from the host, but NOT as a straight copy. That file
-# mixes two kinds of state. Some is portable account and onboarding state we
-# want to keep: hasCompletedOnboarding, oauthAccount, userID, projects,
-# tipsHistory. The rest describes how Claude is installed on the HOST, and that
-# part is never valid here — for example the host's `installMethod` value only
-# makes sense for the host's binary. The fix strips the machine-specific fields
-# and forces hasCompletedOnboarding, while handling a host file that isn't a
-# JSON object. That logic lives in seed-claude-config.cjs so it can be
-# unit-tested and prettier-checked (translate-plugin-registries.test.cjs).
-node "$SCRIPT_DIR/seed-claude-config.cjs"
-
-# Codex auth. Some hosts store credentials in the OS keyring instead of on disk
-# (`cli_auth_credentials_store = "keyring"`, the default on macOS). Those hosts
-# have no auth.json file, so the copy below quietly does nothing. In that case,
-# log in inside the container with `codex login --device-auth`.
-sync_from_host \
-    /host/.codex/auth.json /home/node/.codex/auth.json
-
-# Cursor CLI. Its cli-config.json holds both auth and settings in one file.
-# Cursor has known upstream problems authenticating inside Docker, even when the
-# config is copied correctly. If `cursor-agent` reports auth errors after the
-# copy, run `cursor-agent login` again inside the container. mcp.json (Cursor's
-# MCP server config) is also a single file, so it is copied on create rather
-# than bind-mounted, for the same EXDEV reason as above. hooks.json is left out
-# on purpose. Cursor hooks run shell commands, and sharing the host's hooks
-# would widen the supply-chain attack surface inside the container. Copy it in
-# yourself if you want the host's hooks in the container.
-sync_from_host \
-    /host/.cursor/cli-config.json /home/node/.cursor/cli-config.json
-sync_from_host \
-    /host/.cursor/mcp.json /home/node/.cursor/mcp.json 644
-
-# gh CLI auth + settings. Same copy-into-volume model as the credentials above:
-# hosts.yml holds the GitHub token (mode 600), config.yml holds settings (644).
-# Copied from the read-only /host/.config/gh stage into the gh-config named
-# volume on create. Because the volume is writable, an in-container
-# `gh auth login` / `gh auth refresh` persists across rebuilds; because the
-# stage is read-only, nothing flows back to the host. If the host had no login,
-# both copies quietly no-op and whatever the container wrote is kept.
-sync_from_host /host/.config/gh/hosts.yml  /home/node/.config/gh/hosts.yml
-sync_from_host /host/.config/gh/config.yml /home/node/.config/gh/config.yml 644
-
-echo "[post-create] 3/4: seed shareable config dirs from host (first create only)"
-# The shareable dirs (Claude skills/agents/memory/commands/plugins; Codex
-# plugins/prompts/memories/skills; Cursor rules/commands/agents/skills/plugins)
-# used to be read-write host bind mounts, so a write inside the container landed
-# directly on the host's files. That exposed the host's on-disk CLI setup: a
-# compromised workspace dependency running in the container could drop a malicious
-# skill, agent, command, or plugin into the host's folders, which the next HOST
-# session would then auto-load. To protect the host, these are no longer bound.
-# Instead we COPY them once from the read-only /host/.<cli> stage into the
-# per-container named volume, exactly like claude-mem (step 4/4) and the session
-# volumes. The container gets its own writable copy and can NEVER write back to
-# the host. The container also avoids the old read-only-stage EROFS failure,
-# because it writes to its own volume copy, not a read-only mount.
-#
-# Seed-once, persist: a per-CLI marker file records that the copy has happened.
-# On the first container-create the marker is absent, so we copy; on every later
-# rebuild the marker is present, so we skip and keep whatever the container has
-# accumulated. Host edits made AFTER the first create do NOT reach the container
-# until you remove the config volume and rebuild (see README § Rebuild/reset).
-seed_shareable() {
-    # seed_shareable <cli> <subdir>...: copy each /host/.<cli>/<subdir> into the
-    # named volume, once. Skips a subdir the host doesn't have. We use `cp -r`,
-    # NOT `cp -a`/`cp -p`: this script runs as the non-root node user, and the
-    # host-stage files are owned by a different UID, so trying to preserve
-    # ownership would fail with EPERM and abort the run under `set -e` (the same
-    # reason sync_from_host uses plain cp). `cp -r` copies contents owned by node
-    # — exactly what we want — and preserves symlinks as symlinks (GNU default).
-    local cli=$1
-    shift
-    local marker="/home/node/.$cli/.devcontainer-shareable-seeded"
-    [ -f "$marker" ] && return 0
-    for sub in "$@"; do
-        local src="/host/.$cli/$sub"
-        local dst="/home/node/.$cli/$sub"
-        [ -d "$src" ] || continue
-        mkdir -p "$dst"
-        cp -r "$src/." "$dst/"
-    done
-}
-
-# Decide which plugin registries to translate BEFORE seeding sets the markers.
-# We translate only a CLI being seeded this run, so a plugin installed inside the
-# container isn't overwritten by the host's registry on a later rebuild. Codex
-# has no path-bearing registry (config.toml holds git URLs), so it's never here.
-TRANSLATE_CLIS=()
-[ -f /home/node/.claude/.devcontainer-shareable-seeded ] || TRANSLATE_CLIS+=(claude)
-[ -f /home/node/.cursor/.devcontainer-shareable-seeded ] || TRANSLATE_CLIS+=(cursor)
-
-seed_shareable claude skills agents memory commands plugins/marketplaces plugins/cache
-seed_shareable codex plugins prompts memories skills
-seed_shareable cursor rules commands agents skills plugins/marketplaces plugins/local
-
-# Translate the path-bearing plugin registries (Claude + Cursor) for the CLIs we
-# just seeded. They store absolute, OS-native install paths
-# (`C:\Users\X\.claude\plugins\...` on Windows), which the Linux container can't
-# resolve — it would fail with `cache-miss`. translate-plugin-registries.cjs
-# rewrites those to the container's paths and writes the result into the volume.
-if [ "${#TRANSLATE_CLIS[@]}" -gt 0 ]; then
-    node "$SCRIPT_DIR/translate-plugin-registries.cjs" "${TRANSLATE_CLIS[@]}"
-fi
-
-# Record that each CLI's shareable surface is seeded, so later rebuilds keep the
-# container's copy. Touch even when the host had nothing to copy — an empty CLI
-# is still "seeded", and we don't want to re-scan the host on every rebuild.
-#
-# ORDERING INVARIANT — do NOT move these touches earlier (e.g. into
-# seed_shareable per-CLI). The markers must be written only AFTER the registry
-# translation above, because seed (cache copy) and translate (registry rewrite)
-# are logically atomic: a marker set between them would let a later rebuild skip
-# translation for an already-seeded CLI, leaving its cache/ in place but its
-# registry still pointing at host paths (`cache-miss`). Writing all markers here,
-# after translate, means any abort mid-seed leaves NO markers, so the next create
-# re-runs the whole seed+translate. The cost is re-copying an already-copied CLI
-# on retry; `cp -r` overwrites in place, so that is idempotent and cheap relative
-# to a broken plugin registry.
-for cli in claude codex cursor; do
-    touch "/home/node/.$cli/.devcontainer-shareable-seeded"
-done
-
-echo "[post-create] 4/4: seed claude-mem store from host (first create only)"
-# claude-mem keeps its memory in $HOME/.claude-mem — a SQLite DB (claude-mem.db
-# plus -wal/-shm) and a Chroma vector store (chroma/chroma.sqlite3 + HNSW index
-# binaries). It is mounted as a per-container named volume, NOT a host bind:
-# pushing a multi-GB SQLite/WAL store over the 9p/virtiofs bind risks unreliable
-# fcntl locking and corruption, especially if claude-mem ran on the host and in
-# the container against the same files at once (see devcontainer.json).
-#
-# So seed it ONCE, then let the container own its copy. On every later rebuild
-# we skip the copy and keep whatever the container has accumulated since —
-# rebuilds never clobber it. The container's memory and the host's diverge from
-# this seed point on; that is the deliberate cost of keeping SQLite off a shared
-# bind. To re-seed from the host, remove the volume (`docker volume rm
-# claude-mem-<id>`) and rebuild.
-#
-# The skip guard is a COMPLETION SENTINEL (.claude-mem-seeded), NOT the presence
-# of claude-mem.db. Keying on the DB file would be a trap: a multi-GB `cp -r` can
-# be interrupted (disk full, I/O error) and abort the script under `set -e`,
-# leaving a PARTIAL claude-mem.db behind. The next create would then see that
-# truncated file and treat the store as "already seeded", sticking the container
-# with a corrupt DB forever. With a sentinel touched only AFTER `cp` returns 0,
-# an interrupted seed leaves no sentinel; the next create clears the half-copied
-# store and retries cleanly. CONSISTENCY: copying a live WAL database is only
-# crash-consistent if claude-mem is NOT writing on the host during the copy — do
-# not run claude-mem on the host during a first-create or a re-seed rebuild.
-#
-# `cp -r` (not `cp -a`/`cp -p`) copies the DB together with its -wal/-shm
-# sidecars in one pass. We avoid preserving ownership for the same reason as the
-# shareable seed above: this runs as the non-root node user against host-owned
-# files, so `cp -a` would fail with EPERM and abort under `set -e`. `cp -r`
-# leaves the copies owned by node. The host stage is read-only, so this can
-# never write back to the host's live DB.
-if [ -f /host/.claude-mem/claude-mem.db ] && [ ! -f /home/node/.claude-mem/.claude-mem-seeded ]; then
-    echo "[post-create]   seeding ~/.claude-mem from host (one-time copy, may be several GB)"
-    # Clear any partial store left by a previously-interrupted seed (mindepth 1
-    # so the volume mount point itself is never removed), then copy and only then
-    # write the sentinel. A partial store is node-owned (cp runs as node, and
-    # step 1 re-chowns the volume whenever the sentinel is absent), so no sudo.
-    find /home/node/.claude-mem -mindepth 1 -maxdepth 1 -exec rm -rf {} +
-    cp -r /host/.claude-mem/. /home/node/.claude-mem/
-    touch /home/node/.claude-mem/.claude-mem-seeded
-else
-    echo "[post-create]   skipping claude-mem seed (already seeded, or host has no store)"
-fi
-
-echo "[post-create] done"
@@ -1,83 +0,0 @@
-// Builds the container's $HOME/.claude.json from the host's copy. It does NOT
-// copy the host file verbatim. The host's ~/.claude.json holds two kinds of
-// data. Some is portable account and onboarding state: hasCompletedOnboarding,
-// oauthAccount, userID, projects, tipsHistory. We keep that. The rest tracks
-// how Claude was installed on the host machine, and that is never right inside
-// this container.
-//
-// Here is why the install fields break things. The image installs Claude with
-// `npm install -g`. But if the host's `installMethod` says something like
-// "native", Claude looks for ~/.local/bin/claude and fails with
-// "claude command not found at /home/node/.local/bin/claude". So we drop the
-// install and machine fields. With them gone, the npm-global binary detects its
-// own install method. We also force hasCompletedOnboarding so the setup wizard
-// is skipped, even when the host has never run Claude before.
-//
-// This logic was pulled out of a heredoc in post-create.sh. As its own file the
-// transform can be unit-tested and prettier-checked (see seed-claude-config.test
-// via the translate-plugin-registries test harness). DISABLE_AUTOUPDATER=1 in
-// containerEnv already stops runtime updates. This file only quiets the doctor
-// mismatch and the native-path probe.
-
-'use strict';
-
-const fs = require('fs');
-
-// Fields that describe how Claude was installed on the host machine. They are
-// never valid in an `npm install -g` container. Removing them lets Claude
-// detect the npm-global install on its own.
-const MACHINE_FIELDS = [
-  'installMethod',
-  'autoUpdates',
-  'autoUpdatesProtectedForNative',
-  'shiftEnterKeyBindingInstalled',
-];
-
-// Pure transform: take whatever the host file parsed to and return a config
-// object suitable for the container. It also guards against a host file that is
-// valid JSON but not an object. A bare number, string, or array would pass the
-// parse try/catch. Then the field deletes would do nothing, the
-// hasCompletedOnboarding assignment would silently fail, and onboarding would
-// trigger again on every rebuild. The guard replaces such a value with {}.
-function sanitizeClaudeConfig(parsed) {
-  let cfg = parsed;
-  if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg)) {
-    cfg = {};
-  }
-  for (const k of MACHINE_FIELDS) {
-    delete cfg[k];
-  }
-  cfg.hasCompletedOnboarding = true; // skip the wizard, even on a first-time host
-  return cfg;
-}
-
-function readHostConfig(src) {
-  try {
-    if (fs.existsSync(src) && fs.statSync(src).size > 0) {
-      return JSON.parse(fs.readFileSync(src, 'utf8'));
-    }
-  } catch {
-    // Host file is malformed or unreadable. Fall back to an empty config so the
-    // container still gets a valid file that carries hasCompletedOnboarding.
-  }
-  return {};
-}
-
-function main() {
-  const src = process.argv[2] || '/host/.claude.json';
-  const dst = process.argv[3] || '/home/node/.claude.json';
-  const cfg = sanitizeClaudeConfig(readHostConfig(src));
-  try {
-    fs.writeFileSync(dst, JSON.stringify(cfg, null, 2));
-    fs.chmodSync(dst, 0o644);
-  } catch (err) {
-    console.error(`[post-create] ERROR: failed to seed ${dst}: ${err && err.message}`);
-    process.exit(1);
-  }
-}
-
-module.exports = { sanitizeClaudeConfig, readHostConfig, MACHINE_FIELDS };
-
-if (require.main === module) {
-  main();
-}
@@ -1,107 +0,0 @@
-// Rewrites the host paths inside Claude and Cursor plugin-registry JSON files
-// so they point at the container's Linux paths, then writes the results into
-// the named volume.
-//
-// Why: both CLIs store absolute, OS-native install paths in their registry
-// JSONs. On Windows that looks like `C:\Users\X\.claude\plugins\...`; on macOS
-// like `/Users/X/.cursor/...`. The Linux container can't use those paths. If we
-// just bind-mounted the host files in, the CLI would try to resolve a Windows
-// path under Linux and fail with `cache-miss`. So for each CLI we read the host
-// registry, rewrite every absolute path ending in `/.<cli>/plugins/<rest>` to
-// `/home/node/.<cli>/plugins/<rest>`, and write the result into the named volume.
-//
-// Codex is left alone. Its registry is config.toml and holds git URLs, not
-// filesystem paths, so there's nothing to translate — its whole plugins/ dir is
-// copied as-is into the container volume instead (seeded once by post-create.sh).
-//
-// This code lived inside a post-create.sh heredoc. We pulled it out so the regex
-// and the deep rewrite can be unit-tested and prettier-checked. The regex has
-// had path-handling bugs before.
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-// Build a regex that matches an absolute path containing
-// `<sep>.<cli><sep>plugins<sep><rest>`, where <sep> is `/` or `\`. It's anchored
-// at the start of the string. The lazy `.*?` eats the home prefix up to the
-// FIRST `.<cli>/plugins` segment.
-function buildRe(cliName) {
-  return new RegExp(`^(?:[A-Za-z]:)?[\\\\/].*?[\\\\/]\\.${cliName}[\\\\/]plugins[\\\\/](.*)$`);
-}
-
-// Walk `obj` and rewrite every string value that matches `re`. A match is
-// remapped under `ctr`, the container's plugins dir. Windows backslashes in the
-// matched part are switched to forward slashes.
-function rewriteDeep(obj, re, ctr) {
-  if (Array.isArray(obj)) return obj.map((v) => rewriteDeep(v, re, ctr));
-  if (obj && typeof obj === 'object') {
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) out[k] = rewriteDeep(v, re, ctr);
-    return out;
-  }
-  if (typeof obj === 'string') {
-    return obj.replace(re, (_, rest) => `${ctr}/${rest.replace(/\\/g, '/')}`);
-  }
-  return obj;
-}
-
-const REGISTRIES = [
-  {
-    cli: 'claude',
-    host: '/host/.claude/plugins',
-    ctr: '/home/node/.claude/plugins',
-    files: ['known_marketplaces.json', 'installed_plugins.json', 'plugin-catalog-cache.json'],
-  },
-  {
-    cli: 'cursor',
-    host: '/host/.cursor/plugins',
-    ctr: '/home/node/.cursor/plugins',
-    files: ['installed_plugins.json'],
-  },
-];
-
-function translate(registries) {
-  for (const reg of registries) {
-    const re = buildRe(reg.cli);
-    try {
-      fs.mkdirSync(reg.ctr, { recursive: true });
-    } catch (err) {
-      console.error(`[post-create] ERROR: failed to create ${reg.ctr}: ${err && err.message}`);
-      process.exit(1);
-    }
-    for (const name of reg.files) {
-      const src = path.join(reg.host, name);
-      const dst = path.join(reg.ctr, name);
-      if (!fs.existsSync(src) || fs.statSync(src).size === 0) continue;
-      let data;
-      try {
-        data = JSON.parse(fs.readFileSync(src, 'utf8'));
-      } catch {
-        continue; // Skip a malformed host registry instead of aborting.
-      }
-      try {
-        fs.writeFileSync(dst, JSON.stringify(rewriteDeep(data, re, reg.ctr), null, 2));
-      } catch (err) {
-        console.error(`[post-create] ERROR: failed to write ${dst}: ${err && err.message}`);
-        process.exit(1);
-      }
-    }
-  }
-}
-
-// Filter the registry table by CLI name. post-create.sh passes the CLIs it is
-// seeding this run (e.g. `claude`), so a registry is only (re)generated on the
-// FIRST container-create for that CLI — never on a rebuild, where it would
-// clobber a plugin the user installed inside the container. An empty filter
-// (no args) means "translate every registry" — the original behavior.
-function selectRegistries(registries, only) {
-  return only && only.length ? registries.filter((r) => only.includes(r.cli)) : registries;
-}
-
-module.exports = { buildRe, rewriteDeep, REGISTRIES, translate, selectRegistries };
-
-if (require.main === module) {
-  translate(selectRegistries(REGISTRIES, process.argv.slice(2)));
-}
@@ -1,436 +0,0 @@
-// Unit tests for the devcontainer host->container config transforms.
-//
-// This code used to live inside post-create.sh heredocs, where lint could not
-// see it and tests could not reach it. We test three things:
-//   - plugin-registry path translation (buildRe + rewriteDeep + the real
-//     filesystem translate() driver). Path handling here has had bugs before.
-//   - the strip of machine-specific fields from $HOME/.claude.json
-//     (sanitizeClaudeConfig + readHostConfig + the seed-claude-config main()
-//     entry point)
-//   - the host bind-source bootstrap (ensurePaths). One test guards against a
-//     regression: ensurePaths must NOT pre-create settings.json / config.toml
-//     on the host.
-//
-// We test both pure functions and code that touches the filesystem. The
-// filesystem tests use throwaway directories under os.tmpdir() and delete them
-// when done. So they run in CI with no mounts and never touch the real home dir.
-//
-// Run with the built-in Node test runner (no extra dependencies):
-//   node --test .devcontainer/
-
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const os = require('node:os');
-const fs = require('node:fs');
-const path = require('node:path');
-const { execFileSync } = require('node:child_process');
-
-const {
-  buildRe,
-  rewriteDeep,
-  translate,
-  selectRegistries,
-} = require('./translate-plugin-registries.cjs');
-const { sanitizeClaudeConfig, readHostConfig } = require('./seed-claude-config.cjs');
-const { ensurePaths, DIRS, FILES } = require('./ensure-host-config-dirs.cjs');
-
-const CLAUDE = '/home/node/.claude/plugins';
-const CURSOR = '/home/node/.cursor/plugins';
-
-// Make a fresh throwaway directory under the OS temp root. mkdtemp picks a
-// unique name on every call, so we don't need Date.now() or random names.
-function tmp() {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'gn-dc-'));
-}
-
-function rw(value, cli, ctr) {
-  return rewriteDeep(value, buildRe(cli), ctr);
-}
-
-test('claude: Windows backslash absolute path -> container path', () => {
-  assert.equal(
-    rw('C:\\Users\\gergo\\.claude\\plugins\\cache\\x\\1.0', 'claude', CLAUDE),
-    '/home/node/.claude/plugins/cache/x/1.0',
-  );
-});
-
-test('claude: Windows forward-slash absolute path -> container path', () => {
-  assert.equal(
-    rw('C:/Users/gergo/.claude/plugins/marketplaces/m', 'claude', CLAUDE),
-    '/home/node/.claude/plugins/marketplaces/m',
-  );
-});
-
-test('claude: macOS POSIX path -> container path', () => {
-  assert.equal(
-    rw('/Users/alice/.claude/plugins/marketplaces/m', 'claude', CLAUDE),
-    '/home/node/.claude/plugins/marketplaces/m',
-  );
-});
-
-test('claude: Linux POSIX path -> container path', () => {
-  assert.equal(
-    rw('/home/bob/.claude/plugins/cache/foo', 'claude', CLAUDE),
-    '/home/node/.claude/plugins/cache/foo',
-  );
-});
-
-test('cursor: Windows path -> container cursor path', () => {
-  assert.equal(
-    rw('C:\\Users\\gergo\\.cursor\\plugins\\local\\myplug', 'cursor', CURSOR),
-    '/home/node/.cursor/plugins/local/myplug',
-  );
-});
-
-test('cross-CLI isolation: claude regex leaves a .cursor path untouched', () => {
-  const input = 'C:\\Users\\g\\.cursor\\plugins\\x';
-  assert.equal(rw(input, 'claude', CLAUDE), input);
-});
-
-test('non-path strings pass through unchanged', () => {
-  assert.equal(rw('not-a-path', 'claude', CLAUDE), 'not-a-path');
-  assert.equal(
-    rw('https://github.com/EveryInc/x.git', 'claude', CLAUDE),
-    'https://github.com/EveryInc/x.git',
-  );
-});
-
-test('non-string scalars pass through unchanged', () => {
-  assert.equal(rw(42, 'claude', CLAUDE), 42);
-  assert.equal(rw(null, 'claude', CLAUDE), null);
-  assert.equal(rw(true, 'claude', CLAUDE), true);
-});
-
-test('nested objects/arrays are rewritten deeply', () => {
-  const input = {
-    'compound-engineering@m': [
-      { installPath: 'C:\\Users\\g\\.claude\\plugins\\cache\\ce\\3.9.2', version: '3.9.2' },
-    ],
-    nested: { installLocation: '/Users/g/.claude/plugins/marketplaces/m' },
-  };
-  const out = rw(input, 'claude', CLAUDE);
-  assert.equal(
-    out['compound-engineering@m'][0].installPath,
-    '/home/node/.claude/plugins/cache/ce/3.9.2',
-  );
-  assert.equal(out['compound-engineering@m'][0].version, '3.9.2');
-  assert.equal(out.nested.installLocation, '/home/node/.claude/plugins/marketplaces/m');
-});
-
-test('sanitizeClaudeConfig: strips machine fields, forces hasCompletedOnboarding', () => {
-  const out = sanitizeClaudeConfig({
-    installMethod: 'native',
-    autoUpdates: false,
-    autoUpdatesProtectedForNative: true,
-    shiftEnterKeyBindingInstalled: true,
-    userID: 'abc',
-    oauthAccount: { emailAddress: 'x@y.z' },
-  });
-  assert.equal(out.installMethod, undefined);
-  assert.equal(out.autoUpdates, undefined);
-  assert.equal(out.autoUpdatesProtectedForNative, undefined);
-  assert.equal(out.shiftEnterKeyBindingInstalled, undefined);
-  assert.equal(out.userID, 'abc');
-  assert.equal(out.oauthAccount.emailAddress, 'x@y.z');
-  assert.equal(out.hasCompletedOnboarding, true);
-});
-
-test('sanitizeClaudeConfig: non-object inputs become a valid onboarding-bearing object', () => {
-  for (const bad of [42, 'x', null, ['a'], true]) {
-    const out = sanitizeClaudeConfig(bad);
-    assert.equal(typeof out, 'object');
-    assert.equal(Array.isArray(out), false);
-    assert.equal(out.hasCompletedOnboarding, true);
-  }
-});
-
-test('sanitizeClaudeConfig: empty object still gets hasCompletedOnboarding', () => {
-  assert.deepEqual(sanitizeClaudeConfig({}), { hasCompletedOnboarding: true });
-});
-
-// --- readHostConfig: reading the file, and the fallbacks when it fails ------
-
-test('readHostConfig: missing file -> {}', () => {
-  const dir = tmp();
-  try {
-    assert.deepEqual(readHostConfig(path.join(dir, 'nope.json')), {});
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('readHostConfig: empty (zero-byte) file -> {}', () => {
-  const dir = tmp();
-  try {
-    const f = path.join(dir, 'empty.json');
-    fs.writeFileSync(f, '');
-    assert.deepEqual(readHostConfig(f), {});
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('readHostConfig: malformed JSON -> {}', () => {
-  const dir = tmp();
-  try {
-    const f = path.join(dir, 'bad.json');
-    fs.writeFileSync(f, '{ not valid json');
-    assert.deepEqual(readHostConfig(f), {});
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('readHostConfig: valid object is parsed through', () => {
-  const dir = tmp();
-  try {
-    const f = path.join(dir, 'ok.json');
-    fs.writeFileSync(f, JSON.stringify({ userID: 'u', hasCompletedOnboarding: false }));
-    const out = readHostConfig(f);
-    assert.equal(out.userID, 'u');
-    assert.equal(out.hasCompletedOnboarding, false);
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-// --- translate(): runs against real registry files on disk ------------------
-
-test('translate: rewrites host absolute paths and writes into the ctr dir', () => {
-  const hostDir = tmp();
-  const ctrParent = tmp();
-  const ctrDir = path.join(ctrParent, 'plugins'); // need not exist yet; translate creates it
-  try {
-    const reg = [{ cli: 'claude', host: hostDir, ctr: ctrDir, files: ['installed_plugins.json'] }];
-    fs.writeFileSync(
-      path.join(hostDir, 'installed_plugins.json'),
-      JSON.stringify({ 'p@m': [{ installPath: 'C:\\Users\\g\\.claude\\plugins\\cache\\p\\1.0' }] }),
-    );
-    translate(reg);
-    const out = JSON.parse(fs.readFileSync(path.join(ctrDir, 'installed_plugins.json'), 'utf8'));
-    assert.equal(out['p@m'][0].installPath, `${ctrDir}/cache/p/1.0`);
-  } finally {
-    fs.rmSync(hostDir, { recursive: true, force: true });
-    fs.rmSync(ctrParent, { recursive: true, force: true });
-  }
-});
-
-test('translate: idempotent — a second run reproduces byte-identical output', () => {
-  const hostDir = tmp();
-  const ctrParent = tmp();
-  const ctrDir = path.join(ctrParent, 'plugins');
-  try {
-    const reg = [{ cli: 'claude', host: hostDir, ctr: ctrDir, files: ['installed_plugins.json'] }];
-    fs.writeFileSync(
-      path.join(hostDir, 'installed_plugins.json'),
-      JSON.stringify({ 'p@m': [{ installPath: 'C:\\Users\\g\\.claude\\plugins\\cache\\p\\1.0' }] }),
-    );
-    translate(reg);
-    const first = fs.readFileSync(path.join(ctrDir, 'installed_plugins.json'), 'utf8');
-    translate(reg);
-    const second = fs.readFileSync(path.join(ctrDir, 'installed_plugins.json'), 'utf8');
-    assert.equal(first, second);
-  } finally {
-    fs.rmSync(hostDir, { recursive: true, force: true });
-    fs.rmSync(ctrParent, { recursive: true, force: true });
-  }
-});
-
-test('translate: malformed host registry is skipped, dst not written', () => {
-  const hostDir = tmp();
-  const ctrParent = tmp();
-  const ctrDir = path.join(ctrParent, 'plugins');
-  try {
-    const reg = [{ cli: 'claude', host: hostDir, ctr: ctrDir, files: ['installed_plugins.json'] }];
-    fs.writeFileSync(path.join(hostDir, 'installed_plugins.json'), '{ broken');
-    translate(reg);
-    assert.equal(fs.existsSync(path.join(ctrDir, 'installed_plugins.json')), false);
-  } finally {
-    fs.rmSync(hostDir, { recursive: true, force: true });
-    fs.rmSync(ctrParent, { recursive: true, force: true });
-  }
-});
-
-test('translate: empty and missing host registries are skipped without error', () => {
-  const hostDir = tmp();
-  const ctrParent = tmp();
-  const ctrDir = path.join(ctrParent, 'plugins');
-  try {
-    const reg = [
-      { cli: 'claude', host: hostDir, ctr: ctrDir, files: ['empty.json', 'missing.json'] },
-    ];
-    fs.writeFileSync(path.join(hostDir, 'empty.json'), ''); // we never create missing.json
-    translate(reg);
-    assert.equal(fs.existsSync(path.join(ctrDir, 'empty.json')), false);
-    assert.equal(fs.existsSync(path.join(ctrDir, 'missing.json')), false);
-  } finally {
-    fs.rmSync(hostDir, { recursive: true, force: true });
-    fs.rmSync(ctrParent, { recursive: true, force: true });
-  }
-});
-
-// --- selectRegistries: the per-CLI filter post-create.sh drives translate with
-
-test('selectRegistries: no filter -> all registries (original behavior)', () => {
-  const regs = [{ cli: 'claude' }, { cli: 'cursor' }];
-  assert.deepEqual(selectRegistries(regs, []), regs);
-  assert.deepEqual(selectRegistries(regs, undefined), regs);
-});
-
-test('selectRegistries: filter keeps only the named CLIs', () => {
-  const regs = [{ cli: 'claude' }, { cli: 'cursor' }];
-  assert.deepEqual(selectRegistries(regs, ['claude']), [{ cli: 'claude' }]);
-  assert.deepEqual(selectRegistries(regs, ['cursor']), [{ cli: 'cursor' }]);
-  assert.deepEqual(selectRegistries(regs, ['claude', 'cursor']), regs);
-});
-
-test('selectRegistries: an unknown CLI name selects nothing', () => {
-  const regs = [{ cli: 'claude' }, { cli: 'cursor' }];
-  assert.deepEqual(selectRegistries(regs, ['codex']), []);
-});
-
-test('selectRegistries: empty registry table stays empty under any filter', () => {
-  assert.deepEqual(selectRegistries([], ['claude']), []);
-  assert.deepEqual(selectRegistries([], []), []);
-});
-
-// --- seed-claude-config main(): end-to-end, through the real CLI entry point
-
-const SEED_SCRIPT = path.join(__dirname, 'seed-claude-config.cjs');
-
-test('seed main: strips machine fields, keeps account, sets onboarding, chmod 644', () => {
-  const dir = tmp();
-  try {
-    const src = path.join(dir, 'host.claude.json');
-    const dst = path.join(dir, 'out.claude.json');
-    fs.writeFileSync(
-      src,
-      JSON.stringify({
-        installMethod: 'native',
-        userID: 'abc',
-        oauthAccount: { emailAddress: 'x@y.z' },
-      }),
-    );
-    execFileSync(process.execPath, [SEED_SCRIPT, src, dst]);
-    const out = JSON.parse(fs.readFileSync(dst, 'utf8'));
-    assert.equal(out.installMethod, undefined);
-    assert.equal(out.userID, 'abc');
-    assert.equal(out.oauthAccount.emailAddress, 'x@y.z');
-    assert.equal(out.hasCompletedOnboarding, true);
-    if (process.platform !== 'win32') {
-      assert.equal(fs.statSync(dst).mode & 0o777, 0o644);
-    }
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('seed main: missing host file still writes a valid onboarding-bearing file', () => {
-  const dir = tmp();
-  try {
-    const dst = path.join(dir, 'out.claude.json');
-    execFileSync(process.execPath, [SEED_SCRIPT, path.join(dir, 'nope.json'), dst]);
-    assert.deepEqual(JSON.parse(fs.readFileSync(dst, 'utf8')), { hasCompletedOnboarding: true });
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-test('seed main: chmodSync widens a pre-existing restrictive dst to 0o644', () => {
-  // This checks the file's permission bits, which only exist on POSIX systems.
-  //
-  // The catch: CI's default umask is 022, so a plain writeFileSync already
-  // creates files at mode 0o644. Asserting 0o644 right after a fresh write
-  // would therefore NOT prove the explicit chmodSync did anything.
-  //
-  // So we pre-create dst at the stricter mode 0o600. Opening a file in 'w'
-  // mode replaces its contents but KEEPS the mode of a file that already
-  // exists. That means the only way dst can end up at 0o644 is the chmodSync
-  // inside seed-claude-config.cjs. This pins the test to the chmod and not to
-  // the umask: delete the chmodSync line and this test fails, while the other
-  // seed test still passes.
-  if (process.platform === 'win32') return;
-  const dir = tmp();
-  try {
-    const src = path.join(dir, 'host.claude.json');
-    const dst = path.join(dir, 'out.claude.json');
-    fs.writeFileSync(src, JSON.stringify({ userID: 'u' }));
-    fs.writeFileSync(dst, '{}');
-    fs.chmodSync(dst, 0o600);
-    execFileSync(process.execPath, [SEED_SCRIPT, src, dst]);
-    assert.equal(fs.statSync(dst).mode & 0o777, 0o644);
-    assert.equal(JSON.parse(fs.readFileSync(dst, 'utf8')).userID, 'u');
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-// --- ensurePaths: sets up the host paths the bind mounts point at -----------
-
-test('ensurePaths: creates every DIR and FILE under a temp home, idempotently', () => {
-  const home = tmp();
-  try {
-    ensurePaths(home);
-    for (const d of DIRS) {
-      assert.equal(fs.statSync(path.join(home, d)).isDirectory(), true, `not a dir: ${d}`);
-    }
-    for (const f of FILES) {
-      assert.equal(fs.statSync(path.join(home, f)).isFile(), true, `not a file: ${f}`);
-    }
-    // Running it again must not throw and must not overwrite existing content.
-    fs.writeFileSync(path.join(home, '.claude.json'), '{"keep":true}');
-    ensurePaths(home);
-    assert.equal(fs.readFileSync(path.join(home, '.claude.json'), 'utf8'), '{"keep":true}');
-  } finally {
-    fs.rmSync(home, { recursive: true, force: true });
-  }
-});
-
-test('ensurePaths: does NOT pre-create settings.json / config.toml (no gratuitous host mutation)', () => {
-  const home = tmp();
-  try {
-    ensurePaths(home);
-    assert.equal(fs.existsSync(path.join(home, '.claude', 'settings.json')), false);
-    assert.equal(fs.existsSync(path.join(home, '.codex', 'config.toml')), false);
-  } finally {
-    fs.rmSync(home, { recursive: true, force: true });
-  }
-});
-
-test('ensurePaths: does NOT pre-create the shareable subdirs (now copied, not bound)', () => {
-  // The shareable dirs are seeded into the per-container volume from the
-  // read-only /host stage, so they are no longer bind-mount sources. Pre-creating
-  // empty ones would needlessly write into the host of someone who never used a
-  // CLI. This pins the DIRS trim: re-adding any of these would fail the test.
-  const home = tmp();
-  const mustNotExist = [
-    path.join('.claude', 'skills'),
-    path.join('.claude', 'agents'),
-    path.join('.claude', 'memory'),
-    path.join('.claude', 'commands'),
-    path.join('.claude', 'plugins'),
-    path.join('.codex', 'plugins'),
-    path.join('.codex', 'prompts'),
-    path.join('.codex', 'memories'),
-    path.join('.codex', 'skills'),
-    path.join('.cursor', 'rules'),
-    path.join('.cursor', 'commands'),
-    path.join('.cursor', 'agents'),
-    path.join('.cursor', 'skills'),
-    path.join('.cursor', 'plugins'),
-  ];
-  try {
-    ensurePaths(home);
-    for (const sub of mustNotExist) {
-      assert.equal(fs.existsSync(path.join(home, sub)), false, `should not pre-create: ${sub}`);
-    }
-    // The top-level stage roots that ARE still bind sources must exist.
-    for (const top of ['.claude', '.codex', '.cursor', '.claude-mem']) {
-      assert.equal(fs.statSync(path.join(home, top)).isDirectory(), true, `missing root: ${top}`);
-    }
-  } finally {
-    fs.rmSync(home, { recursive: true, force: true });
-  }
-});
@@ -17,9 +17,3 @@ 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=./
-
-# Azure DevOps Server Integration (passed to the server container)
-# Prefer https:// — the PAT rides in an Authorization header, so cleartext
-# http:// exposes it on the wire (still supported for internal-only instances).
-# AZURE_DEVOPS_URL=https://azuredevops.example.com
-# AZURE_DEVOPS_PAT=your-pat-here
@@ -1,19 +0,0 @@
-description = "GitNexus production-readiness PR swarm review (Solo mode)"
-
-prompt = """
-You are the GitNexus PR review coordinator. Review this pull request: {{args}}
-(a PR URL or number for https://github.com/abhigyanpatwari/GitNexus). If no target was
-given, ask for one.
-
-Read `pr-swarm-review/orchestration.md` in this repository and follow it exactly. It is the
-canonical, CLI-neutral review contract (lanes, classifications, output structure, finding
-format, hidden-Unicode checks, behavior rules).
-
-Run in **Solo mode**: you are a single agent, so perform all seven lanes yourself in
-dependency order, adopting each persona in `pr-swarm-review/personas/0N-*.md` in turn
-(lanes 1-2 first, then 3-6, then lane 7). Keep every lane's findings in context. Lane 7
-(synthesis critic) is a hard gate: do not emit the final review until its "Required
-corrections before posting" section is empty — revise and re-run it otherwise.
-
-Stay strictly read-only: investigate and report; never edit files, commit, or post to GitHub.
-"""
@@ -1,17 +1,2 @@
 * text=auto eol=lf
 .husky/* text eol=lf
-
-# Shell scripts: force LF unconditionally so devcontainer scripts
-# (e.g. anything COPYed into a Linux container) execute correctly when
-# checked out on Windows hosts with core.autocrlf=true.
-*.sh text eol=lf
-*.bash text eol=lf
-
-# Native and binary assets shouldn't be treated as text under any
-# auto-detection or eol normalization.
-*.node binary
-*.wasm binary
-*.onnx binary
-*.so binary
-*.dll binary
-*.dylib binary
@@ -1,4 +0,0 @@
-# Code owners
-
-* @Arvuno
-* @magyargergo
@@ -1,5 +1,5 @@
 name: Setup GitNexus Web
-description: Setup Node.js 22, build gitnexus-shared, install web dependencies
+description: Setup Node.js 20.19+ (vite 7 floor), build gitnexus-shared, install web dependencies

 runs:
  using: composite
@@ -7,7 +7,9 @@ runs:
    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
      with:
        # Vite 7 requires Node ^20.19.0 || >=22.12.0 (require(esm) support).
-        node-version: 22
+        # Pin explicitly so we don't depend on the floating "20" alias resolving
+        # to a high enough patch version on every runner image.
+        node-version: '20.19.0'
        cache: npm
        cache-dependency-path: gitnexus-web/package-lock.json

@@ -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

@@ -7,8 +7,6 @@ updates:
    directory: /
    schedule:
      interval: weekly
-    cooldown:
-      default-days: 7
    open-pull-requests-limit: 5
    commit-message:
      prefix: chore
@@ -17,36 +15,6 @@ updates:
      - 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
@@ -57,11 +25,6 @@ updates:
    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)
@@ -91,11 +54,6 @@ updates:
    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)
@@ -109,11 +67,6 @@ updates:
    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)
@@ -1,19 +0,0 @@
---
-description: 'GitNexus production-readiness PR swarm review (Solo mode)'
-mode: 'agent'
---
-
-You are the GitNexus PR review coordinator. Review the pull request the user names (a PR URL
-or number for `https://github.com/abhigyanpatwari/GitNexus`). If none was given, ask for one.
-
-Read `pr-swarm-review/orchestration.md` in this repository and follow it exactly — it is the
-canonical, CLI-neutral review contract (lanes, classifications, output structure, finding
-format, hidden-Unicode checks, behavior rules).
-
-Run in **Solo mode**: you are a single agent, so perform all seven lanes yourself in
-dependency order, adopting each persona in `pr-swarm-review/personas/0N-*.md` in turn
-(lanes 1–2 first, then 3–6, then lane 7). Keep every lane's findings in context. Lane 7
-(synthesis critic) is a hard gate: do not emit the final review until its "Required
-corrections before posting" section is empty.
-
-Stay strictly read-only: investigate and report; never edit files, commit, or post to GitHub.
@@ -1,19 +1,31 @@
 #!/usr/bin/env python3
-"""Monitor tree-sitter 0.25 upgrade readiness — two things Dependabot can't see:
+"""Monitor tree-sitter 0.25 upgrade readiness.

-  1. Peer-dep compatibility: when every grammar's *latest npm release* accepts
-     tree-sitter@0.25.0 (so we can upgrade without --legacy-peer-deps).
-  2. Vendored upstream drift: whether a vendored grammar's upstream parser.c moved.
+Tracks two things Dependabot cannot see:

-Invoked daily from tree-sitter-upgrade-readiness.yml; runs locally too. Outputs
-Markdown to stdout; exit 1 when blockers remain (the workflow upserts a tracking
-issue). stdlib-only — runs on any vanilla runner.
-    python3 .github/scripts/check-tree-sitter-upgrade-readiness.py [--offline | --assert-current]
+  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 http.client
 import json
 import os
 import pathlib
@@ -26,11 +38,6 @@ import urllib.request
 REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
 GITNEXUS_DIR = REPO_ROOT / "gitnexus"

-# Offline mode (--offline flag or GITNEXUS_TS_READINESS_OFFLINE=1): skip ALL network
-# so the script + tests run hermetically. npm columns render "n/a (offline)";
-# vendored ABIs are still read from the repo. The read-path mirror of --assert-current.
-OFFLINE = os.environ.get("GITNEXUS_TS_READINESS_OFFLINE", "") not in ("", "0", "false")
-
 # ── 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).
@@ -71,11 +78,15 @@ GRAMMARS: dict[str, tuple[str, str, str]] = {
    "tree-sitter-proto":      ("coder3101/tree-sitter-proto",        "main",   "src/parser.c"),
 }

-# npm-installed grammars deliberately held below npm latest (surfaced so reviewers
-# can tell intentional pins from drift). Add an entry when you pin an npm grammar.
-# VENDORED grammars carry their hold in .github/vendored-grammars.json instead, so a
-# vendored grammar's hold lives in one place — tree-sitter-c's is there, not here.
+# 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 "
@@ -84,56 +95,6 @@ INTENTIONAL_PINS: dict[str, str] = {
 }


-def load_vendored_manifest() -> dict[str, dict]:
-    """Load the shared vendored-grammar manifest (.github/vendored-grammars.json).
-
-    The single source of truth — shared with update-vendored-grammars.mjs — for
-    which grammars are *vendored* (shipped from gitnexus/vendor/<name>, not npm)
-    and any policy ``hold`` (e.g. tree-sitter-c, #1242/#858). Membership routes a
-    grammar to the vendored branch, which reads its ABI from the repo instead of
-    node_modules (the #858 source of the old bare ``?``). Returns
-    ``{ name: {"hold": str | None} }``; upstream-drift coords stay in ``GRAMMARS``.
-    """
-    manifest_path = REPO_ROOT / ".github" / "vendored-grammars.json"
-    # Fail loud with a pointer, not a bare traceback: this runs at module import,
-    # so a missing/corrupt manifest would otherwise crash both the script and any
-    # test that imports it with an opaque FileNotFoundError/JSONDecodeError.
-    try:
-        data = json.loads(manifest_path.read_text(encoding="utf-8"))
-    except FileNotFoundError as exc:
-        raise SystemExit(
-            f"vendored-grammars manifest not found at {manifest_path}. "
-            f"It is the shared source of truth for vendored grammars "
-            f"(see CONTRIBUTING.md → CI automation contracts)."
-        ) from exc
-    except json.JSONDecodeError as exc:
-        raise SystemExit(
-            f"vendored-grammars manifest at {manifest_path} is not valid JSON: {exc}."
-        ) from exc
-    out: dict[str, dict] = {}
-    for key, g in (data.get("grammars") or {}).items():
-        name = g.get("name")
-        if not name:
-            raise SystemExit(
-                f"vendored-grammars manifest entry {key!r} is missing a 'name' field "
-                f"({manifest_path})."
-            )
-        # Defense-in-depth (#2187): `name` is joined into gitnexus/vendor/<name>, so
-        # reject anything not a plain grammar name before it can traverse ("../etc").
-        if not re.fullmatch(r"tree-sitter-[a-z0-9-]+", name):
-            raise SystemExit(
-                f"vendored-grammars manifest entry {key!r} has an invalid grammar "
-                f"name {name!r} (must match tree-sitter-[a-z0-9-]+)."
-            )
-        out[name] = {"hold": g.get("hold")}
-    return out
-
-
-# Vendored set + holds, keyed by full grammar name (e.g. "tree-sitter-c").
-VENDORED: dict[str, dict] = load_vendored_manifest()
-VENDORED_NAMES: frozenset[str] = frozenset(VENDORED)
-
-
 # ── Helpers ─────────────────────────────────────────────────────────────

 def _load_package_json() -> dict:
@@ -173,27 +134,12 @@ def npm_view_json(pkg: str) -> dict | None:
    being available (it's a batch file on Windows which complicates
    subprocess calls).
    """
-    if OFFLINE:
-        return None
    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"))
-    # OSError covers read-phase transport failures (ConnectionResetError,
-    # ssl.SSLError, socket.timeout) that escape resp.read() AFTER urlopen
-    # returns — urllib only wraps connect-phase OSErrors into URLError, so these
-    # are not URLError subclasses. http.client.IncompleteRead is an HTTPException,
-    # not an OSError, so it must be named explicitly. Returning None routes the
-    # grammar to the fetch_failed blocker bucket (a complete report) instead of
-    # crashing main() to empty stdout.
-    except (
-        urllib.error.URLError,
-        urllib.error.HTTPError,
-        OSError,
-        http.client.IncompleteRead,
-        json.JSONDecodeError,
-    ):
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError):
        return None


@@ -244,8 +190,6 @@ def fetch_text(url: str, timeout: int = 8) -> str | None:
    Adds an Authorization header for github.com URLs when GITHUB_TOKEN is
    set (raises the rate limit from 60 to 5 000 requests/hour).
    """
-    if OFFLINE:
-        return None
    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).
@@ -263,16 +207,7 @@ def fetch_text(url: str, timeout: int = 8) -> str | None:
        req = urllib.request.Request(url, headers=headers)
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            return resp.read().decode("utf-8", errors="ignore")
-    # See npm_view_json: OSError + http.client.IncompleteRead catch read-phase
-    # transport failures that escape resp.read() and are not URLError subclasses,
-    # so a transient network blip yields None (→ fetch_failed) rather than
-    # crashing the report to empty stdout.
-    except (
-        urllib.error.URLError,
-        urllib.error.HTTPError,
-        OSError,
-        http.client.IncompleteRead,
-    ):
+    except (urllib.error.URLError, urllib.error.HTTPError):
        return None


@@ -296,8 +231,14 @@ def md_h(text: str, level: int = 2) -> str:


 def _first_sentence(text: str) -> str:
-    """Return the leading sentence of a `_vendoredBy` rationale (the rest tails off
-    into install-script breadcrumbs); fall back to the whole string."""
+    """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
@@ -321,26 +262,21 @@ def range_includes(spec: str | None, version: str) -> bool:
    return spec.strip() == version.strip()


-def vendored_abi_from_repo(name: str, parser_path: str) -> int | None:
-    """Read a vendored grammar's ABI directly from gitnexus/vendor/<name>.
-
-    Local-only (no network) — the offline half of ``vendored_drift_summary``,
-    factored out so the hermetic ``--assert-current`` gate can introspect vendored
-    ABIs without triggering the upstream-drift fetches it never uses (#858 review).
-    """
-    vendor_dir = GITNEXUS_DIR / "vendor" / name
-    vendored_parser = vendor_dir / parser_path
-    if not vendored_parser.is_file():
-        vendored_parser = vendor_dir / "src" / "parser.c"
-    return extract_language_version(vendored_parser)
+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 its
-    package.json ``version`` + ``_vendoredBy`` (the rationale, kept next to the
-    sources), the vendored ABI, and a comparison against upstream main.
+    """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 = {}
@@ -354,7 +290,7 @@ def vendored_drift_summary(
    vendored_parser = vendor_dir / parser_path
    if not vendored_parser.is_file():
        vendored_parser = vendor_dir / "src" / "parser.c"
-    vendored_abi = vendored_abi_from_repo(name, parser_path)
+    vendored_abi = extract_language_version(vendored_parser)

    upstream_url = (
        f"https://raw.githubusercontent.com/{upstream_repo}/"
@@ -366,13 +302,10 @@ def vendored_drift_summary(
    sha_text = fetch_text(
        f"https://api.github.com/repos/{upstream_repo}/commits/{upstream_branch}"
    )
-    # Labeled fallback rather than a bare "?": in CI this fetch succeeds, but
-    # offline (or on a transient API miss) the report should say *why* it's
-    # blank instead of leaving a placeholder (#858).
-    upstream_sha = "unknown"
+    upstream_sha = "?"
    if sha_text:
        try:
-            upstream_sha = json.loads(sha_text).get("sha", "unknown")[:12]
+            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
        except json.JSONDecodeError:
            pass

@@ -388,9 +321,7 @@ def vendored_drift_summary(

    return {
        "name": name,
-        # Labeled fallback, never a bare "?": a vendor package.json should always
-        # carry a version, but if one is missing the report says so plainly (#858).
-        "vendored_version": pkg.get("version") or "unknown",
+        "vendored_version": pkg.get("version", "?"),
        "vendored_by": pkg.get("_vendoredBy"),
        "vendored_abi": vendored_abi,
        "upstream_repo": upstream_repo,
@@ -401,105 +332,6 @@ def vendored_drift_summary(
    }


-# ── Assert mode (CI gate) ─────────────────────────────────────────────────
-
-
-def assert_current() -> int:
-    """Assert every grammar's compiled ABI loads on the CURRENT runtime.
-
-    The hermetic/offline static half of the #1922 ABI gate (the runtime
-    load-smoke is the dynamic half): reads only local files — npm ABIs from
-    node_modules/<name>, vendored ABIs from gitnexus/vendor/<name> via
-    ``vendored_abi_from_repo`` (no network). A prebuilt-only vendor (no
-    parser.c) is skipped; INTENTIONAL_PINS are asserted like any other grammar.
-    Returns 0 when every introspectable grammar is in range, 1 otherwise.
-    """
-    current_runtime = read_current_runtime()
-    abi_range = RUNTIME_ABI_RANGES.get(current_runtime)
-    if abi_range is None:
-        print(
-            f"FAIL: RUNTIME_ABI_RANGES has no entry for current runtime "
-            f"{current_runtime!r}; add it before asserting.",
-        )
-        return 1
-    lo, hi = abi_range
-    pinned_versions = read_pinned_grammar_versions()
-
-    print(
-        f"Asserting all grammar ABIs load on tree-sitter@{current_runtime}.x "
-        f"(ABI {lo}–{hi})."
-    )
-
-    failures: list[str] = []
-    checked = 0
-    skipped: list[str] = []
-
-    for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
-        pinned_spec = pinned_versions.get(name, "—")
-        if name in VENDORED_NAMES and VENDORED[name].get("hold"):
-            pin_note = " [vendored, held]"
-        elif name in INTENTIONAL_PINS:
-            pin_note = f" [intentional pin: {pinned_spec}]"
-        else:
-            pin_note = ""
-
-        # Vendored grammars: ABI read locally from the repo via vendored_abi_from_repo
-        # (NOT vendored_drift_summary, which fetches upstream — this gate is hermetic),
-        # so the offline #1922 gate covers them instead of skipping them (#858/#2187).
-        if name in VENDORED_NAMES:
-            abi = vendored_abi_from_repo(name, parser_path)
-            if abi is None:
-                # Prebuilt-only vendor (e.g. a binary-only grammar): no parser.c to
-                # introspect. The runtime load-smoke covers it instead.
-                skipped.append(f"{name} (vendored, prebuilt — covered by load-smoke)")
-                continue
-            checked += 1
-            if lo <= abi <= hi:
-                print(f"  OK   {name}: vendored ABI {abi} in range{pin_note}")
-            else:
-                msg = (
-                    f"{name}: vendored ABI {abi} outside current runtime range "
-                    f"{lo}..{hi}{pin_note}"
-                )
-                print(f"  FAIL {msg}")
-                failures.append(msg)
-            continue
-
-        installed_parser = GITNEXUS_DIR / "node_modules" / name / parser_path
-        if not installed_parser.is_file():
-            installed_parser = GITNEXUS_DIR / "node_modules" / name / "src" / "parser.c"
-        abi = extract_language_version(installed_parser)
-        if abi is None:
-            skipped.append(f"{name} (not installed / no parser.c — covered by load-smoke)")
-            continue
-        checked += 1
-        if lo <= abi <= hi:
-            print(f"  OK   {name}: installed ABI {abi} in range{pin_note}")
-        else:
-            msg = (
-                f"{name}: installed ABI {abi} outside current runtime range "
-                f"{lo}..{hi}{pin_note}"
-            )
-            print(f"  FAIL {msg}")
-            failures.append(msg)
-
-    print("")
-    if skipped:
-        print("Not statically introspectable (asserted via runtime load-smoke):")
-        for s in skipped:
-            print(f"  - {s}")
-        print("")
-
-    if failures:
-        print(f"RESULT: FAIL — {len(failures)} grammar(s) out of range, {checked} checked.")
-        for f in failures:
-            print(f"  - {f}")
-        return 1
-
-    print(f"RESULT: OK — all {checked} introspectable grammar ABIs in range.")
-    return 0
-
-
 # ── Main ────────────────────────────────────────────────────────────────


@@ -516,18 +348,32 @@ def _classify_grammar(
 ) -> dict:
    """Decide a single primary disposition + a separate bump-now hint.

-    Mutually-exclusive buckets, ordered by reviewer priority: ``fetch_failed``
-    (npm fetch failed — surfaced apart from upstream blocks), ``intentional``
-    (in INTENTIONAL_PINS), ``ready`` (npm-latest peer accepts the target),
-    ``waiting`` (a fix on main, unpublished), ``blocked`` (peer too tight on
-    both). ``bump_now`` is independent: True only when npm-latest's peer also
-    accepts our *current* runtime (else the bump would break ``npm install``).
+    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`.
    """
-    # Only npm-path grammars reach this function — vendored grammars are routed
-    # to the vendored branch in main() and `continue` before classification.
-    behind_latest = npm_version != "?" and not range_includes(pinned_spec, npm_version)
-    # Intentional pins are never actionable bumps (held on purpose; lifted only by
-    # editing INTENTIONAL_PINS + package.json together).
+    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:
@@ -545,9 +391,6 @@ def _classify_grammar(
        "name": name,
        "pinned_spec": pinned_spec or "—",
        "npm_version": npm_version,
-        # Display form for the disposition prose, laundering a "?" (a malformed 200
-        # npm response lacking `version`) so it never shows bare, like the matrix cell.
-        "npm_version_label": "unknown" if npm_version == "?" else npm_version,
        "peer_range": peer_range,
        "target_compat": target_compat,
        "current_compat": current_compat,
@@ -555,105 +398,15 @@ def _classify_grammar(
        "behind_latest": behind_latest,
        "bump_now": bump_now,
        "bucket": bucket,
+        "is_vendored": is_vendored,
    }


-def _render_vendored_section(
-    vendored_grammars: list[dict],
-    target_abi_range: tuple[int, int],
-    blockers: dict[str, str],
-) -> list[str]:
-    """Render the 'Vendored parsers' prose block. Appends any runtime-side blocker
-    (upstream ABI beyond the target range) to ``blockers`` in place; returns the
-    markdown lines (empty when nothing is vendored). Extracted from main() so that
-    function coordinates named render phases rather than inlining them (#2187)."""
-    if not vendored_grammars:
-        return []
-    # Hoisted out of the list literal below: an implicit string concatenation
-    # inside a list display trips CodeQL py/implicit-string-concatenation-in-list
-    # (it reads as a possibly-missing comma between elements).
-    intro = (
-        "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 = [md_h(f"Vendored parsers ({len(vendored_grammars)})", 2), intro, ""]
-    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]})"
-            )
-        # Never a bare "?": when upstream parser.c can't be read (generated at build,
-        # or a transient fetch miss), use the neutral `n/a` token (#858).
-        upstream_abi_str = (
-            f"ABI `{v['upstream_abi']}`" if v["upstream_abi"] is not None else "ABI `n/a`"
-        )
-        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.get("hold"):
-            lines.append(f"  - **Held:** {v['hold']}")
-        if v["vendored_by"]:
-            # First sentence only — vendor _vendoredBy fields tail off into noise.
-            lines.append(f"  - **Why vendored:** {_first_sentence(v['vendored_by'])}")
-        # Action: regen iff upstream ABI exceeds vendored AND stays within target;
-        # beyond target is a runtime-side blocker. Prebuilt-only vendors get a
-        # manual-refresh action driven by 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("")
-    return lines
-
-
 def main() -> int:
    blockers: dict[str, str] = {}
    lines: list[str] = []
-    # Label for npm/upstream values we couldn't determine: in --offline mode the
-    # fetch was deliberately skipped (not "failed"), so say so honestly.
-    miss_label = "offline" if OFFLINE else "fetch failed"
    lines.append(md_h("Tree-sitter 0.25 upgrade readiness", 1))
    lines.append("")
-    if OFFLINE:
-        lines.append(
-            "> **Offline mode** — npm registry + upstream GitHub checks were skipped. "
-            "npm-installed grammars show as unverified; vendored-grammar ABIs are read "
-            "from `gitnexus/vendor/`."
-        )
-        lines.append("")

    current_runtime = read_current_runtime()
    current_abi_range = RUNTIME_ABI_RANGES.get(current_runtime, (0, 0))
@@ -667,9 +420,10 @@ def main() -> int:
    )
    lines.append("")

-    # First pass: gather + classify per grammar. Human buckets render first, then
-    # the raw matrix in a <details> block (Status text preserved verbatim so the
-    # workflow's row-diff change-detection keeps working).
+    # 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 |",
@@ -681,17 +435,17 @@ def main() -> int:
    for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
        pinned_spec = pinned_versions.get(name, "—")

-        # Vendored grammars are classified by manifest membership (NOT a file: pin
-        # heuristic — they aren't in package.json at all, the #858 misrouting bug).
-        # Their readiness is governed by the vendored ABI, read from the repo, not a
-        # peer-dep negotiation. npm-latest columns get sentinels.
-        if name in VENDORED_NAMES:
+        # 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
-            hold = VENDORED[name].get("hold")
-            v["hold"] = hold
-            # Three-state ABI classification: in-range, out-of-range, or
-            # not-introspectable (e.g. a prebuilt-only vendor with no parser.c).
+            # 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"
@@ -708,37 +462,13 @@ def main() -> int:
                    f"vendored `{name}`: ABI {v['vendored_abi']} outside target range "
                    f"{target_abi_range[0]}..{target_abi_range[1]}"
                )
-            # A held vendored grammar (e.g. tree-sitter-c, #1242/#858) is frozen below
-            # a runtime upgrade: in-range ABI or not, keep it a blocker until the hold
-            # (from the manifest) is lifted — same treatment as npm INTENTIONAL_PINS.
-            if hold:
-                v["target_compat"] = False
-                status = "Vendored — held"
-                # Compose with any out-of-range reason rather than overwriting it:
-                # both share the blockers[name] key, and the ABI-out-of-range
-                # detail would otherwise be lost from the blockers summary.
-                hold_reason = f"vendored `{name}` held: {hold}"
-                prior = blockers.get(name)
-                blockers[name] = f"{prior}; {hold_reason}" if prior else hold_reason
-            # Cell sentinels: never emit a bare "?". A vendored grammar's ABI is
-            # the real LANGUAGE_VERSION when introspectable, else a labeled token.
-            vendored_abi_cell = (
-                str(v["vendored_abi"]) if v["vendored_abi"] is not None else "prebuilt"
-            )
-            # A None upstream ABI means the upstream parser.c couldn't be read —
-            # either it is generated at build time (e.g. swift) or the fetch
-            # missed. We can't tell which here, so use a neutral label rather
-            # than asserting "generated at build". Never a bare "?".
-            upstream_abi_cell = (
-                str(v["upstream_abi"]) if v["upstream_abi"] is not None else "n/a"
-            )
            # 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.
+            # 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"{vendored_abi_cell} | {upstream_abi_cell} | {status} |"
+                f"{v['vendored_abi'] or '?'} | {v['upstream_abi'] or '?'} | {status} |"
            )
            vendored_grammars.append(v)
            continue
@@ -758,7 +488,7 @@ def main() -> int:
            peer_optional = ts_meta.get("optional", False) if peer_range else True

        if fetch_failed:
-            peer_display = f"n/a ({miss_label})"
+            peer_display = "? (fetch failed)"
            target_compat = False
            current_compat = False
        else:
@@ -774,9 +504,7 @@ def main() -> int:
            # Fallback to default location.
            installed_parser = GITNEXUS_DIR / "node_modules" / name / "src" / "parser.c"
        installed_abi = extract_language_version(installed_parser)
-        # Labeled sentinel, never a bare "?": CI's `npm ci` populates node_modules,
-        # but if it's absent say so plainly rather than leaving a placeholder (#858).
-        abi_display = str(installed_abi) if installed_abi else "n/a (not installed)"
+        abi_display = str(installed_abi) if installed_abi else "?"

        # Check upstream (main/master branch) ABI for unreleased work.
        upstream_url = (
@@ -785,19 +513,23 @@ def main() -> int:
        )
        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 "n/a"
+        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 = f"Unknown ({miss_label})"
-            reason = "checks skipped (offline)" if OFFLINE else "npm registry fetch failed"
-            blockers[name] = f"`{name}`: {reason} — could not verify peer dep"
+            status = "Unknown (fetch failed)"
+            blockers[name] = f"`{name}`: npm registry fetch failed — could not verify peer dep"
        elif name in INTENTIONAL_PINS:
-            # A held-back grammar: treated as a blocker until the pin is lifted
-            # (entry removed from INTENTIONAL_PINS), then reclassified next run.
+            # 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}` "
@@ -838,11 +570,8 @@ def main() -> int:

        pinned_spec = pinned_versions.get(name, "—")
        compat_icon = "Yes" if target_compat else "**No**"
-        # "?" stays the internal fetch-failed sentinel (compared above); render a
-        # labeled token in the matrix so the report never shows a bare "?" (#858).
-        npm_version_cell = f"n/a ({miss_label})" if npm_version == "?" else npm_version
        raw_matrix.append(
-            f"| `{name}` | {pinned_spec} | {npm_version_cell} | {peer_display} | "
+            f"| `{name}` | {pinned_spec} | {npm_version} | {peer_display} | "
            f"{compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
        )

@@ -892,8 +621,7 @@ def main() -> int:
    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']:
-        why = "checks skipped in offline mode" if OFFLINE else "npm registry unreachable"
-        lines.append(f"- {len(by_bucket['fetch_failed'])} could not be checked ({why})")
+        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 "
@@ -912,7 +640,7 @@ def main() -> int:
        lines.append("")
        for r in sorted(bump_now, key=lambda r: r["name"]):
            lines.append(
-                f"- `{r['name']}`: `{r['pinned_spec']}` → `{r['npm_version_label']}` "
+                f"- `{r['name']}`: `{r['pinned_spec']}` → `{r['npm_version']}` "
                f"(peer `{r['peer_range'] or 'none'}`)"
            )
        lines.append("")
@@ -935,7 +663,7 @@ def main() -> int:
        "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_label']}`"
+            f"- `{r['name']}` — pinned `{r['pinned_spec']}`, npm latest `{r['npm_version']}`"
            + ("  _(also a bump candidate — see above)_" if r["bump_now"] else "")
        ),
    )
@@ -951,7 +679,7 @@ def main() -> int:
            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_label']}`)\n  {reason}"
+                f"(npm latest `{r['npm_version']}`)\n  {reason}"
            )
        lines.append("")

@@ -961,7 +689,7 @@ def main() -> int:
        "We can move forward as soon as upstream cuts a release.",
        by_bucket["waiting"],
        lambda r: (
-            f"- `{r['name']}@{r['npm_version_label']}` — peer `{r['peer_range'] or 'none'}`. "
+            f"- `{r['name']}@{r['npm_version']}` — peer `{r['peer_range'] or 'none'}`. "
            f"_{r['upstream_progress']}_"
        ),
    )
@@ -971,23 +699,90 @@ def main() -> int:
        "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_label']}` — peer `{r['peer_range'] or 'none'}`",
+        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",
-        (
-            "Checks were skipped because the report ran in `--offline` mode. "
-            "Re-run online to verify these grammars."
-            if OFFLINE
-            else "npm registry fetch failed for these grammars. Re-run the workflow to retry."
-        ),
+        "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 ────────────────────────────────────────────
-    lines.extend(_render_vendored_section(vendored_grammars, target_abi_range, blockers))
+    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))
@@ -1011,14 +806,4 @@ if __name__ == "__main__":
        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
    except Exception:
        pass
-    # `--offline` skips all network so the readiness report renders hermetically
-    # (vendored ABIs from the repo; npm columns marked unverified). Useful for
-    # air-gapped runs and deterministic tests.
-    if "--offline" in sys.argv[1:]:
-        OFFLINE = True
-    # `--assert-current` is the offline CI gate (#1922): assert every grammar's
-    # ABI loads on the CURRENT runtime. Bare invocation keeps the original
-    # target-runtime readiness report behaviour.
-    if "--assert-current" in sys.argv[1:]:
-        sys.exit(assert_current())
    sys.exit(main())
@@ -1,474 +0,0 @@
-#!/usr/bin/env python3
-"""Tests for check-tree-sitter-upgrade-readiness.py.
-
-Stdlib-only (``unittest`` + ``unittest.mock``) to match the script under test,
-which is deliberately dependency-free so it runs on any vanilla runner. Run with:
-
-    python3 -m unittest .github/scripts/test_check_tree_sitter_upgrade_readiness.py
-
-(pytest also discovers ``unittest.TestCase`` classes, so a future pytest CI job
-picks these up unchanged.)
-
-These tests lock in the #858 fix: the 5 vendored grammars
-(c/swift/kotlin/dart/proto) are classified from the shared manifest
-(.github/vendored-grammars.json), their ABI is read from gitnexus/vendor/<name>,
-and the report never renders a bare ``?`` placeholder. All network is mocked.
-"""
-from __future__ import annotations
-
-import contextlib
-import http.client
-import importlib.util
-import io
-import json
-import pathlib
-import re
-from unittest import TestCase, main, mock
-
-# ── Load the hyphenated script as a module ───────────────────────────────
-_SCRIPTS_DIR = pathlib.Path(__file__).resolve().parent
-_SCRIPT = _SCRIPTS_DIR / "check-tree-sitter-upgrade-readiness.py"
-_REPO_ROOT = _SCRIPTS_DIR.parents[1]
-_MANIFEST = _REPO_ROOT / ".github" / "vendored-grammars.json"
-
-_spec = importlib.util.spec_from_file_location("readiness_under_test", _SCRIPT)
-readiness = importlib.util.module_from_spec(_spec)
-_spec.loader.exec_module(readiness)  # type: ignore[union-attr]
-
-# The exact row-diff regex the workflow's change-detection bot uses
-# (.github/workflows/tree-sitter-upgrade-readiness.yml) — byte-identical so a matrix
-# format change that would silently break change-detection fails here. Group 2 is
-# ONLY the Status cell ([^|]+? before the final `|$`).
-_ROW_DIFF_RE = re.compile(r"\| `(tree-sitter-[^`]+)` \|.*\| ([^|]+?) \|$", re.M)
-# Mirrors the scheduled issue-update summary extraction in
-# tree-sitter-upgrade-readiness.yml. If the report prose changes again, the issue
-# comment should not silently degrade to "?/? ready. ? blocker(s)".
-_ISSUE_READY_RE = re.compile(
-    r"- (\d+)/(\d+) npm-installed grammars already accept tree-sitter@"
-)
-_ISSUE_BLOCKER_RE = re.compile(r"\*\*Blocked\*\* — (\d+) grammars? ")
-
-
-def _physical_vendor_grammars() -> set[str]:
-    vendor = _REPO_ROOT / "gitnexus" / "vendor"
-    return {
-        p.name
-        for p in vendor.iterdir()
-        if p.is_dir() and p.name.startswith("tree-sitter-")
-    }
-
-
-def _render_report() -> tuple[str, int]:
-    """Run main() with network mocked to mirror PRODUCTION; return (md, exit_code).
-
-    - npm grammars resolve to a permissive "Ready" peer dep, so the ONLY blocker
-      left is the held vendored tree-sitter-c — letting us assert the hold is
-      load-bearing (exit code stays non-zero because of it).
-    - npm_view_json records its calls so we can prove vendored grammars are never
-      npm-queried.
-    - fetch_text mirrors the real workflow: upstream parser.c resolves to a real
-      ABI (committed upstream), commit endpoints return a sha — EXCEPT swift's
-      upstream, whose parser.c is generated at build time and so is unreachable
-      (None). That single miss exercises the labeled-sentinel path; every other
-      cell must be a real value, never a bare '?'.
-    """
-    npm_calls: list[str] = []
-
-    def fake_npm_view_json(pkg: str):
-        npm_calls.append(pkg)
-        return {"version": "9.9.9", "peerDependencies": {"tree-sitter": "^0.25.0"}}
-
-    def fake_fetch_text(url: str, timeout: int = 8):
-        if "parser.c" in url:
-            # swift's upstream parser.c is generated at build time → unreachable;
-            # the others ship a committed parser.c.
-            if "alex-pinkus" in url:
-                return None
-            return "#define LANGUAGE_VERSION 14\n#define STATE_COUNT 1\n"
-        if "/commits/" in url:
-            return json.dumps({"sha": "0123456789abcdef"})
-        # package.json (relaxed-peer probe) etc. — not needed for these assertions.
-        return None
-
-    buf = io.StringIO()
-    with mock.patch.object(readiness, "npm_view_json", side_effect=fake_npm_view_json), \
-         mock.patch.object(readiness, "fetch_text", side_effect=fake_fetch_text), \
-         contextlib.redirect_stdout(buf):
-        code = readiness.main()
-    report = buf.getvalue()
-    _render_report.last_npm_calls = npm_calls  # type: ignore[attr-defined]
-    return report, code
-
-
-class ManifestClassification(TestCase):
-    def test_manifest_matches_physical_vendor_dirs(self):
-        """Consistency guard: the manifest set == the gitnexus/vendor/tree-sitter-*
-        dirs. Vendoring a grammar without a manifest entry (or vice-versa) fails —
-        this is what keeps the two tree-sitter workflows aligned (#858)."""
-        manifest_names = {
-            g["name"]
-            for g in json.loads(_MANIFEST.read_text())["grammars"].values()
-        }
-        self.assertEqual(manifest_names, _physical_vendor_grammars())
-
-    def test_vendored_names_loaded_from_manifest(self):
-        self.assertEqual(set(readiness.VENDORED_NAMES), _physical_vendor_grammars())
-        # npm-installed grammars must NOT be classified vendored.
-        self.assertNotIn("tree-sitter-cpp", readiness.VENDORED_NAMES)
-        self.assertNotIn("tree-sitter-go", readiness.VENDORED_NAMES)
-
-    def test_c_carries_a_hold_cpp_does_not(self):
-        self.assertTrue(readiness.VENDORED["tree-sitter-c"]["hold"])
-        self.assertNotIn("tree-sitter-c", readiness.INTENTIONAL_PINS)
-        # cpp stays an npm intentional pin.
-        self.assertIn("tree-sitter-cpp", readiness.INTENTIONAL_PINS)
-
-    def test_vendored_names_are_a_subset_of_GRAMMARS(self):
-        # The report + --assert-current iterate the hardcoded GRAMMARS dict for
-        # upstream-drift coords. A vendored grammar present in the manifest but
-        # missing from GRAMMARS would be silently dropped from both — re-creating
-        # the cross-workflow divergence the manifest exists to kill (#858). Guard it.
-        missing = set(readiness.VENDORED_NAMES) - set(readiness.GRAMMARS)
-        self.assertEqual(missing, set(), f"manifest grammars missing from GRAMMARS: {missing}")
-
-    def test_missing_manifest_raises_a_clear_error(self):
-        import pathlib
-        import tempfile
-
-        with tempfile.TemporaryDirectory() as d:
-            with mock.patch.object(readiness, "REPO_ROOT", pathlib.Path(d)):
-                with self.assertRaises(SystemExit) as ctx:
-                    readiness.load_vendored_manifest()
-        self.assertIn("vendored-grammars manifest", str(ctx.exception))
-
-    def test_malformed_manifest_raises_a_clear_error(self):
-        import pathlib
-        import tempfile
-
-        with tempfile.TemporaryDirectory() as d:
-            gh = pathlib.Path(d) / ".github"
-            gh.mkdir()
-            (gh / "vendored-grammars.json").write_text("{ not valid json", encoding="utf-8")
-            with mock.patch.object(readiness, "REPO_ROOT", pathlib.Path(d)):
-                with self.assertRaises(SystemExit) as ctx:
-                    readiness.load_vendored_manifest()
-        self.assertIn("not valid JSON", str(ctx.exception))
-
-    def test_path_traversal_grammar_name_is_rejected(self):
-        import pathlib
-        import tempfile
-
-        bad = '{"grammars": {"evil": {"name": "../etc"}}}'
-        with tempfile.TemporaryDirectory() as d:
-            gh = pathlib.Path(d) / ".github"
-            gh.mkdir()
-            (gh / "vendored-grammars.json").write_text(bad, encoding="utf-8")
-            with mock.patch.object(readiness, "REPO_ROOT", pathlib.Path(d)):
-                with self.assertRaises(SystemExit) as ctx:
-                    readiness.load_vendored_manifest()
-        self.assertIn("invalid grammar name", str(ctx.exception))
-
-
-class AssertCurrent(TestCase):
-    """The offline #1922 ABI gate (--assert-current) must stay hermetic — it reads
-    vendored ABIs from the repo, never the network. (Regression guard: a prior
-    revision routed vendored grammars through vendored_drift_summary, which fetches
-    upstream parser.c + commit sha, silently breaking the 'hermetic and offline'
-    contract — #858 review.)"""
-
-    def _run_assert_current(self):
-        import urllib.request
-
-        def explode(*a, **k):
-            raise AssertionError("--assert-current attempted a network call")
-
-        buf = io.StringIO()
-        with mock.patch.object(urllib.request, "urlopen", side_effect=explode), \
-             contextlib.redirect_stdout(buf):
-            code = readiness.assert_current()
-        return buf.getvalue(), code
-
-    def test_assert_current_is_network_free_and_passes(self):
-        report, code = self._run_assert_current()  # raises if any urlopen fires
-        self.assertEqual(code, 0)
-        # All 5 vendored grammars are introspected from the repo (ABI 14), not skipped.
-        for name in readiness.VENDORED_NAMES:
-            self.assertIn(f"{name}: vendored ABI", report)
-
-    def test_assert_current_fails_an_out_of_range_vendored_abi(self):
-        # vendored_abi_from_repo is the local-read injection point: force one
-        # grammar out of the current runtime's ABI window and assert the gate trips.
-        real = readiness.vendored_abi_from_repo
-
-        def fake(name, parser_path):
-            return 99 if name == "tree-sitter-dart" else real(name, parser_path)
-
-        import urllib.request
-        buf = io.StringIO()
-        with mock.patch.object(readiness, "vendored_abi_from_repo", side_effect=fake), \
-             mock.patch.object(urllib.request, "urlopen", side_effect=AssertionError("network")), \
-             contextlib.redirect_stdout(buf):
-            code = readiness.assert_current()
-        self.assertEqual(code, 1)
-        self.assertIn("tree-sitter-dart", buf.getvalue())
-        self.assertIn("outside current runtime range", buf.getvalue())
-
-
-class FetchHelperReadPhaseErrors(TestCase):
-    """Read-phase transport failures — raised by resp.read() AFTER urlopen has
-    returned (ConnectionResetError, ssl.SSLError, socket.timeout,
-    http.client.IncompleteRead) — are NOT urllib.error.URLError subclasses
-    (urllib only wraps connect-phase OSErrors). A prior revision's narrow except
-    tuple let them escape npm_view_json / fetch_text, crash main(), and empty
-    stdout — which makes the workflow's requireMatch throw on a non-drift
-    scheduled run. The helpers must swallow them to None so the grammar routes to
-    the fetch_failed blocker bucket and the report still renders completely."""
-
-    @staticmethod
-    def _patch_urlopen(*, read_returns=None, read_raises=None):
-        class _Resp:
-            def __enter__(self):
-                return self
-
-            def __exit__(self, *exc):
-                return False
-
-            def read(self, *a, **k):
-                if read_raises is not None:
-                    raise read_raises
-                return read_returns
-
-        def _fake_urlopen(*a, **k):
-            return _Resp()
-
-        import urllib.request
-
-        return mock.patch.object(urllib.request, "urlopen", side_effect=_fake_urlopen)
-
-    def test_npm_view_json_swallows_read_phase_connection_reset(self):
-        # ConnectionResetError is an OSError but NOT a URLError — the broadened
-        # OSError clause must catch it so the helper returns None, not raises.
-        with mock.patch.object(readiness, "OFFLINE", False), self._patch_urlopen(
-            read_raises=ConnectionResetError("peer reset mid-body")
-        ):
-            self.assertIsNone(readiness.npm_view_json("tree-sitter-anything"))
-
-    def test_fetch_text_swallows_read_phase_incomplete_read(self):
-        # http.client.IncompleteRead is an HTTPException (not OSError), so it must
-        # be named explicitly in the except tuple.
-        with mock.patch.object(readiness, "OFFLINE", False), self._patch_urlopen(
-            read_raises=http.client.IncompleteRead(partial=b"half")
-        ):
-            self.assertIsNone(readiness.fetch_text("https://example.com/parser.c"))
-
-    def test_npm_view_json_still_swallows_bad_json(self):
-        # JSONDecodeError is a ValueError, not an OSError — broadening the tuple
-        # must not drop it. Non-JSON body still yields None.
-        with mock.patch.object(readiness, "OFFLINE", False), self._patch_urlopen(
-            read_returns=b"<<not json>>"
-        ):
-            self.assertIsNone(readiness.npm_view_json("tree-sitter-anything"))
-
-
-class ReportRendering(TestCase):
-    @classmethod
-    def setUpClass(cls):
-        cls.report, cls.code = _render_report()
-        cls.rows = dict(_ROW_DIFF_RE.findall(cls.report))
-
-    def test_no_bare_question_mark_anywhere(self):
-        # The only legitimate '?' is the "Satisfies 0.25?" column header.
-        sanitized = self.report.replace("Satisfies 0.25?", "Satisfies 0.25")
-        self.assertNotIn("?", sanitized, "report still contains a bare '?' placeholder")
-
-    def test_malformed_npm_version_renders_unknown_in_prose_not_bare_question(self):
-        # A successful (200) npm /latest response that omits `version` leaves
-        # npm_version == "?"; the grammar is still bucketed (fetch did not fail), so
-        # its disposition PROSE line must show the labeled sentinel, never a bare '?'.
-        def fake_npm(pkg: str):
-            if pkg == "tree-sitter-go":
-                return {"peerDependencies": {"tree-sitter": "^0.25.0"}}  # no 'version'
-            return {"version": "9.9.9", "peerDependencies": {"tree-sitter": "^0.25.0"}}
-
-        def fake_fetch(url: str, timeout: int = 8):
-            if "parser.c" in url and "alex-pinkus" not in url:
-                return "#define LANGUAGE_VERSION 14\n"
-            if "/commits/" in url:
-                return json.dumps({"sha": "0123456789abcdef"})
-            return None
-
-        buf = io.StringIO()
-        with mock.patch.object(readiness, "npm_view_json", side_effect=fake_npm), \
-             mock.patch.object(readiness, "fetch_text", side_effect=fake_fetch), \
-             contextlib.redirect_stdout(buf):
-            readiness.main()
-        report = buf.getvalue()
-        sanitized = report.replace("Satisfies 0.25?", "Satisfies 0.25")
-        self.assertNotIn("?", sanitized)
-        # The Ready bucket prose line for go shows the labeled 'unknown', not '?'.
-        self.assertRegex(report, r"`tree-sitter-go`.*npm latest `unknown`")
-
-    def test_every_vendored_grammar_shows_numeric_abi_not_question_mark(self):
-        for name in readiness.VENDORED_NAMES:
-            row = self._matrix_row(name)
-            cells = [c.strip() for c in row.strip().strip("|").split("|")]
-            abi_cell = cells[5]  # Grammar|Pinned|npm|Peer|Satisfies|ABI|UpstreamABI|Status
-            self.assertRegex(
-                abi_cell, r"^\d+$",
-                f"{name} ABI cell is '{abi_cell}', expected a number (read from vendor/)",
-            )
-
-    def test_proto_is_never_npm_queried(self):
-        # github-only vendored grammars must skip the npm peer-dep path entirely,
-        # which is what removes the old "? (fetch failed)" for tree-sitter-proto.
-        self.assertNotIn("tree-sitter-proto", _render_report.last_npm_calls)
-        self.assertNotIn("tree-sitter-dart", _render_report.last_npm_calls)
-        self.assertNotIn("Could not check", self.report)
-        self.assertNotIn("fetch failed", self.report)
-
-    def test_held_c_renders_held_and_keeps_exit_nonzero(self):
-        # Status is the last matrix cell (the row-diff regex captures the whole
-        # tail, not just status, so read the cell directly).
-        cells = [c.strip() for c in self._matrix_row("tree-sitter-c").strip().strip("|").split("|")]
-        self.assertEqual(cells[-1], "Vendored — held")
-        self.assertIn("**Held:**", self.report)
-        # With every npm grammar mocked to "Ready", the ONLY remaining blocker is
-        # the held c — so a non-zero exit proves the hold is treated as a blocker.
-        self.assertEqual(self.code, 1)
-
-    def test_upstream_abi_miss_uses_labeled_sentinel(self):
-        # swift's upstream parser.c is unreachable (mocked None), so its
-        # upstream-ABI cell is the labeled 'n/a' token, never a bare '?'.
-        cells = [c.strip() for c in self._matrix_row("tree-sitter-swift").strip().strip("|").split("|")]
-        self.assertEqual(cells[6], "n/a")  # Upstream ABI column
-
-    def test_row_diff_regex_captures_all_fifteen_grammar_statuses(self):
-        # The change-detection bot keys on this regex: group 1 = grammar name,
-        # group 2 = the Status cell ONLY (not the whole tail). It must match every
-        # row after the format change so status transitions keep being detected.
-        self.assertEqual(len(self.rows), 15)
-        for name in readiness.VENDORED_NAMES:
-            self.assertIn(name, self.rows)
-        # group 2 is the Status cell — held c renders exactly "Vendored — held",
-        # and no captured status contains a pipe (proves cell-scoped capture).
-        self.assertEqual(self.rows["tree-sitter-c"], "Vendored — held")
-        for status in self.rows.values():
-            self.assertNotIn("|", status)
-
-    def test_issue_update_summary_regex_matches_current_report(self):
-        ready = _ISSUE_READY_RE.search(self.report)
-        blockers = _ISSUE_BLOCKER_RE.search(self.report)
-        self.assertIsNotNone(ready)
-        self.assertIsNotNone(blockers)
-        # Counts are derived from _render_report()'s mock corpus (all npm peer
-        # deps mocked permissive): of the 10 npm-installed grammars, 9 render
-        # Ready and 1 — tree-sitter-cpp — is the intentional pin (#1242), so it is
-        # not counted ready. The 2 blockers are that same pinned tree-sitter-cpp
-        # plus the vendored, ABI-held tree-sitter-c (the only out-of-range
-        # vendored grammar). If a grammar is added/removed or a pin/hold changes,
-        # update _render_report()'s mock AND these expected counts together; a
-        # mismatch here means the report prose drifted, not the regex.
-        self.assertEqual(ready.groups(), ("9", "10"))
-        self.assertEqual(blockers.group(1), "2")
-
-    def _matrix_row(self, name: str) -> str:
-        for line in self.report.splitlines():
-            if line.startswith(f"| `{name}` |"):
-                return line
-        # Explicit terminating raise (not self.fail, which CodeQL doesn't model as
-        # NoReturn) so the function has no implicit fall-through return (CodeQL 754).
-        raise AssertionError(f"no matrix row for {name}")
-
-
-class OfflineMode(TestCase):
-    """--offline must render the report touching ZERO network — vendored ABIs come
-    from the repo, npm columns are marked unverified. This is what makes the
-    network-dependent report deterministically testable in air-gapped CI."""
-
-    def _render_offline(self):
-        import urllib.request
-
-        def explode(*a, **k):
-            raise AssertionError("network call attempted in --offline mode")
-
-        buf = io.StringIO()
-        with mock.patch.object(readiness, "OFFLINE", True), \
-             mock.patch.object(urllib.request, "urlopen", side_effect=explode), \
-             contextlib.redirect_stdout(buf):
-            code = readiness.main()
-        return buf.getvalue(), code
-
-    def test_offline_touches_no_network_and_still_renders(self):
-        report, code = self._render_offline()  # raises if any urlopen fires
-        self.assertIn("Offline mode", report)
-        # Vendored grammars are introspected from the repo → real ABI 14, not a miss.
-        for name in readiness.VENDORED_NAMES:
-            row = next(l for l in report.splitlines() if l.startswith(f"| `{name}` |"))
-            cells = [c.strip() for c in row.strip().strip("|").split("|")]
-            self.assertRegex(cells[5], r"^\d+$", f"{name} vendored ABI missing offline")
-
-    def test_offline_marks_npm_grammars_offline_not_fetch_failed(self):
-        report, _ = self._render_offline()
-        self.assertIn("(offline)", report)
-        self.assertNotIn("fetch failed", report)  # honest: skipped, not failed
-
-    def test_offline_report_has_no_bare_question_mark(self):
-        report, _ = self._render_offline()
-        sanitized = report.replace("Satisfies 0.25?", "Satisfies 0.25")
-        self.assertNotIn("?", sanitized)
-
-
-class VendoredAbiBranches(TestCase):
-    """main()'s vendored-ABI classification reads through vendored_abi_from_repo
-    (the same local-read seam --assert-current uses), so a single patch drives the
-    out-of-range and prebuilt-only branches that no real vendor dir can trigger
-    today (all ship parser.c at ABI 14)."""
-
-    def _render_with_vendored_abi(self, override):
-        """Render main() with the standard production-faithful network mock plus a
-        vendored_abi_from_repo override (dict: name -> int|None; others read real)."""
-        real = readiness.vendored_abi_from_repo
-
-        def abi_seam(name, parser_path):
-            return override[name] if name in override else real(name, parser_path)
-
-        def fake_npm(pkg):
-            return {"version": "9.9.9", "peerDependencies": {"tree-sitter": "^0.25.0"}}
-
-        def fake_fetch(url, timeout=8):
-            if "parser.c" in url and "alex-pinkus" not in url:
-                return "#define LANGUAGE_VERSION 14\n"
-            if "/commits/" in url:
-                return json.dumps({"sha": "0123456789abcdef"})
-            return None
-
-        buf = io.StringIO()
-        with mock.patch.object(readiness, "vendored_abi_from_repo", side_effect=abi_seam), \
-             mock.patch.object(readiness, "npm_view_json", side_effect=fake_npm), \
-             mock.patch.object(readiness, "fetch_text", side_effect=fake_fetch), \
-             contextlib.redirect_stdout(buf):
-            code = readiness.main()
-        return buf.getvalue(), code
-
-    def _row(self, report, name):
-        line = next(l for l in report.splitlines() if l.startswith(f"| `{name}` |"))
-        return [c.strip() for c in line.strip().strip("|").split("|")]
-
-    def test_out_of_range_vendored_abi_is_a_blocker(self):
-        # Force tree-sitter-dart's vendored ABI outside the target range (13–15).
-        report, code = self._render_with_vendored_abi({"tree-sitter-dart": 99})
-        cells = self._row(report, "tree-sitter-dart")
-        self.assertEqual(cells[-1], "Vendored (ABI out of range)")
-        self.assertEqual(cells[5], "99")
-        self.assertEqual(code, 1)  # out-of-range vendored grammar is a blocker
-
-    def test_prebuilt_only_vendored_abi_renders_prebuilt_not_question(self):
-        # vendored_abi None (a future binary-only vendor with no parser.c).
-        report, _ = self._render_with_vendored_abi({"tree-sitter-dart": None})
-        cells = self._row(report, "tree-sitter-dart")
-        self.assertEqual(cells[5], "prebuilt")  # labeled, never a bare '?'
-        self.assertEqual(cells[4], "Yes")  # prebuilt is assumed target-compatible
-
-
-if __name__ == "__main__":
-    main()
@@ -1,363 +0,0 @@
-#!/usr/bin/env node
-/**
- * Vendored tree-sitter grammar update monitor.
- *
- * Checks each vendored grammar against its upstream source-of-origin and, for an
- * available AND ABI-compatible update, re-vendors the grammar source in place so
- * a PR can be opened. The version bump in vendor/<name>/package.json then triggers
- * .github/workflows/build-tree-sitter-prebuilds.yml, which cross-builds + ABI-
- * validates the prebuilds — so even an imperfect re-vendor can never silently
- * ship: its PR's CI goes red.
- *
- * ABI awareness is load-bearing. Every grammar is pinned to tree-sitter@0.21.1
- * (LANGUAGE_VERSION 13–14, the #1922 gate). Most upstream grammar releases target
- * a newer tree-sitter, so a blind "bump to latest" would pull an ABI-incompatible
- * parser and open doomed PRs. This monitor fetches the candidate source, reads its
- * parser.c `#define LANGUAGE_VERSION`, and only re-vendors when it is 13 or 14;
- * incompatible updates are reported (and surfaced as a workflow notice), not
- * applied.
- *
- * Usage:
- *   node update-vendored-grammars.mjs            # detect only → JSON report on stdout
- *   node update-vendored-grammars.mjs --apply X  # re-vendor grammar X in place
- *
- * tree-sitter-c is MONITORED but report-only (`hold`): it is ABI-pinned at 0.21.4
- * (#1242/#858) and must not auto-bump without a tree-sitter runtime upgrade, so an
- * available c update is detected + reported but never auto-applied — even if it is
- * ABI-13/14. A maintainer re-vendors it deliberately.
- */
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-const VENDOR = path.join(REPO_ROOT, 'gitnexus', 'vendor');
-
-const COMPATIBLE_ABI = new Set([13, 14]); // tree-sitter@0.21.1 LANGUAGE_VERSION range
-
-// Source-of-origin per grammar. npm grammars resolve `latest` via the registry;
-// github grammars (no usable npm release) track the default branch HEAD. A `hold`
-// reason makes a grammar report-only: updates are detected + surfaced but never
-// auto-applied (c is ABI-pinned and must not move without a runtime upgrade).
-//
-// The vendored set lives in .github/vendored-grammars.json — the SHARED source of
-// truth this monitor and .github/scripts/check-tree-sitter-upgrade-readiness.py both
-// read, so the two tree-sitter workflows can never disagree about which grammars are
-// vendored or where their upstream lives. We reshape the manifest's
-// `{ upstream: { npm | github } }` form into the flat `{ npm? , github? }` shape the
-// rest of this script consumes. This is a local file read (import-safe, no network).
-const MANIFEST = path.join(REPO_ROOT, '.github', 'vendored-grammars.json');
-// `raw` is injectable for testing; production reads the manifest file.
-function loadManifestGrammars(raw = null) {
-  if (raw === null) {
-    // Fail loud with a pointer, not a bare ENOENT/SyntaxError: this runs at import.
-    try {
-      raw = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
-    } catch (e) {
-      throw new Error(
-        `Could not load the vendored-grammars manifest at ${MANIFEST} ` +
-          `(shared source of truth — see CONTRIBUTING.md → CI automation contracts): ${e.message}`,
-      );
-    }
-  }
-  return Object.fromEntries(
-    Object.entries(raw.grammars || {}).map(([key, g]) => {
-      if (!g.name)
-        throw new Error(`manifest entry '${key}' is missing a 'name' field (${MANIFEST})`);
-      // Defense-in-depth: `name` is joined into gitnexus/vendor/<name> paths (and
-      // apply() WRITES there), so reject anything that isn't a plain grammar name
-      // before it can traverse the filesystem (#2187).
-      if (!/^tree-sitter-[a-z0-9-]+$/.test(g.name))
-        throw new Error(
-          `manifest entry '${key}' has an invalid grammar name '${g.name}' ` +
-            `(must match tree-sitter-[a-z0-9-]+)`,
-        );
-      return [
-        key,
-        {
-          name: g.name,
-          ...(g.upstream?.npm ? { npm: g.upstream.npm } : {}),
-          ...(g.upstream?.github ? { github: g.upstream.github } : {}),
-          ...(g.hold ? { hold: g.hold } : {}),
-        },
-      ];
-    }),
-  );
-}
-const GRAMMARS = loadManifestGrammars();
-
-const sh = (cmd, args, opts = {}) =>
-  execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
-
-const clean = (v) =>
-  String(v || '')
-    .replace(/^[v^~]/, '')
-    .trim();
-
-// Shared "is the candidate newer than what we ship?" check, used by BOTH detect()
-// and apply() so they can never disagree. up.version is the comparable identity for
-// both kinds: a plain semver for npm, and the `<base>-g<sha7>` provenance string for
-// github (which apply() also writes to package.json). detect() previously compared
-// the bare sha7 for github, so after the bot re-vendored a github grammar once it
-// reported a perpetual false "update available" while apply() saw "already current"
-// (#2187 review). Comparing up.version on both sides removes that asymmetry.
-const isNewer = (up, have) => !have || up.version !== have;
-
-// apply() throws this (instead of calling process.exit) so its error branches are
-// exercisable in-process by tests; the CLI entrypoint maps `.code` back to the
-// original exit code, keeping the monitor's subprocess contract identical (#2187).
-class ApplyExit extends Error {
-  constructor(message, code) {
-    super(message);
-    this.name = 'ApplyExit';
-    this.code = code;
-  }
-}
-
-function vendoredVersion(g) {
-  const p = path.join(VENDOR, g.name, 'package.json');
-  return clean(JSON.parse(fs.readFileSync(p, 'utf8')).version);
-}
-
-/** Resolve the upstream candidate: { version, ref, kind }. */
-function resolveUpstream(g) {
-  if (g.npm) {
-    const version = clean(sh('npm', ['view', g.npm, 'version']));
-    return { version, ref: version, kind: 'npm' };
-  }
-  // github: no reliable release tags here, so track the default branch HEAD sha.
-  const meta = JSON.parse(sh('gh', ['api', `repos/${g.github}`]));
-  const branch = meta.default_branch;
-  const sha = JSON.parse(sh('gh', ['api', `repos/${g.github}/commits/${branch}`])).sha;
-  // Version key: "<upstreamPkgVersion>-g<sha7>" — safeRef-compatible (no `+`,
-  // which the build workflow's ref validator rejects) and changes on every commit.
-  let base = '0.0.0';
-  try {
-    const pkg = JSON.parse(
-      Buffer.from(
-        JSON.parse(sh('gh', ['api', `repos/${g.github}/contents/package.json?ref=${sha}`])).content,
-        'base64',
-      ).toString('utf8'),
-    );
-    if (pkg.version) base = clean(pkg.version);
-  } catch {
-    /* no upstream package.json — base stays 0.0.0 */
-  }
-  return { version: `${base}-g${sha.slice(0, 7)}`, ref: sha, kind: 'github' };
-}
-
-/** Fetch the candidate source into a temp dir; return the package root. */
-function fetchSource(g, ref) {
-  const work = fs.mkdtempSync(
-    path.join(os.tmpdir(), `revendor-${Object.keys(GRAMMARS).find((k) => GRAMMARS[k] === g)}-`),
-  );
-  if (g.npm) {
-    sh('npm', ['pack', `${g.npm}@${ref}`, '--silent'], { cwd: work });
-    const tgz = fs.readdirSync(work).find((f) => f.endsWith('.tgz'));
-    sh('tar', ['xzf', tgz], { cwd: work });
-    return path.join(work, 'package');
-  }
-  // github tarball at the resolved sha. Download + extract WITHOUT a shell
-  // (no `bash -c`/redirect): `gh api` writes the binary tarball to stdout, which
-  // we capture as a Buffer and write to a fixed path, then extract with execFile.
-  // Avoids the shell-command-injection surface CodeQL flags when an API-derived
-  // ref is interpolated into a `bash -c` string.
-  const tgz = path.join(work, 'src.tgz');
-  fs.writeFileSync(
-    tgz,
-    execFileSync('gh', ['api', `repos/${g.github}/tarball/${ref}`], {
-      maxBuffer: 512 * 1024 * 1024,
-    }),
-  );
-  sh('tar', ['xzf', tgz], { cwd: work });
-  const dir = fs.readdirSync(work).find((f) => fs.statSync(path.join(work, f)).isDirectory());
-  return path.join(work, dir);
-}
-
-/** Read parser.c's LANGUAGE_VERSION (ABI). Prefer the ABI-14 default parser.c. */
-function readAbi(srcRoot) {
-  const candidates = ['src/parser.c', 'parser.c'];
-  for (const rel of candidates) {
-    const p = path.join(srcRoot, rel);
-    if (!fs.existsSync(p)) continue;
-    // Read only the head — the #define is near the top.
-    const head = fs.readFileSync(p, 'utf8').slice(0, 4000);
-    const m = head.match(/#define\s+LANGUAGE_VERSION\s+(\d+)/);
-    if (m) return Number(m[1]);
-  }
-  return null; // unknown (e.g. parser.c only generated at build time)
-}
-
-// `deps` injects the network/filesystem seams (vendoredVersion / resolveUpstream /
-// fetchSource / readAbi) so the classification logic — newer-detection, the ABI
-// gate, and the policy-hold gate — can be unit-tested offline with fixtures, never
-// touching live npm/GitHub. Production passes nothing and gets the real functions.
-function detect(deps = {}) {
-  const getVendored = deps.vendoredVersion || vendoredVersion;
-  const resolveUp = deps.resolveUpstream || resolveUpstream;
-  const fetchSrc = deps.fetchSource || fetchSource;
-  const readAbiFn = deps.readAbi || readAbi;
-  const report = [];
-  for (const [key, g] of Object.entries(GRAMMARS)) {
-    const have = getVendored(g);
-    let up;
-    try {
-      up = resolveUp(g);
-    } catch (err) {
-      report.push({ grammar: key, error: String(err.message || err) });
-      continue;
-    }
-    const newer = isNewer(up, have);
-    let abi = null;
-    if (newer) {
-      try {
-        abi = readAbiFn(fetchSrc(g, up.ref));
-      } catch {
-        /* fetch/abi best-effort; null = unknown */
-      }
-    }
-    report.push({
-      grammar: key,
-      vendored: have,
-      upstream: up.version,
-      ref: up.ref,
-      kind: up.kind,
-      update: newer,
-      abi,
-      abiCompatible: abi == null ? null : COMPATIBLE_ABI.has(abi),
-      hold: g.hold || null,
-      // Auto-appliable only when there's an update, the ABI is known-compatible,
-      // AND the grammar is not on a policy hold (c).
-      applicable: newer && abi != null && COMPATIBLE_ABI.has(abi) && !g.hold,
-    });
-  }
-  return report;
-}
-
-const copyFile = (srcRoot, dest, rel) => {
-  const from = path.join(srcRoot, rel);
-  if (!fs.existsSync(from)) return false;
-  const to = path.join(dest, rel);
-  fs.mkdirSync(path.dirname(to), { recursive: true });
-  fs.copyFileSync(from, to);
-  return true;
-};
-
-/**
- * Re-vendor one grammar in place from its ABI-compatible upstream candidate.
- * Copies ONLY the generated source-build + runtime files; deliberately KEEPS the
- * GitNexus-hardened binding.gyp (Windows cflags, target_name), README (vendor
- * notice), LICENSE, and prebuilds/ (the build workflow refreshes those). Bumps the
- * stripped vendor package.json version + provenance — never re-introduces
- * scripts/dependencies (#836/#1728). Returns the new version.
- *
- * opts.dryRun resolves + ABI-validates the candidate but writes NOTHING — it logs
- * what it would re-vendor and returns the version, so the flow can be rehearsed
- * (locally or in CI) without mutating gitnexus/vendor/. opts.deps injects the
- * network/fs seams for offline testing (same shape as detect()).
- */
-function apply(key, opts = {}) {
-  const dryRun = opts.dryRun || false;
-  const deps = opts.deps || {};
-  const getVendored = deps.vendoredVersion || vendoredVersion;
-  const resolveUp = deps.resolveUpstream || resolveUpstream;
-  const fetchSrc = deps.fetchSource || fetchSource;
-  const readAbiFn = deps.readAbi || readAbi;
-  const g = GRAMMARS[key];
-  if (!g) throw new ApplyExit(`unknown grammar '${key}'`, 2);
-  if (g.hold)
-    throw new ApplyExit(
-      `${key}: report-only (${g.hold}); not auto-applied. Re-vendor manually if intended.`,
-      3,
-    );
-  const have = getVendored(g);
-  const up = resolveUp(g);
-  const newer = isNewer(up, have);
-  if (!newer) {
-    // Already current: nothing to apply. Return (exit 0 via the CLI) — NOT an error.
-    console.error(`${key}: already current (${have}); nothing to apply.`);
-    return have;
-  }
-  const srcRoot = fetchSrc(g, up.ref);
-  const abi = readAbiFn(srcRoot);
-  if (abi == null || !COMPATIBLE_ABI.has(abi))
-    throw new ApplyExit(
-      `${key}: candidate ${up.version} is ABI ${abi ?? 'unknown'} — not tree-sitter@0.21.1 ` +
-        `compatible (need 13/14); refusing to re-vendor. Handle manually.`,
-      3,
-    );
-
-  if (dryRun) {
-    console.log(
-      `${key}: [dry-run] would re-vendor ${g.name} → ${up.version} (ABI ${abi}); no files written.`,
-    );
-    return up.version;
-  }
-
-  const dest = path.join(VENDOR, g.name);
-  // The source-build inputs + runtime entrypoints that change between versions.
-  // binding.gyp / README / LICENSE / prebuilds are intentionally NOT touched.
-  for (const rel of [
-    'src/parser.c',
-    'src/scanner.c',
-    'src/node-types.json',
-    'src/tree_sitter/alloc.h',
-    'src/tree_sitter/array.h',
-    'src/tree_sitter/parser.h',
-    'bindings/node/binding.cc',
-    'bindings/node/index.js',
-    'bindings/node/index.d.ts',
-  ]) {
-    copyFile(srcRoot, dest, rel);
-  }
-
-  const pkgPath = path.join(dest, 'package.json');
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-  pkg.version = up.version;
-  pkg._vendoredBy =
-    `gitnexus - re-vendored from ${g.npm ? `npm ${g.npm}@${up.version}` : `${g.github}@${up.ref}`} ` +
-    `by grammar-update-monitor on ABI ${abi}. Source-build inputs (parser.c/scanner.c/src/) refreshed; ` +
-    `the GitNexus-hardened binding.gyp + vendor README + prebuilds are preserved (prebuilds are ` +
-    `rebuilt by build-tree-sitter-prebuilds.yml on this version change). No scripts/dependencies here ` +
-    `(#836/#1728).`;
-  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-
-  console.log(`${key}: re-vendored ${g.name} → ${up.version} (ABI ${abi}).`);
-  return up.version;
-}
-
-// Run the CLI only when invoked directly (not when imported by a test) — detect()
-// makes live network calls, so importing must be side-effect-free.
-const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMain) {
-  const args = process.argv.slice(2);
-  const dryRun = args.includes('--dry-run');
-  if (args[0] === '--apply') {
-    // `--apply <grammar> [--dry-run]` — --dry-run previews without writing.
-    // Map apply()'s thrown ApplyExit back to the original exit codes (0/2/3) so
-    // the monitor workflow's subprocess (which only distinguishes zero vs non-zero)
-    // sees identical behavior.
-    try {
-      apply(args[1], { dryRun });
-    } catch (e) {
-      console.error(e.message);
-      process.exit(e instanceof ApplyExit ? e.code : 1);
-    }
-  } else {
-    process.stdout.write(JSON.stringify(detect(), null, 2) + '\n');
-  }
-}
-
-export {
-  detect,
-  apply,
-  resolveUpstream,
-  readAbi,
-  vendoredVersion,
-  loadManifestGrammars,
-  GRAMMARS,
-  COMPATIBLE_ABI,
-};
@@ -1,26 +0,0 @@
-{
-  "_comment": "Single source of truth for the VENDORED SET + policy holds, read by BOTH .github/scripts/update-vendored-grammars.mjs (weekly auto-PR bot) and .github/scripts/check-tree-sitter-upgrade-readiness.py (daily readiness report -> issue #858). The monitor also resolves each grammar's upstream from the `upstream` field here; the readiness report reads vendored ABIs from gitnexus/vendor/<name>/src/parser.c and keeps its own upstream-drift coords. A consistency-guard test asserts this set equals the gitnexus/vendor/tree-sitter-* directories. See CONTRIBUTING.md.",
-  "grammars": {
-    "c": {
-      "name": "tree-sitter-c",
-      "upstream": { "npm": "tree-sitter-c" },
-      "hold": "ABI-pinned at 0.21.4 (#1242/#858) — needs a tree-sitter runtime upgrade before bumping"
-    },
-    "swift": {
-      "name": "tree-sitter-swift",
-      "upstream": { "npm": "tree-sitter-swift" }
-    },
-    "kotlin": {
-      "name": "tree-sitter-kotlin",
-      "upstream": { "npm": "tree-sitter-kotlin" }
-    },
-    "dart": {
-      "name": "tree-sitter-dart",
-      "upstream": { "github": "UserNobody14/tree-sitter-dart" }
-    },
-    "proto": {
-      "name": "tree-sitter-proto",
-      "upstream": { "github": "coder3101/tree-sitter-proto" }
-    }
-  }
-}
@@ -1,529 +0,0 @@
-name: Build tree-sitter prebuilds
-
-# Cross-builds the native tree-sitter prebuilds GitNexus vendors itself, so that
-# grammars whose upstream packages ship SOURCE ONLY (no usable prebuilds/) never
-# require a C/C++ toolchain at a user's install. This is the "no operational
-# risk for any tree-sitter grammar" pipeline.
-#
-# Grammars covered here (the at-risk set — everything else already ships 6
-# upstream prebuilds AND stays dependency-review-tracked, so it is left alone).
-# All five are vendored under gitnexus/vendor/; `kind` (below) only picks where
-# the build job fetches the C source to compile:
-#   - tree-sitter-c      (vendored prebuild-only; built from the published npm
-#                         package — closes upstream's 4/6 ARM gap #2116 for a
-#                         REQUIRED grammar)
-#   - tree-sitter-dart   (vendored source; built from gitnexus/vendor/)
-#   - tree-sitter-proto  (vendored source; built from gitnexus/vendor/)
-#   - tree-sitter-kotlin (vendored source; built from the published npm package —
-#                         upstream ships source only)
-#   - tree-sitter-swift  (vendored source; built from gitnexus/vendor/ — its
-#                         prebuilds were originally upstream-shipped, now
-#                         GitNexus-cross-built like the rest for uniformity)
-#
-# Output: gitnexus/vendor/<grammar>/prebuilds/<platform-arch>/<grammar>.node for
-# all 6 targets ({linux,darwin,win32}-{x64,arm64}). tree-sitter grammars are
-# N-API, so one ABI-stable .node per platform-arch works across all Node majors.
-#
-# COST DISCIPLINE — this is a HEAVY native matrix (up to 3 grammars x 6 runners,
-# incl. macOS + arm64). It is DELIBERATELY NOT wired into normal PR/push CI. It
-# runs only:
-#   1. on manual dispatch (workflow_dispatch); or
-#   2. when a covered grammar's recorded version actually CHANGES — the `guard`
-#      job is the real gate (it diffs the recorded version vs the PR base); the
-#      `paths:` filter below only makes ordinary code PRs cost ZERO matrix time.
-# Net effect: an ordinary code PR triggers nothing; bumping one grammar costs
-# exactly one matrix run for that grammar, which opens a PR committing its rebuilt
-# binaries.
-#
-# Concurrency convention: see CONTRIBUTING.md -> "GitHub Actions — Concurrency Convention".
-#
-# NOTE: every action below is pinned to a release commit SHA (with the matching
-# `# vX.Y.Z` tag comment verified against the GitHub API). If a future bump adds
-# a new action, pin its real release SHA and allowlist it in .github/zizmor.yml /
-# Scorecard before merge.
-
-on:
-  workflow_dispatch:
-    inputs:
-      grammars:
-        description: 'Comma-separated grammar shortnames to build (c,dart,proto,kotlin,swift), or "all".'
-        required: false
-        type: string
-        default: 'all'
-      ref:
-        description: 'Upstream version/tag/sha override (only honored when exactly one grammar is selected).'
-        required: false
-        type: string
-        default: ''
-      force:
-        description: 'Build even if the recorded version is unchanged (re-cut a broken prebuild).'
-        required: false
-        type: boolean
-        default: false
-      open_pr:
-        description: 'Open a PR with the rebuilt prebuilds (false = artifacts only).'
-        required: false
-        type: boolean
-        default: true
-  pull_request:
-    branches: [main]
-    paths:
-      # Vendored grammars: their version lives in the vendor snapshot package.json.
-      - 'gitnexus/vendor/tree-sitter-c/package.json'
-      - 'gitnexus/vendor/tree-sitter-dart/package.json'
-      - 'gitnexus/vendor/tree-sitter-proto/package.json'
-      - 'gitnexus/vendor/tree-sitter-kotlin/package.json'
-      - 'gitnexus/vendor/tree-sitter-swift/package.json'
-      # Transition window: kotlin's pin still lives here until it is vendored.
-      - 'gitnexus/package.json'
-      # Self-test: re-run the guard (normally a no-op) when the recipe changes.
-      - '.github/workflows/build-tree-sitter-prebuilds.yml'
-
-# Least privilege by default; only `aggregate` opts up.
-permissions:
-  contents: read
-
-# One slot per ref. Collapse PR re-pushes, but never cancel a manual re-cut.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  # ── Gate: decide which grammars (if any) need a native rebuild, and emit the
-  #    {grammar x platform-arch} matrix the build job consumes. ───────────────
-  guard:
-    name: Decide what to build
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-    permissions:
-      contents: read
-    outputs:
-      any: ${{ steps.decide.outputs.any }}
-      matrix: ${{ steps.decide.outputs.matrix }}
-      release_app: ${{ steps.relapp.outputs.configured }}
-    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 0 # need base history to diff recorded versions
-          persist-credentials: false
-
-      - name: Decide
-        id: decide
-        env:
-          EVENT: ${{ github.event_name }}
-          # Untrusted dispatch inputs — read via env only, validated in JS.
-          INPUT_GRAMMARS: ${{ inputs.grammars }}
-          INPUT_REF: ${{ inputs.ref }}
-          FORCE: ${{ github.event_name == 'workflow_dispatch' && inputs.force || 'false' }}
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-        run: |
-          set -euo pipefail
-          node --input-type=module - <<'NODE'
-          import { execSync } from 'node:child_process';
-          import fs from 'node:fs';
-          import { appendFileSync } from 'node:fs';
-
-          // Registry of the at-risk grammars this workflow owns. `kind` drives
-          // how the build job resolves source: 'npm' pulls the published package;
-          // 'vendored' builds from gitnexus/vendor/<name> (which carries the C
-          // source + binding.gyp). Extend this list to cover a new grammar.
-          const REGISTRY = {
-            // c is vendored prebuild-only but BUILT from the published npm
-            // package (kind 'npm'), held at 0.21.4 — it closes upstream's 4/6
-            // ARM gap (#2116) for a REQUIRED grammar that otherwise hard-fails
-            // install on toolchain-less ARM.
-            c:      { name: 'tree-sitter-c',      kind: 'npm' },
-            dart:   { name: 'tree-sitter-dart',   kind: 'vendored' },
-            proto:  { name: 'tree-sitter-proto',  kind: 'vendored' },
-            kotlin: { name: 'tree-sitter-kotlin', kind: 'npm' },
-            // swift is vendored WITH its source (parser.c/scanner.c/binding.gyp),
-            // so it builds from gitnexus/vendor/ like dart/proto. Its prebuilds
-            // were originally upstream-shipped; rebuilding them here unifies it.
-            swift:  { name: 'tree-sitter-swift',  kind: 'vendored' },
-          };
-          const PLATFORMS = [
-            { platform_arch: 'linux-x64',    os: 'ubuntu-24.04' },
-            { platform_arch: 'linux-arm64',  os: 'ubuntu-24.04-arm' },
-            { platform_arch: 'darwin-arm64', os: 'macos-15' },
-            { platform_arch: 'darwin-x64',   os: 'macos-15-intel' }, // macos-13 retired Dec-2025; Intel EOL ~Aug-2027
-            { platform_arch: 'win32-x64',    os: 'windows-2022' },
-            { platform_arch: 'win32-arm64',  os: 'windows-11-arm' },
-          ];
-
-          const clean = (v) => (v || '').replace(/^[\^~]/, '').trim();
-          const json = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
-
-          // Durable version key for a grammar at a checkout root. Prefer the
-          // vendor snapshot (the post-vendor source of truth); fall back to the
-          // optionalDependencies pin during the transition window. (A guard keyed
-          // on the node_modules lock entry would self-disable once a grammar is
-          // vendored, because that entry is deleted.)
-          function recordedVersion(root, name) {
-            const v = json(`${root}/gitnexus/vendor/${name}/package.json`);
-            if (v && v.version) return clean(v.version);
-            const pkg = json(`${root}/gitnexus/package.json`);
-            const od = pkg && (pkg.optionalDependencies || {});
-            const d = pkg && (pkg.dependencies || {});
-            return clean((od && od[name]) || (d && d[name]) || '');
-          }
-
-          const event = process.env.EVENT;
-          const force = process.env.FORCE === 'true';
-
-          // Select which grammar shortnames are in play.
-          let selected;
-          if (event === 'workflow_dispatch') {
-            const raw = (process.env.INPUT_GRAMMARS || 'all').trim();
-            selected = raw === 'all' ? Object.keys(REGISTRY)
-              : raw.split(',').map((s) => s.trim()).filter(Boolean);
-            for (const s of selected) if (!REGISTRY[s]) throw new Error(`unknown grammar '${s}'`);
-          } else {
-            selected = Object.keys(REGISTRY);
-          }
-
-          // Resolve the base-ref recorded versions (pull_request only) so we can
-          // diff. On dispatch, base is irrelevant (manual intent / force wins).
-          const baseRoot = `${process.env.RUNNER_TEMP}/base`;
-          if (event === 'pull_request') {
-            const baseSha = process.env.BASE_SHA;
-            for (const s of selected) {
-              const name = REGISTRY[s].name;
-              for (const rel of [`gitnexus/vendor/${name}/package.json`, `gitnexus/package.json`]) {
-                const dst = `${baseRoot}/${rel}`;
-                fs.mkdirSync(dst.slice(0, dst.lastIndexOf('/')), { recursive: true });
-                try {
-                  const buf = execSync(`git show ${baseSha}:${rel}`, { stdio: ['ignore', 'pipe', 'ignore'] });
-                  fs.writeFileSync(dst, buf);
-                } catch { /* file absent at base — fine */ }
-              }
-            }
-          }
-
-          // The single-ref override is only meaningful for a one-grammar dispatch.
-          const refOverride = clean(process.env.INPUT_REF);
-          if (refOverride && !(event === 'workflow_dispatch' && selected.length === 1)) {
-            throw new Error('ref override requires exactly one grammar selected');
-          }
-          const safeRef = (r) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(r);
-
-          const include = [];
-          const built = [];
-          for (const short of selected) {
-            const { name, kind } = REGISTRY[short];
-            const head = recordedVersion('.', name);
-            const ref = refOverride || head;
-            if (!ref) { console.log(`skip ${short}: no recorded version`); continue; }
-            if (!safeRef(ref)) throw new Error(`unsafe ref for ${short}: '${ref}'`);
-
-            let build = false;
-            if (event === 'workflow_dispatch') {
-              build = true; // manual intent (force toggles only the unchanged-guard, which is bypassed here)
-            } else {
-              const base = recordedVersion(baseRoot, name);
-              build = !!head && head !== base;
-              console.log(`${short}: head='${head || '<absent>'}' base='${base || '<absent>'}' -> ${build ? 'BUILD' : 'skip'}`);
-            }
-            if (force) build = true;
-            if (!build) continue;
-            built.push(short);
-            for (const p of PLATFORMS) include.push({ grammar: short, name, kind, ref, ...p });
-          }
-
-          const out = process.env.GITHUB_OUTPUT;
-          appendFileSync(out, `any=${include.length > 0}\n`);
-          appendFileSync(out, `matrix=${JSON.stringify({ include })}\n`);
-          if (include.length === 0) {
-            console.log('::notice::No covered grammar version changed — skipping native matrix.');
-          } else {
-            console.log(`Building: ${built.join(', ')} (${include.length} jobs)`);
-          }
-          NODE
-
-      # The aggregate job opens a PR via a GitHub App token; without the App
-      # secrets it would hard-fail AFTER a full native build. Surface their
-      # presence as a guard output so aggregate skips cleanly (the build job's
-      # artifacts still upload). secrets aren't available in a job-level `if:`,
-      # so we compute the boolean here (a step CAN read secrets) and gate on it.
-      - name: Check release App secret
-        id: relapp
-        env:
-          HAS_APP: ${{ secrets.RELEASE_APP_ID != '' && secrets.RELEASE_APP_PRIVATE_KEY != '' }}
-        run: |
-          set -euo pipefail
-          echo "configured=$HAS_APP" >> "$GITHUB_OUTPUT"
-          if [ "$HAS_APP" != "true" ]; then
-            echo "::notice::Release GitHub App secrets (RELEASE_APP_ID / RELEASE_APP_PRIVATE_KEY) are not configured — prebuilds will build and upload as artifacts, but the auto-PR is skipped. Provision the App, or run with open_pr=false to suppress this notice."
-          fi
-
-  # ── Build one native prebuild per (grammar, platform-arch). No cross-compile. ─
-  build:
-    name: ${{ matrix.grammar }} ${{ matrix.platform_arch }}
-    needs: guard
-    if: needs.guard.outputs.any == 'true'
-    permissions:
-      contents: read
-    strategy:
-      fail-fast: false
-      matrix: ${{ fromJSON(needs.guard.outputs.matrix) }}
-    runs-on: ${{ matrix.os }}
-    # 45 (not 30) for headroom: the kotlin parser.c is ~23 MB and swift's ~18 MB,
-    # and compiling them under emulation on the arm runners is slow.
-    timeout-minutes: 45
-    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false # this job uploads artifacts (artipacked)
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-
-      - name: Ensure Python (arm64 Windows only)
-        if: matrix.platform_arch == 'win32-arm64'
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: '3.12'
-
-      - name: Build prebuild
-        id: build
-        shell: bash
-        env:
-          GRAMMAR: ${{ matrix.grammar }}
-          NAME: ${{ matrix.name }}
-          KIND: ${{ matrix.kind }}
-          REF: ${{ matrix.ref }}
-          PLATFORM_ARCH: ${{ matrix.platform_arch }}
-        run: |
-          set -euo pipefail
-          work="$RUNNER_TEMP/ts-build"
-          rm -rf "$work"; mkdir -p "$work"; cd "$work"
-          npm init -y >/dev/null
-
-          # node-addon-api must match what the grammar's binding.cc expects.
-          # GitNexus hoists ^8 for the vendored grammars; npm grammars declare
-          # their own (do NOT pin it for npm grammars — let the dep resolve it).
-          if [ "$KIND" = "vendored" ]; then
-            # Build from the vendored C source (carries parser.c + binding.gyp).
-            srcdir="$work/$NAME"
-            cp -R "$GITHUB_WORKSPACE/gitnexus/vendor/$NAME" "$srcdir"
-            rm -rf "$srcdir/prebuilds" "$srcdir/build" "$srcdir/node_modules"
-            npm install --no-audit --no-fund --ignore-scripts \
-              prebuildify@^6 node-gyp@^11 node-addon-api@^8
-            pkgdir="$srcdir"
-            export npm_config_node_gyp="$work/node_modules/node-gyp/bin/node-gyp.js"
-          else
-            # Pull the published source-only package.
-            npm install --no-audit --no-fund --ignore-scripts \
-              "$NAME@${REF}" prebuildify@^6 node-gyp@^11
-            pkgdir="$work/node_modules/$NAME"
-          fi
-
-          test -f "$pkgdir/binding.gyp" || { echo "::error::no binding.gyp for $NAME@$REF"; exit 1; }
-
-          # Drop any prebuilds the package shipped in its own tarball before we
-          # build. The tree-sitter-org npm grammars (e.g. tree-sitter-c) bundle
-          # prebuilds/ for all 6 tuples; left in place, the `find ... -print -quit`
-          # below would pick a non-host tuple (e.g. win32-x64 on a linux runner)
-          # and the assertion would wrongly fail. prebuildify rebuilds THIS host's
-          # tuple from the source the tarball also ships. (Vendored grammars are
-          # already cleaned above; this also covers the npm branch.)
-          rm -rf "$pkgdir/prebuilds"
-
-          # N-API, stripped, single ABI-stable binary for THIS host's arch. No
-          # `-t <node-version>`: an N-API prebuild is Node-version-agnostic, and
-          # prebuildify parses a bare `-t 22` as the NUMBER 22 and crashes
-          # (`v.indexOf is not a function`). prebuildify emits
-          # prebuilds/<platform>-<arch>/<something>.node.
-          ( cd "$pkgdir" && npx --no-install prebuildify --napi --strip )
-
-          out=$(find "$pkgdir/prebuilds" -name '*.node' -print -quit)
-          test -n "$out" || { echo "::error::prebuildify produced no .node"; exit 1; }
-          produced=$(basename "$(dirname "$out")")
-          [ "$produced" = "$PLATFORM_ARCH" ] || { echo "::error::built $produced, expected $PLATFORM_ARCH"; exit 1; }
-
-          stage="$RUNNER_TEMP/stage/$GRAMMAR/$PLATFORM_ARCH"; mkdir -p "$stage"
-          cp "$out" "$stage/$NAME.node"
-          echo "stage=$stage" >> "$GITHUB_OUTPUT"
-
-      - name: Validate the .node loads and parses on this arch
-        shell: bash
-        env:
-          GRAMMAR: ${{ matrix.grammar }}
-          NAME: ${{ matrix.name }}
-          PLATFORM_ARCH: ${{ matrix.platform_arch }}
-          EXPECT_ARCH: ${{ contains(matrix.platform_arch, 'arm64') && 'arm64' || 'x64' }}
-        run: |
-          set -euo pipefail
-          probe="$RUNNER_TEMP/probe"; rm -rf "$probe"
-          mkdir -p "$probe/prebuilds/$PLATFORM_ARCH"
-          cp "$RUNNER_TEMP/stage/$GRAMMAR/$PLATFORM_ARCH/$NAME.node" \
-             "$probe/prebuilds/$PLATFORM_ARCH/$NAME.node"
-          cd "$probe"
-          # Pin tree-sitter to the repo's exact runtime peer so an ABI mismatch
-          # fails HERE, not in a user's install (mirrors the #1922 ABI gate).
-          # NOT --ignore-scripts: tree-sitter@0.21.1's tarball ships prebuilds for
-          # the common tuples but NOT linux-arm64 / win32-arm64, so on the arm64
-          # runners node-gyp-build must source-build the runtime — give it node-gyp
-          # + node-addon-api to do so. Where tree-sitter ships a prebuild (x64,
-          # darwin-arm64) node-gyp-build uses it and nothing compiles. The grammar
-          # .node we built is still loaded as a prebuild; only the runtime peer may
-          # compile. The grammar-vs-runtime ABI check still fires at setLanguage.
-          npm install --no-audit --no-fund \
-            node-gyp-build@^4 node-gyp@^11 node-addon-api@^8 tree-sitter@0.21.1
-          # The node script is single-quoted on purpose — its ${...} are JS
-          # template literals read from the environment, not shell expansions.
-          # shellcheck disable=SC2016
-          GRAMMAR="$GRAMMAR" EXPECT_ARCH="$EXPECT_ARCH" node -e '
-            const expect = process.env.EXPECT_ARCH;
-            // Catch an emulated x64 Node silently mis-passing on an arm64 runner.
-            if (process.arch !== expect) throw new Error(`runner arch ${process.arch} != ${expect}`);
-            const snippets = {
-              c:      "int main(void) { return 0; }",
-              dart:   "void main() { print(\"hi\"); }",
-              proto:  "syntax = \"proto3\";\nmessage M { int32 id = 1; }",
-              kotlin: "fun main() { println(\"hi\") }",
-              swift:  "func greet() { print(\"hi\") }",
-            };
-            const lang = require("node-gyp-build")(process.cwd());
-            const Parser = require("tree-sitter");
-            const p = new Parser(); p.setLanguage(lang);
-            const tree = p.parse(snippets[process.env.GRAMMAR]);
-            if (!tree || !tree.rootNode || tree.rootNode.hasError) {
-              throw new Error("parse failed/error: " + (tree && tree.rootNode && tree.rootNode.type));
-            }
-            console.log("OK", process.env.GRAMMAR, process.platform + "-" + process.arch, tree.rootNode.type);
-          '
-
-      - name: Upload prebuild artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: ts-prebuild-${{ matrix.grammar }}-${{ matrix.platform_arch }}
-          path: ${{ steps.build.outputs.stage }}/${{ matrix.name }}.node
-          if-no-files-found: error
-          retention-days: 7
-
-  # ── Aggregate every grammar's six prebuilds, assert completeness, open a PR. ─
-  aggregate:
-    name: Vendor prebuilds + open PR
-    needs: [guard, build]
-    # Open the prebuild PR on a non-fork pull_request that bumped a grammar
-    # version (the documented version-change -> prebuild-PR flow), or on a manual
-    # dispatch with open_pr=true. Event-gating is explicit so we never rely on
-    # GHA coercing a null `inputs.open_pr` on pull_request events (Codex F4):
-    # `inputs.open_pr` is null off-dispatch, and `null != false` is direction-
-    # ambiguous, so `open_pr` is only consulted on workflow_dispatch.
-    if: >-
-      needs.guard.outputs.any == 'true' &&
-      needs.guard.outputs.release_app == 'true' &&
-      github.event.pull_request.head.repo.fork != true &&
-      (github.event_name == 'pull_request' || inputs.open_pr == true)
-    runs-on: ubuntu-24.04
-    timeout-minutes: 15
-    permissions:
-      contents: read # actual writes use a short-lived App token below
-      id-token: write # SLSA provenance attestation
-      attestations: write
-    steps:
-      - name: Mint GitHub App token
-        id: app-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          app-id: ${{ secrets.RELEASE_APP_ID }}
-          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
-
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-          persist-credentials: false
-
-      - name: Download all prebuild artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          path: ${{ runner.temp }}/dl
-          pattern: ts-prebuild-*
-
-      - name: Place prebuilds, assert each built grammar has all 6, write SHA256SUMS
-        id: place
-        shell: bash
-        env:
-          MATRIX: ${{ needs.guard.outputs.matrix }}
-          DL: ${{ runner.temp }}/dl
-        run: |
-          set -euo pipefail
-          node --input-type=module - <<'NODE'
-          import fs from 'node:fs';
-          import { execSync } from 'node:child_process';
-          const include = JSON.parse(process.env.MATRIX).include;
-          const dl = process.env.DL;
-          const byGrammar = {};
-          for (const e of include) (byGrammar[e.grammar] ||= { name: e.name, archs: [] }).archs.push(e.platform_arch);
-          const PLATFORMS = ['linux-x64','linux-arm64','darwin-arm64','darwin-x64','win32-x64','win32-arm64'];
-          const changed = [];
-          for (const [grammar, { name }] of Object.entries(byGrammar)) {
-            const dest = `gitnexus/vendor/${name}/prebuilds`;
-            // A vendored grammar with 5/6 prebuilds silently breaks node-gyp-build
-            // on the 6th platform — refuse a partial result.
-            for (const pa of PLATFORMS) {
-              const art = `${dl}/ts-prebuild-${grammar}-${pa}/${name}.node`;
-              if (!fs.existsSync(art)) throw new Error(`missing ${grammar} prebuild for ${pa}`);
-              fs.mkdirSync(`${dest}/${pa}`, { recursive: true });
-              fs.copyFileSync(art, `${dest}/${pa}/${name}.node`);
-            }
-            execSync(`cd ${dest} && find . -name '*.node' | sort | xargs sha256sum > SHA256SUMS`);
-            changed.push(name);
-          }
-          fs.appendFileSync(process.env.GITHUB_OUTPUT, `grammars=${changed.join(',')}\n`);
-          console.log('Vendored prebuilds for:', changed.join(', '));
-          NODE
-
-      - name: Attest build provenance (SLSA)
-        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
-        with:
-          subject-path: 'gitnexus/vendor/tree-sitter-*/prebuilds/**/*.node'
-
-      - name: Create or update PR
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        env:
-          GRAMMARS: ${{ steps.place.outputs.grammars }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-        with:
-          github-token: ${{ steps.app-token.outputs.token }}
-          script: |
-            const { execSync } = require('node:child_process');
-            const run = (c) => execSync(c, { stdio: ['ignore', 'pipe', 'inherit'] }).toString().trim();
-            const grammars = process.env.GRAMMARS;
-            const slug = grammars.replace(/[^a-z0-9]+/gi, '-');
-            const branch = `chore/vendor-ts-prebuilds-${slug}-${context.runId}`;
-
-            run('git add gitnexus/vendor/tree-sitter-*/prebuilds');
-            if (!run('git status --porcelain -- gitnexus/vendor/tree-sitter-*/prebuilds')) {
-              core.notice('Prebuilds byte-identical to vendor; nothing to commit.');
-              return;
-            }
-            run('git config user.name "gitnexus-release-bot[bot]"');
-            run('git config user.email "gitnexus-release-bot[bot]@users.noreply.github.com"');
-            run(`git checkout -b "${branch}"`);
-            run(`git commit -m "chore(vendor): rebuild native prebuilds (${grammars})\n\nBuilt by ${process.env.RUN_URL}"`);
-            const { owner, repo } = context.repo;
-            const remote = `https://x-access-token:${process.env.GH_TOKEN}@github.com/${owner}/${repo}.git`;
-            // Plain --force, not --force-with-lease: the branch is ephemeral and
-            // unique per run (keyed by context.runId), written ONLY by this job, so
-            // there is no concurrent writer to protect against. --force-with-lease
-            // would compare against a remote-tracking ref this fresh checkout never
-            // fetched, so re-running the SAME run (branch already pushed by attempt
-            // 1) fails with "stale info" instead of overwriting.
-            run(`git push --force "${remote}" "HEAD:${branch}"`);
-            const body = [
-              `Rebuilt the vendored native prebuilds for: **${grammars}**.`,
-              '',
-              `Builder run: ${process.env.RUN_URL}`,
-              'Each `.node` was `require()`-loaded + parsed a real snippet on its target',
-              'platform-arch before upload. SLSA build-provenance attested; `SHA256SUMS`',
-              'committed alongside each grammar.',
-            ].join('\n');
-            const { data: pr } = await github.rest.pulls.create({
-              owner, repo, head: branch, base: 'main',
-              title: `chore(vendor): tree-sitter prebuilds (${grammars})`, body,
-            });
-            core.info(`Opened PR #${pr.number}`);
@@ -1,127 +0,0 @@
-name: Devcontainer Smoke
-
-# Smoke-tests .devcontainer/ whenever it changes. Two things happen here.
-# First, unit tests run on the pure host->container config transforms: the
-# plugin-registry path translation, and the strip of the machine field from
-# $HOME/.claude.json. Second, the devcontainer image is built through the
-# standard @devcontainers/cli path. That CLI reads build.args from
-# devcontainer.json, so the version pin there stays the single source of truth.
-on:
-  push:
-    branches: [main]
-    paths:
-      - '.devcontainer/**'
-      - '.github/workflows/ci-devcontainer.yml'
-  pull_request:
-    paths:
-      - '.devcontainer/**'
-      - '.github/workflows/ci-devcontainer.yml'
-
-permissions:
-  contents: read
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Grouped per branch or tag. Cancel a PR run when a newer one replaces it.
-# Never cancel a push-to-main run.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  config-transforms:
-    name: Config-transform unit tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      # persist-credentials: false — this job only reads (tests and syntax
-      # checks) and never pushes. The setting keeps GITHUB_TOKEN out of
-      # .git/config, which zizmor flags as the "artipacked" issue.
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-      - name: Unit-test the host->container config transforms
-        run: node --test .devcontainer/translate-plugin-registries.test.cjs
-      - name: Syntax-check the lifecycle shell scripts
-        run: |
-          bash -n .devcontainer/install-deps.sh
-          bash -n .devcontainer/post-create.sh
-
-  build:
-    name: Build devcontainer image
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      # persist-credentials: false — this is a read-only build smoke that
-      # never pushes. The setting keeps GITHUB_TOKEN out of .git/config,
-      # which zizmor flags as the "artipacked" issue.
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-      # Builds the image the same way a developer's "Reopen in Container" does.
-      # @devcontainers/cli reads devcontainer.json (jsonc format), resolves
-      # build.args (the CLAUDE_CODE_VERSION / CODEX_VERSION pins), and runs the
-      # Dockerfile. This smoke catches Dockerfile regressions and any drift from
-      # the canonical version pins. The lifecycle hooks (post-create.sh) do not
-      # run here. They need the host config mounts, and CI has none.
-      #
-      # ARCH COVERAGE: this runs on an x64 runner with no --platform or QEMU, so
-      # it builds only the amd64 Cursor branch (CURSOR_SHA256_X64). The arm64
-      # branch (CURSOR_SHA256_ARM64 plus the arm64 tarball URL) is pinned by a
-      # sha256 checked against the published artifact, but it is not BUILT here.
-      # Cursor's extract-and-symlink step does not depend on the architecture, so
-      # the only remaining gap is a stale arm64 URL or hash. If that becomes a
-      # concern, add a linux/arm64 matrix leg (docker/setup-qemu-action plus
-      # `--platform`).
-      #
-      # The @devcontainers/cli version is pinned on purpose. A bare
-      # `npx --yes @devcontainers/cli` would resolve @latest at run time. A
-      # breaking or malicious publish could then change CI behavior, or change
-      # how devcontainer.json is read, with no diff to show for it. Bump this pin
-      # deliberately, alongside the Dockerfile and devcontainer.json pins.
-      #
-      # @devcontainers/cli wraps the Dockerfile with `# syntax=docker/dockerfile:1`,
-      # which BuildKit resolves from Docker Hub. Hub blips surface as
-      # `DeadlineExceeded` / `i/o timeout` on the syntax frontend (see run
-      # 26797815133). Build retry (2 attempts, 45s backoff) matches
-      # `.github/actions/docker-build-push-retry` (docker/build-push-action#1422).
-      # Pre-pull of docker/dockerfile:1 is extra hardening; best-effort so the
-      # build retry still runs if Hub is flaky only during pull.
-      - name: Pre-pull BuildKit Dockerfile frontend (retry)
-        continue-on-error: true
-        run: |
-          set -euo pipefail
-          img="docker/dockerfile:1"
-          for attempt in 1 2 3; do
-            if docker pull "$img"; then
-              exit 0
-            fi
-            echo "::warning::docker pull ${img} attempt ${attempt} failed"
-            if [ "$attempt" -lt 3 ]; then
-              sleep $((attempt * 15))
-            fi
-          done
-          echo "::warning::failed to pre-pull ${img} after 3 attempts; continuing — build step may still succeed"
-          exit 1
-      - name: Build devcontainer via @devcontainers/cli
-        run: |
-          set -euo pipefail
-          for attempt in 1 2; do
-            if npx --yes @devcontainers/cli@0.87.0 build --workspace-folder .; then
-              if [ "$attempt" -eq 2 ]; then
-                echo "::notice::devcontainer build retry succeeded (attempt 2); investigate if this recurs across runs."
-              fi
-              exit 0
-            fi
-            if [ "$attempt" -eq 2 ]; then
-              echo "::error::devcontainer build failed after 2 attempts"
-              exit 1
-            fi
-            echo "::warning::devcontainer build attempt ${attempt} failed; retrying in 45s…"
-            sleep 45
-          done
@@ -3,9 +3,6 @@ name: E2E Tests
 on:
  workflow_call:

-permissions:
-  contents: read
-
 jobs:
  check-changes:
    name: Check web module changes
@@ -14,7 +11,7 @@ jobs:
    outputs:
      web_changed: ${{ steps.filter.outputs.web }}
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v3
        id: filter
        with:
@@ -29,7 +26,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Configure e2e GitNexus home
        run: echo "GITNEXUS_HOME=${RUNNER_TEMP}/gitnexus-home" >> "$GITHUB_ENV"
@@ -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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: ./.github/actions/setup-gitnexus
      - run: npx tsc --noEmit
        working-directory: gitnexus
@@ -46,7 +43,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: ./.github/actions/setup-gitnexus-web
      - run: npx tsc -b --noEmit
        working-directory: gitnexus-web
@@ -67,7 +64,7 @@ jobs:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - name: Validate workflow concurrency convention
        shell: bash
        run: |
@@ -95,37 +95,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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          sparse-checkout: gitnexus/vitest.config.ts
          sparse-checkout-cone-mode: false
@@ -281,17 +279,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 ──
@@ -0,0 +1,110 @@
+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:
+
+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"
@@ -3,22 +3,13 @@ name: Tests
 on:
  workflow_call:

-permissions:
-  contents: read
-
 jobs:
  tests:
    name: ubuntu / coverage
    runs-on: ubuntu-latest
    timeout-minutes: 25
    steps:
-      # persist-credentials: false — this job runs tests and uploads a
-      # test-reports artifact (if: always()). The default-persisted token in
-      # .git/config must not be capturable through that upload (zizmor
-      # credential-persistence / artipacked audit). The job never pushes.
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: ./.github/actions/setup-gitnexus
        with:
          build: 'true'
@@ -65,243 +56,19 @@ jobs:
            gitnexus-web/web-test-results.json
          retention-days: 5

-  # Platform-sensitive subset only — the full suite runs on Ubuntu above.
-  # See gitnexus/scripts/cross-platform-tests.ts for the file list and
-  # rationale for each included test.
  cross-platform:
-    name: ${{ matrix.os }} (platform-sensitive)
+    name: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        # Ubuntu already covered by the coverage job above
        os: [windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
-    timeout-minutes: 20
-    steps:
-      # persist-credentials: false — runs tests only, never pushes (zizmor
-      # credential-persistence / artipacked audit).
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'true'
-      - name: Run platform-sensitive tests
-        run: npx tsx scripts/run-cross-platform.ts
-        working-directory: gitnexus
-
-  # Tree-sitter ABI gate (#1922). Two halves, both blocking:
-  #   1. Static, offline: assert every grammar's compiled ABI loads on the
-  #      pinned runtime (check-tree-sitter-upgrade-readiness.py --assert-current).
-  #   2. Dynamic: run the parser-loader ABI load-smoke on the OS matrix so an
-  #      ABI-incompatible committed vendor prebuilt (e.g. Swift's — the static
-  #      check introspects source, not the shipped .node) fails on the platform
-  #      it ships to.
-  abi-assert:
-    name: tree-sitter ABI (${{ matrix.os }})
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 20
-    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'true'
-
-      - name: Assert installed + vendored grammar ABIs (static)
-        shell: bash
-        run: python3 .github/scripts/check-tree-sitter-upgrade-readiness.py --assert-current
-
-      - name: Run parser-loader ABI load-smoke (dynamic)
-        run: npx vitest run test/unit/parser-loader-abi.test.ts
-        working-directory: gitnexus
-
-  # End-to-end smoke test for the #1728 packaging fix: pack the published
-  # tarball, install it globally into a temp prefix, and assert no junction
-  # creation (the EPERM root cause) plus working CLI plus vendor cleanliness
-  # (#836). Runs on windows-latest because that is the platform the fix
-  # targets; the in-repo `npm ci` job above only exercises the dev-tree path
-  # and skips the tarball reify step where the historical EPERM occurred.
-  packaged-install-smoke:
-    name: packaged install smoke (${{ matrix.os }})
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [windows-latest, ubuntu-latest]
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 15
-    steps:
-      # persist-credentials: false — this job runs npm pack + npm install -g
-      # from a tarball and never pushes back; the token in .git/config would
-      # be at risk of leaking through any future artifact-upload step
-      # (zizmor artipacked audit). Disable upfront.
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'true'
-
-      - name: Pack gitnexus tarball
-        shell: bash
-        run: npm pack
-        working-directory: gitnexus
-
-      - name: Install gitnexus tarball into isolated prefix
-        shell: bash
-        run: |
-          set -euo pipefail
-          PREFIX="$RUNNER_TEMP/gitnexus-smoke"
-          mkdir -p "$PREFIX"
-          TARBALL=$(find . -maxdepth 1 -name 'gitnexus-*.tgz' -print -quit)
-          if [ -z "$TARBALL" ]; then
-            echo "ERROR: no gitnexus-*.tgz tarball found in $(pwd)" >&2
-            exit 1
-          fi
-          echo "Installing $TARBALL into $PREFIX"
-          npm install -g --prefix "$PREFIX" "./$TARBALL" --no-audit --no-fund
-          echo "PREFIX=$PREFIX" >> "$GITHUB_ENV"
-        working-directory: gitnexus
-
-      - name: Assert no junctions or vendor build artifacts
-        shell: bash
-        run: |
-          set -euo pipefail
-          # Locate the installed gitnexus package across npm prefix layouts
-          # (lib/node_modules on POSIX, node_modules on Windows).
-          for candidate in "$PREFIX/lib/node_modules/gitnexus" "$PREFIX/node_modules/gitnexus"; do
-            if [ -d "$candidate" ]; then
-              INSTALLED="$candidate"
-              break
-            fi
-          done
-          if [ -z "${INSTALLED:-}" ]; then
-            echo "ERROR: installed gitnexus package not found under $PREFIX" >&2
-            ls -la "$PREFIX" || true
-            exit 1
-          fi
-          echo "Installed package at: $INSTALLED"
-
-          # #836 invariant: no node_modules/ or build/ under any vendor/*.
-          BAD=$(find "$INSTALLED/vendor" \( -name node_modules -o -name build \) -print 2>/dev/null || true)
-          if [ -n "$BAD" ]; then
-            echo "ERROR: vendor tree contains forbidden build artifacts (#836):" >&2
-            echo "$BAD" >&2
-            exit 1
-          fi
-
-          # #1728 invariant: materialized grammar dirs are real directories,
-          # not junctions/symlinks (which is what the EPERM regression created).
-          for name in tree-sitter-dart tree-sitter-proto tree-sitter-swift; do
-            entry="$INSTALLED/node_modules/$name"
-            if [ ! -e "$entry" ]; then
-              echo "WARN: $name not materialized (toolchain/prebuild may be unavailable on $RUNNER_OS)"
-              continue
-            fi
-            if [ -L "$entry" ]; then
-              echo "ERROR: $entry is a symlink/junction — #1728 regression" >&2
-              exit 1
-            fi
-            if [ ! -d "$entry" ]; then
-              echo "ERROR: $entry is not a directory" >&2
-              exit 1
-            fi
-          done
-
-      - name: Assert gitnexus --version works
-        shell: bash
-        run: |
-          set -euo pipefail
-          if [ "$RUNNER_OS" = "Windows" ]; then
-            "$PREFIX/gitnexus.cmd" --version
-          else
-            "$PREFIX/bin/gitnexus" --version
-          fi
-
-  # ── Dedicated benchmark gate ─────────────────────────────────────
-  # The cross-language `*-pipeline-benchmark.test.ts` suites are gated behind
-  # GITNEXUS_BENCH (they generate synthetic codebases at scale), so the main
-  # coverage job above SKIPS them — their O(n^2) scaling guards never ran in CI.
-  # Run them here with GITNEXUS_BENCH=1, alongside the Python scope-capture and
-  # import-resolution fingerprint + scaling guards (PR #1918 P2a).
-  #
-  # `--no-file-parallelism` is REQUIRED: these suites measure wall-clock and peak
-  # heap, so parallel forks both skew the timings and OOM the worker pool — they
-  # must run one file at a time.
-  #
-  # go-pipeline-benchmark.test.ts is deliberately NOT included: its
-  # worker-pool (#1848) suite spins a real worker pool that exits unexpectedly
-  # under vitest's fork pool (reproduced in validation), which would make this
-  # gate flaky. Go is already guarded by its non-gated O(n^2) tripwire (runs in
-  # the main coverage job) plus its golden capture-parity test.
-  benchmarks:
-    name: benchmarks (GITNEXUS_BENCH)
-    runs-on: ubuntu-latest
    timeout-minutes: 25
    steps:
-      # persist-credentials: false — this job only runs npm + vitest benchmarks
-      # and never pushes; the default-persisted token in .git/config would be at
-      # risk of leaking through an artifact upload (zizmor credential-persistence
-      # / artipacked audit). Mirrors the packaged-install-smoke job below.
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: ./.github/actions/setup-gitnexus
        with:
          build: 'true'
-
-      - name: Python scope-capture + import-resolution fingerprint / scaling guards
-        run: |
-          node --import tsx bench/python-scope/measure.mjs --check
-          node --import tsx bench/python-scope/import-target-fingerprint.mjs --check
-        working-directory: gitnexus
-
-      - name: Cross-language scope-capture fingerprint + scaling guards
-        # Build-free: asserts emit<Lang>ScopeCaptures output is unchanged
-        # (fingerprint) and stays linear (scaling < 1.5) for go/csharp/rust/php/
-        # ruby/cobol. Catches an O(n^2) re-regression without the worker pool.
-        run: node --import tsx bench/scope-capture/measure.mjs --check
-        working-directory: gitnexus
-
-      - name: CFG construction time / disk / memory guards (#2081 M1)
-        # Build-free: asserts collectFunctionCfgs output is unchanged
-        # (fingerprint) and that wall-time, cfgSideChannel disk bytes, AND
-        # retained heap all stay sub-quadratic for the straight-line /
-        # many-functions / branchy scenarios. Catches an O(n^2) re-regression in
-        # the per-function CFG builder (e.g. an extendBlock concat chain) and a
-        # memory/disk blow-up. --expose-gc enables the retained-heap measurement.
-        run: node --expose-gc --import tsx bench/cfg/measure.mjs --check
-        working-directory: gitnexus
-
-      - name: Emit-persistence throughput / byte-identity guards (#2203)
-        # Build-free: asserts streamAllCSVsToDisk output is byte-identical
-        # (order-independent CSV-line fingerprint — the #2203 U2/U3 emit
-        # optimisations must not change graph content) and that emit wall-time
-        # stays linear in node+edge count. The LadybugDB COPY half needs a real
-        # DB, so its timing lives in the runtime PROF_LBUG_LOAD breakdown.
-        run: node --import tsx bench/emit-persistence/measure.mjs --check
-        working-directory: gitnexus
-
-      - name: Streaming PDG-emit byte-identity / bounded-RSS guards (#2202)
-        # Build-free: asserts the streaming PdgEmitSink emits a CSV row SET
-        # byte-identical to the whole-graph streamAllCSVsToDisk emit, AND that
-        # the in-memory graph retains zero BasicBlock nodes (the O(chunk) peak-RSS
-        # bound that unblocks full-kernel-scale repos). Fails on fingerprint drift
-        # or any resident BasicBlock.
-        run: node --import tsx bench/emit-persistence/measure-streaming.mjs --check
-        working-directory: gitnexus
-
-      - name: Cross-language pipeline benchmarks (GITNEXUS_BENCH, serial)
-        env:
-          GITNEXUS_BENCH: '1'
-        run: >-
-          npx vitest run --no-file-parallelism
-          test/integration/cobol-pipeline-benchmark.test.ts
-          test/integration/csharp-pipeline-benchmark.test.ts
-          test/integration/rust-pipeline-benchmark.test.ts
-          test/integration/php-pipeline-benchmark.test.ts
-          test/integration/ruby-pipeline-benchmark.test.ts
+      - run: npx vitest run
        working-directory: gitnexus
@@ -6,19 +6,16 @@ on:
    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. 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 publish.yml (RC mode), which calls this workflow once
-# before publishing.
+# 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' }}
@@ -27,8 +24,9 @@ concurrency:
 # 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
-#                          (includes the scope-resolution resolver tests)
 #   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.

@@ -48,6 +46,11 @@ 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
@@ -56,7 +59,7 @@ jobs:
  save-pr-meta:
    name: Save PR Metadata
    if: always() && github.event_name == 'pull_request'
-    needs: [quality, tests, e2e]
+    needs: [quality, tests, e2e, scope-parity]
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
@@ -67,12 +70,14 @@ 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
          # 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
@@ -95,7 +100,7 @@ jobs:
  # Single required check for branch protection.
  ci-status:
    name: CI Gate
-    needs: [quality, tests, e2e]
+    needs: [quality, tests, e2e, scope-parity]
    if: always()
    runs-on: ubuntu-latest
    timeout-minutes: 5
@@ -104,29 +109,31 @@ jobs:
        shell: bash
        env:
          QUALITY: ${{ needs.quality.result }}
-          # The tree-sitter ABI gate (#1922) runs as the `abi-assert` job
-          # inside the `tests` reusable workflow. A failed job fails the
-          # reusable workflow, so `needs.tests.result` below blocks the merge
-          # on an ABI mismatch. (`jobs.<id>.result` cannot be exposed as a
-          # workflow_call output, so the gate is enforced transitively here.)
-          # The scope-resolution resolver tests also run inside the `tests`
-          # workflow (RING4-1 #942 removed the separate scope-parity gate),
-          # so a resolver regression makes TESTS != success and blocks here.
          TESTS: ${{ needs.tests.result }}
          E2E: ${{ needs.e2e.result }}
+          SCOPE_PARITY: ${{ needs.scope-parity.result }}
        run: |
          echo "Quality:        $QUALITY"
          echo "Tests:          $TESTS"
          echo "E2E:            $E2E"
-          # A failed `abi-assert` job (#1922) inside the tests reusable
-          # workflow makes TESTS != success, so this clause also blocks the
-          # merge on a tree-sitter ABI mismatch.
+          echo "Scope parity:   $SCOPE_PARITY"
          if [[ "$QUALITY" != "success" ]] ||
             [[ "$TESTS" != "success" ]]; then
-            echo "::error::Quality or test jobs failed (includes the tree-sitter ABI gate, #1922)"
+            echo "::error::Quality or test jobs failed"
            exit 1
          fi
          if [[ "$E2E" != "success" && "$E2E" != "skipped" ]]; then
            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
@@ -19,9 +19,6 @@ 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:
@@ -129,7 +126,7 @@ jobs:
            core.setOutput('code_review', isCodeReview ? 'true' : 'false');

      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        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 || '' }}
@@ -158,8 +155,6 @@ jobs:
          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'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'
@@ -17,9 +17,6 @@ on:
    # 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' }}
@@ -42,13 +39,13 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        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@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/init@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
        with:
          languages: ${{ matrix.language }}
          queries: security-and-quality
@@ -65,14 +62,10 @@ jobs:
              - '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. The second glob also
-              # covers fixtures nested deeper in the test tree, e.g.
-              # test/integration/cfg/fixtures/ (the CFG/PDG hazard inputs that
-              # deliberately contain use-before-init / unused-variable shapes).
+              # findings here are noise, not real bugs.
              - '**/test/fixtures/**'
-              - '**/test/**/fixtures/**'

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/analyze@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
        with:
          category: '/language:${{ matrix.language }}'
@@ -10,9 +10,6 @@ on:
  pull_request:
    branches: [main]

-permissions:
-  contents: read
-
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
@@ -28,12 +25,12 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Dependency Review
-        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
        with:
          fail-on-severity: high
          comment-summary-in-pr: on-failure
@@ -25,18 +25,6 @@ on:
          a gitnexus/package.json whose version matches the tag.
        required: true
        type: string
-    # Explicit secret contract — callers pass these by name. Replaces the
-    # blanket `secrets: inherit` pattern (zizmor `secrets-inherit` audit).
-    # GHCR auth uses the implicit GITHUB_TOKEN; only Docker Hub credentials
-    # need to be passed through.
-    secrets:
-      DOCKERHUB_USERNAME:
-        required: true
-      DOCKERHUB_TOKEN:
-        required: true
-
-permissions:
-  contents: read

 # Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
 # Tag refs are unique per release, so distinct tags run in parallel.
@@ -82,7 +70,7 @@ jobs:

    steps:
      # Only the workflow_call path requires a non-empty `inputs.tag` — callers
-      # (publish.yml in RC mode) must pass the RC tag explicitly. On direct
+      # (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
@@ -101,7 +89,7 @@ jobs:
      # 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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          ref: ${{ inputs.tag || github.ref }}

@@ -138,17 +126,17 @@ jobs:

      # Required for multi-platform (linux/arm64) emulation.
      - name: Set up QEMU
-        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

      - name: Install Cosign
-        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+        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@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
@@ -163,7 +151,7 @@ jobs:
      # `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@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
@@ -183,7 +171,7 @@ jobs:
      # `github.event_name` would still be "push", not "workflow_call".
      - name: Extract Docker metadata
        id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
+        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
@@ -12,9 +12,6 @@ on:
  push:
    branches: [main]

-permissions:
-  contents: read
-
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
@@ -29,7 +26,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        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.
@@ -38,22 +35,10 @@ jobs:
          # steps (and Gitleaks itself) don't need it for repo operations.
          persist-credentials: false

-      # gitleaks-action builds `base^..head` for pull_request events; both SHAs
-      # must exist locally (fork PRs and shallow checkouts otherwise fail with
-      # "unknown revision" — see gitleaks/gitleaks-action#199).
-      - name: Fetch PR refs for gitleaks range
-        if: github.event_name == 'pull_request'
-        env:
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          git fetch --no-tags origin "$BASE_SHA"
-          git fetch --no-tags origin "$HEAD_SHA"
-
      # 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@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: true
@@ -1,153 +0,0 @@
-name: Vendored grammar update monitor
-
-# Periodically checks each vendored tree-sitter grammar against its
-# source-of-origin and opens a PR re-vendoring any update that is ABI-COMPATIBLE
-# with the pinned tree-sitter@0.21.1 (LANGUAGE_VERSION 13–14, #1922). The version
-# bump then triggers build-tree-sitter-prebuilds.yml, which cross-builds + ABI-
-# validates the prebuilds — so a re-vendor that is subtly wrong can never silently
-# ship: its PR's CI goes red.
-#
-# ABI-INCOMPATIBLE updates (the common case — upstreams move to newer tree-sitter)
-# are reported as a notice + job summary, NOT applied, so the monitor never opens
-# doomed PRs. tree-sitter-c is MONITORED but report-only: it is ABI-pinned at
-# 0.21.4 (#1242/#858), so an available c update is surfaced (notice + summary) but
-# never auto-bumped — a maintainer re-vendors it deliberately after a runtime
-# upgrade.
-#
-# The vendored set + per-grammar upstream coords + the tree-sitter-c hold live in
-# .github/vendored-grammars.json — the SHARED source of truth this monitor and
-# tree-sitter-upgrade-readiness.yml both read, so the two workflows can never
-# disagree about which grammars are vendored (#858). This monitor additionally
-# resolves each grammar's upstream from it; the readiness report reads vendored
-# ABIs from gitnexus/vendor/ and keeps its own upstream-drift coords.
-#
-# Concurrency convention: see CONTRIBUTING.md -> "GitHub Actions — Concurrency Convention".
-
-on:
-  schedule:
-    - cron: '17 6 * * 1' # weekly, Monday 06:17 UTC
-  workflow_dispatch:
-
-# Least privilege; the actual writes use a short-lived App token minted below.
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}
-  cancel-in-progress: false
-
-jobs:
-  monitor:
-    name: Check upstreams + open update PRs
-    runs-on: ubuntu-24.04
-    timeout-minutes: 20
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-
-      # secrets aren't usable in a job/step `if:`, so compute presence here.
-      - name: Check release App secret
-        id: relapp
-        env:
-          HAS_APP: ${{ secrets.RELEASE_APP_ID != '' && secrets.RELEASE_APP_PRIVATE_KEY != '' }}
-        run: echo "configured=$HAS_APP" >> "$GITHUB_OUTPUT"
-
-      - name: Mint GitHub App token
-        id: app-token
-        if: steps.relapp.outputs.configured == 'true'
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          app-id: ${{ secrets.RELEASE_APP_ID }}
-          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
-
-      - name: Detect updates, re-vendor ABI-compatible ones, open PRs
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        env:
-          HAS_APP: ${{ steps.relapp.outputs.configured }}
-          # App token writes; falls back to the read-only job token (PRs then skip).
-          GH_TOKEN: ${{ steps.app-token.outputs.token || github.token }}
-        with:
-          github-token: ${{ steps.app-token.outputs.token || github.token }}
-          script: |
-            const { execFileSync } = require('node:child_process');
-            const SCRIPT = '.github/scripts/update-vendored-grammars.mjs';
-            const run = (cmd, args, opts = {}) =>
-              execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts });
-
-            const report = JSON.parse(run('node', [SCRIPT]));
-            const { owner, repo } = context.repo;
-            const hasApp = process.env.HAS_APP === 'true';
-            const applied = [], held = [], errors = [], skipped = [];
-
-            run('git', ['config', 'user.name', 'gitnexus-release-bot[bot]']);
-            run('git', ['config', 'user.email', 'gitnexus-release-bot[bot]@users.noreply.github.com']);
-            const baseSha = run('git', ['rev-parse', 'HEAD']).trim();
-
-            for (const r of report) {
-              if (r.error) { errors.push(r); continue; }
-              if (!r.update) continue;
-              if (!r.applicable) { held.push(r); continue; } // ABI-incompatible / unknown
-
-              const name = `tree-sitter-${r.grammar}`;
-              const branch = `chore/update-${name}-${r.upstream}`.replace(/[^a-z0-9._/-]+/gi, '-');
-
-              // Idempotency: don't reopen an existing PR for this exact version.
-              const existing = await github.rest.pulls.list({ owner, repo, head: `${owner}:${branch}`, state: 'all' });
-              if (existing.data.length > 0) { skipped.push({ ...r, reason: 'PR exists' }); continue; }
-
-              // Re-vendor in place (refuses + exits non-zero if ABI turns out wrong).
-              try {
-                run('node', [SCRIPT, '--apply', r.grammar]);
-              } catch (e) {
-                errors.push({ ...r, error: `apply failed: ${String(e.message || e).slice(0, 200)}` });
-                run('git', ['checkout', '--', 'gitnexus/vendor']);
-                continue;
-              }
-
-              if (!hasApp) {
-                skipped.push({ ...r, reason: 'no RELEASE_APP secret — PR not opened' });
-                run('git', ['checkout', '--', 'gitnexus/vendor']);
-                continue;
-              }
-
-              const remote = `https://x-access-token:${process.env.GH_TOKEN}@github.com/${owner}/${repo}.git`;
-              run('git', ['checkout', '-B', branch, baseSha]);
-              run('git', ['add', `gitnexus/vendor/${name}`]);
-              run('git', ['commit', '-m', `chore(vendor): update ${name} to ${r.upstream}`]);
-              run('git', ['push', '--force-with-lease', remote, `HEAD:${branch}`]);
-              const body = [
-                `Automated re-vendor of **${name}** to \`${r.upstream}\` (from ${r.kind === 'npm' ? `npm \`${name}\`` : `\`${r.ref}\``}).`,
-                '',
-                `Verified ABI **${r.abi}** — compatible with the pinned \`tree-sitter@0.21.1\` (13–14).`,
-                'Source-build inputs refreshed; the GitNexus binding.gyp / README / prebuilds are preserved.',
-                'The version bump triggers `build-tree-sitter-prebuilds.yml` to rebuild + ABI-validate the',
-                'prebuilds — review its result before merging.',
-              ].join('\n');
-              const pr = await github.rest.pulls.create({
-                owner, repo, head: branch, base: 'main',
-                title: `chore(vendor): update ${name} to ${r.upstream}`, body,
-              });
-              applied.push({ ...r, pr: pr.data.number });
-              run('git', ['checkout', '--force', baseSha]);
-            }
-
-            // Summary
-            const s = core.summary.addHeading('Vendored grammar update monitor');
-            if (applied.length) s.addRaw(`\n**Opened PRs:** ${applied.map((a) => `${a.grammar}→${a.upstream} (#${a.pr})`).join(', ')}\n`);
-            if (held.length) s.addRaw(`\n**Held (not auto-applied):** ${held.map((h) => `${h.grammar} ${h.upstream} (${h.hold ? 'report-only: ' + h.hold : 'ABI ' + (h.abi ?? '?') + ' — needs the tree-sitter runtime upgrade'})`).join(', ')}\n`);
-            if (skipped.length) s.addRaw(`\n**Skipped:** ${skipped.map((x) => `${x.grammar} (${x.reason})`).join(', ')}\n`);
-            if (errors.length) s.addRaw(`\n**Errors:** ${errors.map((e) => `${e.grammar}: ${e.error}`).join('; ')}\n`);
-            if (!applied.length && !held.length && !skipped.length && !errors.length) s.addRaw('\nAll vendored grammars are up to date. ✅\n');
-            await s.write();
-
-            for (const h of held) core.notice(`${h.grammar}: update to ${h.upstream} available — ${h.hold ? `report-only (${h.hold})` : `ABI ${h.abi ?? 'unknown'} (need 13/14), held until the tree-sitter runtime upgrade`}.`);
-            if (!hasApp && (applied.length || skipped.some((x) => /secret/.test(x.reason)))) {
-              core.notice('RELEASE_APP_ID / RELEASE_APP_PRIVATE_KEY not configured — update PRs were not opened. Provision the App to enable auto-PRs.');
-            }
@@ -1,71 +0,0 @@
-name: Impact PDG Mutation Report
-
-# Off-the-fast-path mutation oracle for the PDG-backed `impact` mode.
-#
-# The `--mutation` oracle (bench/impact-pdg/measure.mjs) is a ~280s dynamic
-# value-diff check: it mutates each fixture, re-analyzes with `--pdg`, and scores
-# the realized recall of the statement slice against the behavioral diff. It is
-# far too slow for the PR critical path, so it runs on a nightly schedule (and on
-# demand via workflow_dispatch) and uploads the JSON report as an artifact rather
-# than gating merges.
-#
-# The harness shells out to `gitnexus analyze --pdg`, which spawns workers from
-# dist/, so dist must be built first — setup-gitnexus with build: 'true' does
-# that (mirrors ci-tests.yml).
-
-on:
-  schedule:
-    - cron: '0 3 * * *'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  mutation-report:
-    name: impact-pdg mutation oracle
-    runs-on: ubuntu-latest
-    timeout-minutes: 25
-    permissions:
-      contents: read
-    steps:
-      # persist-credentials: false — this job runs the bench + uploads an
-      # artifact and never pushes; the default-persisted token in .git/config
-      # must not be capturable through that upload (zizmor credential-persistence
-      # / artipacked audit). Mirrors ci-tests.yml.
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          persist-credentials: false
-
-      # setup-gitnexus is the repo's composite install action (Node 22 + npm ci);
-      # build: 'true' runs `node scripts/build.js` so dist/ exists for the
-      # analyze workers the mutation harness spawns.
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'true'
-
-      - name: Run PDG impact mutation oracle (~280s)
-        run: node --import tsx bench/impact-pdg/measure.mjs --mutation --json > mutation-report.json
-        working-directory: gitnexus
-
-      # Regression gate: write a recall summary to the run AND fail if the
-      # minimum realized recall drops below the (tunable) floor, so a recall
-      # regression surfaces instead of sitting unread in the artifact. Runs
-      # before the (always) upload so the artifact is preserved even on a fail.
-      - name: Gate on mutation recall regression
-        run: node bench/impact-pdg/gate-mutation-recall.mjs mutation-report.json
-        working-directory: gitnexus
-        env:
-          MUTATION_RECALL_FLOOR: '0.5'
-
-      - name: Upload mutation report
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: impact-pdg-mutation-report
-          path: gitnexus/mutation-report.json
-          retention-days: 14
@@ -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@df4cb1c069e1874edd31b4311f1884172cec0e10 # 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
@@ -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})"
@@ -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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        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
@@ -35,9 +35,6 @@ on:
  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
@@ -108,7 +105,7 @@ jobs:
      # 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@693d20e7c1ce1a81d3a41962f85914253b518449 # v7.3.1
+      - uses: release-drafter/release-drafter@563bf132657a13ded0b01fcb723c5a58cdd824e2 # v7.2.1
        with:
          config-name: release-drafter.yml
          dry-run: true
@@ -1,421 +1,61 @@
-name: Publish
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Sole publisher for the `gitnexus` npm package, GitHub Releases, and Docker
-# images. Replaces the former two-workflow design — see issue #1609 for the
-# double-publish race this unification closes.
-#
-# Two release modes, both routed through this file:
-#   • Release candidate (rc)  — triggered by push to `main` or workflow_dispatch.
-#       The RC path computes the next rc version, applies it in-CI, pushes a
-#       detached release commit with v<X.Y.Z>-rc.<N> + rc/<SHA> marker
-#       atomically, then publishes to npm with --tag rc and creates a GitHub
-#       prerelease. RC-only docker.yml invocation follows.
-#   • Stable                  — triggered by push of a v<X.Y.Z> tag (no -rc.*
-#       suffix). Verifies package.json matches the tag, publishes to npm with
-#       --tag latest, creates a stable GitHub Release. No docker (RC-only).
-#
-# ⚠️  SELF-TRIGGER INVARIANT — DO NOT WEAKEN ⚠️
-# The `tags:` filter below uses a negative glob `'!v*-rc.*'` to prevent the
-# workflow from re-triggering itself when the RC path pushes its own v-tag.
-# Without this exclusion, every RC publish double-fires (the bug fixed by
-# #1609). If a NEW prerelease channel is introduced (e.g. `-beta.N`,
-# `-alpha.N`, `-next.N`), the negative-glob list MUST be extended in
-# lock-step or self-trigger returns. The same invariant applies to the
-# `Classify` step further below — its accepted-tag regex must align with
-# the trigger filter's exclusion list.
-# ─────────────────────────────────────────────────────────────────────────────
+name: Publish to npm

 on:
  push:
-    branches: [main]
-    paths-ignore:
-      - '**.md'
-      - 'docs/**'
-      - 'LICENSE'
    tags:
-      # Negative-globbed exclusion of RC tags this workflow itself produces
-      # (see the SELF-TRIGGER INVARIANT in the header comment).
      - 'v*'
-      - '!v*-rc.*'
-  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'
-# Workflow-level deny-all; each job declares the minimum it needs.
-permissions: {}

-# Distinct refs (refs/heads/main, refs/tags/v*) run in parallel. The
-# release-PR-skip in rc-guard is the load-bearing invariant that prevents
-# an RC main-push and a stable tag-push colliding on the same release commit.
+# No workflow-level permissions — scoped per job below.
+
+# 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:
-  # ── Phase 1: classify the triggering event into a release mode ─────────────
-  route:
-    name: Classify release event
-    runs-on: ubuntu-latest
-    timeout-minutes: 2
-    permissions:
-      contents: read
-    outputs:
-      mode: ${{ steps.classify.outputs.mode }}
-      head_sha: ${{ steps.classify.outputs.head_sha }}
-      bump_input: ${{ inputs.bump }}
-      force_input: ${{ inputs.force }}
-    steps:
-      - name: Classify
-        id: classify
-        shell: bash
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          GH_REF: ${{ github.ref }}
-          GH_REF_NAME: ${{ github.ref_name }}
-        run: |
-          set -euo pipefail
-
-          HEAD_SHA="${GITHUB_SHA}"
-          echo "head_sha=${HEAD_SHA}" >> "$GITHUB_OUTPUT"
-
-          # Sanitize before logging (annotation-injection defense in depth).
-          REF_SAFE="${GH_REF//::/__}"
-          REF_NAME_SAFE="${GH_REF_NAME//::/__}"
-          echo "event=${EVENT_NAME} ref=${REF_SAFE} ref_name=${REF_NAME_SAFE}"
-
-          MODE=""
-          case "${EVENT_NAME}" in
-            workflow_dispatch)
-              # Manual dispatch is only valid on main — that's the only ref
-              # where a real publish makes sense.
-              if [ "${GH_REF}" = "refs/heads/main" ]; then
-                MODE="rc"
-              else
-                echo "::error::workflow_dispatch is only permitted on refs/heads/main (got ${REF_SAFE})."
-                exit 1
-              fi
-              ;;
-            push)
-              case "${GH_REF}" in
-                refs/heads/main)
-                  MODE="rc"
-                  ;;
-                refs/tags/v*)
-                  # The trigger filter already excluded v*-rc.* tags. Anything
-                  # reaching here is either a stable semver or a malformed v*.
-                  TAG="${GH_REF#refs/tags/}"
-                  if [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-                    MODE="stable"
-                  else
-                    echo "::error::malformed v* tag rejected: ${REF_NAME_SAFE}"
-                    echo "::error::stable tags must match ^v[0-9]+\\.[0-9]+\\.[0-9]+\$"
-                    exit 1
-                  fi
-                  ;;
-                *)
-                  echo "::error::unexpected push ref ${REF_SAFE} reached publish workflow."
-                  exit 1
-                  ;;
-              esac
-              ;;
-            *)
-              echo "::error::unsupported event ${EVENT_NAME}."
-              exit 1
-              ;;
-          esac
-
-          echo "mode=${MODE}" >> "$GITHUB_OUTPUT"
-          echo "Classified as mode=${MODE}"
-
-  # ── Phase 2 (RC only): dedup marker + release-PR skip ──────────────────────
-  rc-guard:
-    name: RC guard (marker + release-PR skip)
-    needs: route
-    if: needs.route.outputs.mode == 'rc'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      contents: read
-      pull-requests: read
-    outputs:
-      should_run: ${{ steps.decide.outputs.should_run }}
-      head_sha: ${{ steps.decide.outputs.head_sha }}
-    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-          # rc-guard reads only — no git pushes from this job. Skip the
-          # default extraheader credential persistence (artipacked audit).
-          persist-credentials: false
-
-      - 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
-
-          # Explicit cycle reset on dispatch bypasses dedup.
-          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 ───────────
-          # This skip is load-bearing: it prevents an RC build firing on the
-          # release-PR commit from racing the imminent stable-tag push on the
-          # same SHA. Two complementary checks:
-          #   1. HEAD subject matches `chore: release vX.Y.Z` (the canonical
-          #      release-PR title). Anchored to require the bare title or the
-          #      squash-merge `(#NNNN)` suffix exactly. Case-insensitive so
-          #      `Chore: Release v1.2.3` (IDE auto-capitalization) still
-          #      matches — prior commit-author conventions left the door open.
-          #   2. Squash-merged PR carries the `release` label.
-          # Either match suppresses the rc build — stable releases publish on
-          # the v-tag instead.
-          HEAD_SUBJECT="$(git log -1 --pretty=%s HEAD)"
-          # Sanitize GitHub-Actions annotation prefixes before logging — even
-          # though %s strips newlines, a crafted subject containing `::error::`
-          # could forge log annotations.
-          HEAD_SUBJECT_SAFE="${HEAD_SUBJECT//::/__}"
-          RELEASE_SUBJECT_RE='^chore:[[:space:]]*release[[:space:]]+v[0-9]+\.[0-9]+\.[0-9]+([[:space:]]+\(#[0-9]+\))?$'
-          shopt -s nocasematch
-          if [[ "$HEAD_SUBJECT" =~ $RELEASE_SUBJECT_RE ]]; then
-            shopt -u nocasematch
-            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
-          shopt -u nocasematch
-
-          # 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 dedup check.
-              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
-
-  # ── Phase 3: reusable CI gate ──────────────────────────────────────────────
-  # Runs for both rc (when guard says go) and stable. No `secrets:` passed —
-  # ci.yml and its entire reusable-workflow chain (ci-quality, ci-tests,
-  # ci-e2e, ci-report) reference zero `secrets.*` values;
-  # passing any would be unused surface. GITHUB_TOKEN is implicit.
  ci:
-    needs: [route, rc-guard]
-    if: ${{ always() && (needs.route.outputs.mode == 'stable' || needs.rc-guard.outputs.should_run == 'true') }}
    uses: ./.github/workflows/ci.yml
    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.

-  # ── Phase 4: publish to npm + push refs (RC path) ──────────────────────────
-  # INVARIANT: `timeout-minutes` MUST stay below the App-token TTL (~60 min
-  # for actions/create-github-app-token installation tokens). The atomic
-  # tag-push step relies on the token minted at job start; if the job ever
-  # runs longer than the TTL, the push fails with an opaque 401. If you
-  # need to raise the timeout, re-mint the token immediately before the
-  # `Create and push rc tags` step instead.
  publish:
-    name: Publish to npm
-    needs: [route, rc-guard, ci]
-    if: ${{ always() && needs.ci.result == 'success' && (needs.route.outputs.mode == 'stable' || needs.rc-guard.outputs.should_run == 'true') }}
+    needs: ci
    runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 15
    permissions:
-      # contents: write — RC path needs it for `git push --atomic` (v-tag +
-      # marker). Stable path runs in the same job and inherits the grant; it
-      # never invokes `git push`, so the elevated scope is unused there.
-      # id-token: write — npm provenance attestation.
      contents: write
      id-token: write
-    outputs:
-      # Two distinct step IDs feed this output; exactly one fires per run.
-      vtag: ${{ steps.rc-tags.outputs.vtag || steps.stable-vtag.outputs.vtag }}
    steps:
-      # ── Mint short-lived GitHub App token (RC only) ──────────────────────
-      # Industry direction (2025-2026): GitHub Apps with
-      # `actions/create-github-app-token` over long-lived PATs for
-      # workflow-touching tag pushes. Same fine-grained permission surface,
-      # ~1h expiry, not tied to a user seat, organizationally auditable.
-      # Replaces a prior fine-grained PAT.
-      #
-      # Required secrets (set in repo Settings → Secrets and variables → Actions):
-      #   secrets.RELEASE_APP_ID         — the App's numeric ID
-      #   secrets.RELEASE_APP_PRIVATE_KEY — the App's PEM private key
-      # (The App ID is technically not sensitive — it's visible on the App's
-      # settings page — but storing it as a secret is harmless and avoids
-      # mixing storage classes for the same App.)
-      # The App must be installed on this repository with:
-      #   - Contents: write         (push the v-tag and rc marker)
-      #   - Workflows: write        (because the v-tag's tree may touch
-      #                              .github/workflows/**, which the default
-      #                              GITHUB_TOKEN cannot author)
-      #   - Metadata: read          (required for the `gh api /users/<slug>[bot]`
-      #                              bot-identity lookup in the tag-push step)
-      - name: Mint GitHub App token (RC)
-        if: needs.route.outputs.mode == 'rc'
-        id: app-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          # `client-id` is the renamed input that supersedes the deprecated
-          # `app-id` in v3.x. The action accepts the App's numeric ID or
-          # its Client ID under this name. We pass the numeric App ID,
-          # which the action resolves correctly.
-          client-id: ${{ secrets.RELEASE_APP_ID }}
-          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
-
-      # ── Separate checkout steps per mode ─────────────────────────────────
-      # Conditional `token:` expressions are footguns: empty string passed to
-      # actions/checkout fails opaquely, and `|| github.token` silently
-      # degrades a missing token to GITHUB_TOKEN, masking auth failures until
-      # the eventual `git push`. Two distinct steps make the auth contract
-      # explicit and fail loudly at checkout when the App token mint failed
-      # on the RC path.
-      - name: Checkout (RC)
-        if: needs.route.outputs.mode == 'rc'
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-          # Short-lived GitHub App installation token. Required because the
-          # v-tag push lands at a SHA whose tree may touch
-          # `.github/workflows/**`, which the default GITHUB_TOKEN cannot
-          # author.
-          token: ${{ steps.app-token.outputs.token }}
-          # Do not persist the token in .git/config (artipacked audit). The
-          # RC tag push uses an inline `http.extraheader` at push time only;
-          # the credential never lands on disk. See the
-          # `Create and push rc tags` step below.
-          persist-credentials: false
-
-      - name: Checkout (stable)
-        if: needs.route.outputs.mode == 'stable'
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        # No `token:` — actions/checkout uses GITHUB_TOKEN by default. Stable
-        # path performs no git pushes; the default scope is sufficient.
-        with:
-          # No git pushes from the stable path either. Skip credential
-          # persistence (artipacked audit).
-          persist-credentials: false
-
-      - name: Working-tree sanity
-        # Defense in depth (mirrors the vtag integrity gate, but on the input side):
-        # if a route-mode regression skipped both checkout `if:` gates, all
-        # downstream steps would run on a bare runner and produce confusing
-        # ENOENT errors. Fail loudly and early here instead.
-        shell: bash
-        run: |
-          if [ ! -f gitnexus/package.json ]; then
-            echo "::error::no working tree at gitnexus/package.json — route classification likely failed silently."
-            exit 1
-          fi
-
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
-          # Node 24 ships with npm >= 11.5.x, which is the minimum that
-          # supports npm Trusted Publishing OIDC. Node 22 ships with npm
-          # 10.9.x (no OIDC) and `npm install -g npm@latest` to self-upgrade
-          # is fragile — it can crash the in-flight reify with
-          # `MODULE_NOT_FOUND` on `promise-retry` etc. Bumping the Node
-          # version is the clean fix; the package's `engines` field is
-          # `>=22.0.0` so consumer-side compatibility is unaffected (this
-          # Node version is only used during publish, not by package users).
-          node-version: 24
-          # `registry-url:` is intentionally OMITTED. Under npm Trusted
-          # Publishing, OIDC only engages when no credential is configured.
-          # Setting `registry-url:` would make setup-node write
-          # `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}` into the
-          # runner's .npmrc AND export NODE_AUTH_TOKEN from its `token:`
-          # input (default github.token). `npm publish` would then attempt
-          # GITHUB_TOKEN as the npm token, get rejected with 404, and OIDC
-          # would never be tried. See actions/setup-node#1440 and the GitHub
-          # Community discussion #176761 for the upstream bug and consensus
-          # workaround.
-          #
-          # Hermetic install for published artifacts — opt out of the v5+
-          # default packageManager-based caching (clears the zizmor
-          # cache-poisoning audit). ~30s slower per release; runs rarely.
+          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
-
      - name: Build gitnexus-shared
        run: npm install && npm run build
        working-directory: gitnexus-shared

-      - name: Install gitnexus dependencies
-        run: npm ci
+      - run: npm ci
        working-directory: gitnexus

-      # ── Stable-only: verify the tag and package.json agree ───────────────
-      - name: Verify version consistency (stable)
-        if: needs.route.outputs.mode == 'stable'
+      - name: Verify version consistency
        shell: bash
-        working-directory: gitnexus
        run: |
-          set -euo pipefail
          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
-          # Stable mode REJECTS prerelease suffixes — those are filtered at
-          # trigger by the negative-glob filter, but defend at the bash layer too.
-          if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::error::Stable tag must be ^v[0-9]+.[0-9]+.[0-9]+$ — got v$TAG_VERSION"
+          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('./package.json').version")
@@ -424,376 +64,24 @@ jobs:
            exit 1
          fi
          echo "Version verified: $PKG_VERSION"
-
-      # ── RC-only: compute the next rc version against the live registry ──
-      - name: Resolve rc version (rc)
-        id: rc-version
-        if: needs.route.outputs.mode == 'rc'
-        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
-          #    (retry-loud policy: never silently substitute on transient errors).
-          NPM_STDERR_LATEST="$(mktemp)"
-          if CURRENT_LATEST="$(npm view "$PKG_NAME" version 2>"$NPM_STDERR_LATEST")"; then
-            :
-          else
-            if grep -qiE 'E404|not found' "$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 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 -qiE 'E404|not found' "$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 != auto → explicit cycle reset.
-          #    - Otherwise (push, or dispatch with bump=auto) → continue the
-          #      highest active rc base > latest if any; else patch from latest.
-          # Curated wrapper around `npx semver` — bare npx errors are noisy
-          # and don't distinguish registry-unreachable from invalid-bump-spec.
-          semver_bump() {
-            local kind="$1" current="$2" stderr_file out
-            stderr_file="$(mktemp)"
-            if out="$(npx --yes -p semver@7 semver -i "$kind" "$current" 2>"$stderr_file")"; then
-              rm -f "$stderr_file"
-              printf '%s' "$out"
-              return 0
-            fi
-            echo "::error::semver bump failed (kind=${kind}, current=${current}):" >&2
-            cat "$stderr_file" >&2
-            rm -f "$stderr_file"
-            return 1
-          }
-
-          if [ "$EVENT_NAME" = "workflow_dispatch" ] \
-             && [ -n "${BUMP_INPUT:-}" ] \
-             && [ "${BUMP_INPUT:-auto}" != "auto" ]; then
-            BASE="$(semver_bump "$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="$(semver_bump 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
-          #    (race with another run), abort before re-publishing.
-          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
-        if: needs.route.outputs.mode == 'rc'
-        shell: bash
-        working-directory: gitnexus
-        run: |
-          set -euo pipefail
-          npm version "${{ steps.rc-version.outputs.rc_version }}" \
-            --no-git-tag-version --allow-same-version
-
-      - name: Build gitnexus
+      - name: Build
        run: npm run build
        working-directory: gitnexus

      - name: Dry-run publish
-        # Cheap verification that the tarball assembles before the real publish.
-        shell: bash
+        run: npm publish --dry-run
        working-directory: gitnexus
-        env:
-          NPM_TAG: ${{ needs.route.outputs.mode == 'rc' && 'rc' || 'latest' }}
-        run: npm publish --dry-run --tag "$NPM_TAG"

-      # ── Acquire the "rc lock" BEFORE publishing (idempotency anchor) ─────
-      # We create two refs and push 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.
-      # Push fails → nothing published. Push succeeds, npm fails → marker
-      # blocks retries until manual cleanup (see Rollback Runbook in plan).
-      - name: Create and push rc tags
-        id: rc-tags
-        if: needs.route.outputs.mode == 'rc'
-        shell: bash
-        working-directory: gitnexus
-        env:
-          RC_VERSION: ${{ steps.rc-version.outputs.rc_version }}
-          HEAD_SHA: ${{ needs.rc-guard.outputs.head_sha }}
-          # Short-lived GitHub App token. Auth is supplied inline at push
-          # time via `http.extraheader` (per GitHub's documented
-          # x-access-token Basic pattern). It is NOT persisted in
-          # .git/config (artipacked audit) — checkout above ran with
-          # `persist-credentials: false`.
-          PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
-          # App's slug from create-github-app-token (e.g. `gitnexus-release-bot`).
-          # Used to attribute the release commit to the App identity rather
-          # than the generic github-actions[bot]. The bot's numeric user-id
-          # is resolved at runtime via the GitHub API (the action does not
-          # expose it directly as of v3.2.0).
-          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: |
-          set -euo pipefail
-          VTAG="v${RC_VERSION}"
-          MARKER="rc/${HEAD_SHA}"
-
-          # Resolve the App's bot user-id and construct the noreply email
-          # in the GitHub-canonical `<id>+<slug>[bot]@users.noreply.github.com`
-          # shape. `[bot]` is part of the actual login on GitHub.
-          #
-          # The lookup is wrapped in a bounded retry because the first RC
-          # after App installation may hit propagation delay (404), and
-          # transient api.github.com 5xx during heavy org activity is a real
-          # failure class. Without retry, every transient blip aborts the
-          # entire release after CI has already succeeded.
-          BOT_LOGIN="${APP_SLUG}[bot]"
-          BOT_USER_ID=""
-          api_stderr="$(mktemp)"
-          for attempt in 1 2 3; do
-            if BOT_USER_ID="$(gh api "/users/${BOT_LOGIN}" --jq .id 2>"$api_stderr")" \
-               && [[ "${BOT_USER_ID}" =~ ^[0-9]+$ ]]; then
-              break
-            fi
-            BOT_USER_ID=""
-            if [ "$attempt" -lt 3 ]; then
-              echo "::warning::bot user-id lookup attempt ${attempt} failed; retrying in $((attempt * 5))s"
-              sleep $((attempt * 5))
-            fi
-          done
-          if ! [[ "${BOT_USER_ID}" =~ ^[0-9]+$ ]]; then
-            echo "::error::Could not resolve bot user-id for ${BOT_LOGIN} after 3 attempts."
-            echo "::error::gh api stderr:"
-            cat "$api_stderr" >&2 || true
-            echo "::error::Common causes: (a) newly-installed App — user record still propagating to /users/ (wait ~5min, redispatch with force=true); (b) App lacks Metadata: read permission; (c) transient api.github.com 5xx (redispatch)."
-            rm -f "$api_stderr"
-            exit 1
-          fi
-          rm -f "$api_stderr"
-          git config user.name  "${BOT_LOGIN}"
-          git config user.email "${BOT_USER_ID}+${BOT_LOGIN}@users.noreply.github.com"
-
-          # Detached release commit with the version bump — main stays
-          # pristine, but the v-tag's tree matches the published package
-          # exactly (release-integrity).
-          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"
-
-          git tag -a "$VTAG" "$RELEASE_SHA" -m "$VTAG"
-          git tag "$MARKER" "$HEAD_SHA"
-
-          # Inline auth header. The base64-encoded form is masked as well
-          # as the raw token, because GitHub's secret-masker only masks the
-          # raw value — any subsequent `set -x` / GIT_TRACE line would
-          # otherwise expose the encoded credential.
-          #
-          # `set +x` wraps the compute+mask pair so that if an operator
-          # enables ACTIONS_STEP_DEBUG=true for triage (which turns on
-          # `set -x` globally), the assignment is NOT traced for the one
-          # line between compute and mask-registration. Without this wrap,
-          # debug mode would log `+ auth_header='Authorization: Basic <encoded>'`
-          # exposing a still-valid (~1h) App token.
-          { set +x; } 2>/dev/null
-          auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${PUSH_TOKEN}" | base64 -w0)"
-          echo "::add-mask::${auth_header}"
-          # Re-enable tracing only when explicitly requested via step-debug.
-          if [ "${ACTIONS_STEP_DEBUG:-false}" = "true" ]; then set -x; fi
-
-          # Atomic push of both refs. If either would clobber an existing
-          # remote ref, the push fails and we stop before npm publish.
-          git -c http.extraheader="${auth_header}" \
-              push --atomic origin "refs/tags/$VTAG" "refs/tags/$MARKER"
-
-          {
-            echo "vtag=$VTAG"
-            echo "marker=$MARKER"
-            echo "release_sha=$RELEASE_SHA"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Set vtag (stable)
-        id: stable-vtag
-        if: needs.route.outputs.mode == 'stable'
-        shell: bash
-        # github.ref_name flows in via env to avoid templating into the
-        # shell source (template-injection audit). Even though refs are
-        # constrained by git naming rules, the env-passthrough pattern
-        # makes injection structurally impossible.
-        env:
-          REF_NAME: ${{ github.ref_name }}
-        run: |
-          echo "vtag=${REF_NAME}" >> "$GITHUB_OUTPUT"
-
-      # ── vtag integrity gate ──────────────────────────────────────────────
-      # Fail closed before any artifact-producing step (npm publish, Release,
-      # Docker) runs against an empty or mode-mismatched vtag. Prevents the
-      # silent "Release named main" / "Docker tagged from ref fallback"
-      # failure modes that the previous draft was vulnerable to.
-      - name: vtag integrity gate
-        id: vtag-gate
-        shell: bash
-        env:
-          MODE: ${{ needs.route.outputs.mode }}
-          VTAG: ${{ steps.rc-tags.outputs.vtag || steps.stable-vtag.outputs.vtag }}
-        run: |
-          set -euo pipefail
-
-          if [ -z "$VTAG" ]; then
-            echo "::error::vtag is empty — refusing to create GitHub Release or trigger Docker."
-            exit 1
-          fi
-
-          case "$MODE" in
-            rc)
-              if ! [[ "$VTAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$ ]]; then
-                echo "::error::vtag '${VTAG}' does not match rc shape ^v[0-9]+.[0-9]+.[0-9]+-rc.[0-9]+$"
-                exit 1
-              fi
-              ;;
-            stable)
-              if ! [[ "$VTAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-                echo "::error::vtag '${VTAG}' does not match stable shape ^v[0-9]+.[0-9]+.[0-9]+$"
-                exit 1
-              fi
-              ;;
-            *)
-              echo "::error::unknown mode '${MODE}' at vtag integrity gate."
-              exit 1
-              ;;
-          esac
-
-          echo "vtag verified: ${VTAG} (mode=${MODE})"
-          echo "vtag=${VTAG}" >> "$GITHUB_OUTPUT"
-
-      # npm Trusted Publishing (GA'd 2025-07-31). OIDC authentication only
-      # engages when no npm credential is configured anywhere — the absence
-      # is the signal. Two upstream behaviors had to be neutralized for
-      # this to work:
-      #
-      #   1. setup-node's `registry-url:` is omitted (see the setup-node
-      #      step above). With it, setup-node writes
-      #      `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}` into
-      #      .npmrc and exports NODE_AUTH_TOKEN from `token:` (defaulting
-      #      to github.token). npm publish then sends GITHUB_TOKEN as the
-      #      bearer credential and the registry returns 404. OIDC is never
-      #      tried because npm thinks it already has a credential.
-      #   2. The runner's bundled npm (10.9.x on Node 22) has no OIDC
-      #      support; the upgrade step above pins it to >= 11.5.1.
-      #
-      # Provenance is auto-attached by the registry on trusted-publisher
-      # publishes — no --provenance flag needed.
-      #
-      # Prerequisite: register the package as a trusted publisher at
-      # https://www.npmjs.com/package/gitnexus/access (Publishing access →
-      # Trusted Publishers → GitHub Actions):
-      #   Owner:       abhigyanpatwari
-      #   Repository:  GitNexus
-      #   Workflow:    publish.yml
-      #   Environment: (none)
      - name: Publish to npm
-        shell: bash
+        run: npm publish --provenance --access public
        working-directory: gitnexus
        env:
-          NPM_TAG: ${{ needs.route.outputs.mode == 'rc' && 'rc' || 'latest' }}
-        run: npm publish --access public --tag "$NPM_TAG"
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

-      # ── Stable-only: pull CHANGELOG body if present ──────────────────────
-      - name: Extract release notes from CHANGELOG (stable)
+      - name: Extract release notes from CHANGELOG
        id: changelog
-        if: needs.route.outputs.mode == 'stable'
        shell: bash
        run: |
          VERSION="${GITHUB_REF#refs/tags/v}"
@@ -809,90 +97,5 @@ jobs:
      - name: Create GitHub Release
        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
        with:
-          tag_name: ${{ steps.vtag-gate.outputs.vtag }}
-          name: >-
-            ${{ needs.route.outputs.mode == 'rc'
-                && format('Release Candidate {0}', steps.vtag-gate.outputs.vtag)
-                || steps.vtag-gate.outputs.vtag }}
-          prerelease: ${{ needs.route.outputs.mode == 'rc' }}
-          make_latest: ${{ needs.route.outputs.mode == 'stable' && 'true' || 'false' }}
-          # Stable: prefer CHANGELOG body, fall back to auto-generated.
-          # RC: always auto-generated + the prerelease body block below.
-          body_path: >-
-            ${{ needs.route.outputs.mode == 'stable' && steps.changelog.outputs.fallback == 'false'
-                && '/tmp/release-notes.md' || '' }}
-          generate_release_notes: >-
-            ${{ needs.route.outputs.mode == 'rc'
-                || steps.changelog.outputs.fallback == 'true' }}
-          body: >-
-            ${{ needs.route.outputs.mode == 'rc' && format(
-              'Automated release candidate build from `main`.{0}{0}**npm:** `npm install gitnexus@rc`{0}**Version:** `{1}`{0}**Target base:** `{2}` (rc #{3}){0}**Source commit (main):** {4}{0}**Release commit (versioned tree):** {5}{0}{0}Release candidates are pre-stable builds intended for early testing. Stable releases remain on the `latest` dist-tag.',
-              '\n',
-              steps.rc-version.outputs.rc_version,
-              steps.rc-version.outputs.base,
-              steps.rc-version.outputs.rc_n,
-              needs.rc-guard.outputs.head_sha,
-              steps.rc-tags.outputs.release_sha
-            ) || '' }}
-
-      # ── RC partial-failure cleanup ───────────────────────────────────────
-      # If anything after the atomic tag-push step failed (npm publish
-      # blew up, GitHub Release call timed out, etc.), the v-tag and
-      # rc/<SHA> marker are already on origin. External consumers
-      # (Renovate, Dependabot, Releases RSS) can ingest a phantom tag for
-      # a version that was never published to npm. This step deletes them
-      # automatically so the operator's recovery is just "redispatch with
-      # force=true on the next commit", not a manual ref cleanup.
-      #
-      # Scoped strictly to RC + real (non-dry-run) + the rc-tags step
-      # actually produced a vtag (otherwise nothing to clean up). The
-      # App token is still valid (~1h TTL, job timeout 20min).
-      - name: Cleanup pushed tags on partial failure
-        if: ${{ failure() && needs.route.outputs.mode == 'rc' && steps.rc-tags.outputs.vtag != '' }}
-        shell: bash
-        working-directory: gitnexus
-        env:
-          VTAG: ${{ steps.rc-tags.outputs.vtag }}
-          MARKER: ${{ steps.rc-tags.outputs.marker }}
-          PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: |
-          set -uo pipefail
-          echo "::warning::Publish step failed after tag push. Cleaning up remote refs to prevent phantom-version ingestion by downstream consumers."
-
-          { set +x; } 2>/dev/null
-          auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${PUSH_TOKEN}" | base64 -w0)"
-          echo "::add-mask::${auth_header}"
-          if [ "${ACTIONS_STEP_DEBUG:-false}" = "true" ]; then set -x; fi
-
-          # Delete v-tag and marker. Each delete is best-effort — if one
-          # is already absent (atomic push partially rejected, or earlier
-          # cleanup ran), the other still gets attempted.
-          for ref in "refs/tags/${VTAG}" "refs/tags/${MARKER}"; do
-            if git -c http.extraheader="${auth_header}" push origin --delete "${ref}" 2>&1; then
-              echo "deleted origin ${ref}"
-            else
-              echo "::warning::could not delete origin ${ref} — may already be absent or protected. Manual cleanup may be required."
-            fi
-          done
-
-          echo "::notice::Cleanup complete. To retry the release, redispatch the workflow with force=true on the same SHA, or push a new commit to main."
-
-  # ── Phase 5 (RC only): Docker images ───────────────────────────────────────
-  # R6: Docker remains RC-only. Stable Docker builds are explicitly deferred.
-  # Secrets are passed explicitly (not via `secrets: inherit`) so the
-  # callee's secret surface is auditable from the caller's source.
-  docker:
-    name: Build & Push RC Docker images
-    needs: [route, publish]
-    if: ${{ needs.route.outputs.mode == 'rc' && needs.publish.outputs.vtag != '' }}
-    uses: ./.github/workflows/docker.yml
-    secrets:
-      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
-      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
-    permissions:
-      contents: read
-      packages: write
-      id-token: write
-      attestations: write
-    with:
-      tag: ${{ needs.publish.outputs.vtag }}
+          body_path: ${{ steps.changelog.outputs.fallback == 'false' && '/tmp/release-notes.md' || '' }}
+          generate_release_notes: ${{ steps.changelog.outputs.fallback == 'true' }}
@@ -0,0 +1,409 @@
+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
+    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 }}
+        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
+
+          # 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: 20
+          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"             >> "$GITHUB_OUTPUT"
+          echo "rc_n=$NEXT_N"           >> "$GITHUB_OUTPUT"
+          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"     >> "$GITHUB_OUTPUT"
+          echo "marker=$MARKER" >> "$GITHUB_OUTPUT"
+          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 }}
@@ -33,7 +33,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

@@ -53,6 +53,6 @@ jobs:
          retention-days: 5

      - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
        with:
          sarif_file: results.sarif
@@ -1,21 +1,12 @@
 name: Tree-sitter Upgrade Readiness

 # Monitors readiness for upgrading tree-sitter to 0.25.x. Tracks:
-#   1. Peer-dep compatibility — can each NPM-installed grammar install cleanly
-#      with tree-sitter@0.25.0 without --legacy-peer-deps?
-#   2. Vendored grammars — each grammar in .github/vendored-grammars.json
-#      (c/swift/kotlin/dart/proto) is classified by its vendored ABI, read
-#      straight from gitnexus/vendor/<name>/src/parser.c (NOT node_modules,
-#      which is never populated for vendored grammars — that mismatch is why
-#      the report used to render bare "?" placeholders, #858).
+#   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.
 #
-# .github/vendored-grammars.json is the SHARED source of truth for the vendored
-# SET + policy holds: this readiness report and grammar-update-monitor.yml both
-# read it, so the two workflows can never disagree about which grammars are
-# vendored. (The monitor also resolves upstreams from it; this report keeps its
-# own upstream-drift coords and reads vendored ABIs from gitnexus/vendor/.)
-#
 # Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".

 on:
@@ -27,8 +18,6 @@ on:
  pull_request:
    paths:
      - '.github/scripts/check-tree-sitter-upgrade-readiness.py'
-      - '.github/scripts/test_check_tree_sitter_upgrade_readiness.py'
-      - '.github/vendored-grammars.json'
      - '.github/workflows/tree-sitter-upgrade-readiness.yml'

 concurrency:
@@ -39,36 +28,21 @@ permissions:
  contents: read

 jobs:
-  report:
+  readiness:
    name: Check upgrade readiness
    runs-on: ubuntu-latest
    timeout-minutes: 10
-    # Least privilege: rendering the report needs no write. The issue mutation
-    # lives in the schedule-only `upsert-issue` job below, so PR runs (incl. forks)
-    # never receive `issues: write` (#2187 review).
    permissions:
      contents: read
-    outputs:
-      report: ${{ steps.readiness.outputs.report }}
-      exit_code: ${{ steps.readiness.outputs.exit_code }}
+      # Needed to open/update the tracking issue on scheduled runs.
+      issues: write
    steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - uses: ./.github/actions/setup-gitnexus
        with:
          build: 'false'

-      # Guard the readiness script's logic (vendored classification, no bare "?",
-      # the manifest⇄vendor-dir consistency guard). Stdlib-only, so no extra deps;
-      # node_modules is populated by setup-gitnexus above, which the npm-path ABI
-      # reads need. Runs only on validation events (PR / manual), not the daily
-      # scheduled report.
-      - name: Run readiness script unit tests
-        if: github.event_name != 'schedule'
-        shell: bash
-        working-directory: .github/scripts
-        run: python3 -m unittest test_check_tree_sitter_upgrade_readiness -v
-
      - name: Run upgrade readiness check
        id: readiness
        shell: bash
@@ -80,15 +54,10 @@ jobs:
          code=$?
          set -e
          echo "exit_code=$code" >> "$GITHUB_OUTPUT"
-          # Unguessable per-run heredoc delimiter: the report includes the manifest's
-          # `hold` field, which a fork PR can edit — a fixed delimiter (e.g. DRIFT_EOF)
-          # in a hold value could close the heredoc early and inject $GITHUB_OUTPUT keys.
-          # A random hex delimiter the report cannot contain neutralizes that.
-          DELIM="DRIFT_EOF_$(openssl rand -hex 16)"
          {
-            echo "report<<${DELIM}"
+            echo 'report<<DRIFT_EOF'
            cat drift-report.md
-            echo "${DELIM}"
+            echo 'DRIFT_EOF'
          } >> "$GITHUB_OUTPUT"
          echo "=== Report ==="
          cat drift-report.md
@@ -100,22 +69,13 @@ jobs:
        run: |
          echo "::warning::Tree-sitter 0.25 upgrade has blockers. See job output for the full readiness report."

-  # Issue mutation is isolated here so `issues: write` is only ever granted on the
-  # scheduled run (never on PRs). Consumes the report + exit_code via job outputs.
-  upsert-issue:
-    name: Upsert tracking issue
-    needs: report
-    if: github.event_name == 'schedule'
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      issues: write
-    steps:
-      - name: Upsert tracking issue on blockers
-        if: needs.report.outputs.exit_code != '0'
+      - 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: ${{ needs.report.outputs.report }}
+          REPORT: ${{ steps.readiness.outputs.report }}
        with:
          script: |
            const title = 'Tree-sitter 0.25 upgrade readiness';
@@ -133,32 +93,11 @@ jobs:
            const existing = open.find(i => i.title === title);
            if (existing) {
              // Extract ready/total count for the changelog comment.
-              // The two report.match() regexes below are mirrored as
-              // _ISSUE_READY_RE / _ISSUE_BLOCKER_RE in
-              // .github/scripts/test_check_tree_sitter_upgrade_readiness.py, which is
-              // the ONLY place the contract is asserted against the rendered report.
-              // Keep all three in sync: changing the report prose means updating both
-              // these literals AND the test mirror, or requireMatch throws on the next
-              // scheduled run (the silent "?" fallback that used to hide drift is gone).
-              const requireMatch = (name, match) => {
-                if (!match) {
-                  throw new Error(
-                    `Could not extract ${name} from tree-sitter readiness report`,
-                  );
-                }
-                return match;
-              };
-              const readyMatch = requireMatch(
-                'ready npm grammar count',
-                report.match(/- (\d+)\/(\d+) npm-installed grammars already accept tree-sitter@/),
-              );
-              const blockerMatch = requireMatch(
-                'blocker count',
-                report.match(/\*\*Blocked\*\* — (\d+) grammars? /),
-              );
-              const ready = readyMatch[1];
-              const total = readyMatch[2];
-              const blockers = blockerMatch[1];
+              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:
@@ -166,11 +105,7 @@ jobs:
              //   | `tree-sitter-foo` | ... | Blocking |
              const parseRows = (md) => {
                const map = {};
-                // Group 2 captures ONLY the Status cell ([^|]+? before the final
-                // `|$`), so change-detection fires on status transitions, not on
-                // unrelated cell drift (e.g. an upstream-ABI bump). Mirror this in
-                // _ROW_DIFF_RE in test_check_tree_sitter_upgrade_readiness.py.
-                for (const m of md.matchAll(/\| `(tree-sitter-[^`]+)` \|.*\| ([^|]+?) \|$/gm)) {
+                for (const m of md.matchAll(/\| `(tree-sitter-[^`]+)` \|.*?\| (\S+(?:\s\S+)*?) \|$/gm)) {
                  map[m[1]] = m[2].trim();
                }
                return map;
@@ -186,7 +121,7 @@ jobs:
              }

              const today = new Date().toISOString().slice(0, 10);
-              let comment = `**${today}:** ${ready}/${total} npm-installed ready. ${blockers} blocker(s) remaining.`;
+              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 {
@@ -217,8 +152,10 @@ jobs:
              core.info(`Opened issue #${created.number}`);
            }

-      - name: Close tracking issue on clean runs
-        if: needs.report.outputs.exit_code == '0'
+      - 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: |
@@ -59,7 +59,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Checkout repository
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          sparse-checkout: .github/scripts/triage
          sparse-checkout-cone-mode: false
@@ -1,28 +1,19 @@
 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.
+# for OS-package and language-package CVEs at HIGH/CRITICAL 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.
+# NOT triggered on PRs — image builds are slow and base-image CVE churn
+# shouldn't gate feature delivery.

 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
@@ -45,15 +36,15 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Setup Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0

      - name: Build image (load locally for scan)
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: .
          file: ${{ matrix.image.dockerfile }}
@@ -70,13 +61,13 @@ jobs:
          image-ref: scan-target:${{ matrix.image.name }}
          format: sarif
          output: trivy-${{ matrix.image.name }}.sarif
-          severity: MEDIUM,HIGH,CRITICAL
+          severity: 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@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
        with:
          sarif_file: trivy-${{ matrix.image.name }}.sarif
          category: trivy-${{ matrix.image.name }}
@@ -1,13 +1,10 @@
-name: Workflow Lint
+name: Workflow Lint (zizmor)

-# 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.
+# Lints .github/workflows/** for known GitHub Actions security misconfigurations:
+# unpinned Actions, dangerous ${{ ... }} interpolation in run: blocks,
+# missing per-job permissions:, etc.
 #
-# Scoped to PRs that touch .github/** only — keeps off the typical PR
-# critical path.
+# Scoped to PRs that touch .github/** only — keeps off the typical PR critical path.

 on:
  pull_request:
@@ -15,35 +12,11 @@ on:
    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@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-        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
@@ -53,7 +26,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

@@ -76,7 +49,7 @@ jobs:
        continue-on-error: true

      - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
        with:
          sarif_file: zizmor.sarif
          category: zizmor
@@ -14,15 +14,6 @@ rules:
      # 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,
@@ -37,8 +28,7 @@ rules:
      - pr-labeler.yml

  # Note: cache-poisoning is NOT exempted. The two prior findings in
-  # publish.yml and the former release-candidate.yml were fixed structurally
-  # by dropping `cache: npm` from those workflows (matches the pattern used
-  # by PyO3/maturin for the same audit). After the publish-workflow
-  # unification (issue #1609), only publish.yml remains; the same
-  # cache-poisoning hardening applies there.
+  # 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.
@@ -68,8 +68,8 @@ gitnexus-web/test-results/
 eval/.coverage
 eval/.hypothesis/

-# Local docs
-docs/
+# Design docs (local only)
+docs/plans/

 gitnexus/test/fixtures/mini-repo/*.md
 gitnexus/test/fixtures/mini-repo/.claude
@@ -91,13 +91,11 @@ gitnexus/vendor/**/node_modules/

 .claude-flow/

-.claude/agents/*
-!.claude/agents/gitnexus-*.md
+.claude/agents/
 .claude/commands/
 .claude/helpers
-.claude/skills/*
+.claude/skills/
 !.claude/skills/gitnexus/
-!.claude/skills/gitnexus-pr-swarm-review/

 .history/

@@ -1,19 +0,0 @@
-title = "GitNexus"
-
-[extend]
-useDefault = true
-
-# Fake credentials in unit tests — none are real secrets:
-#   - embedding API keys in the http-embedder tests (regexes below)
-#   - synthetic GitHub PAT fixtures in the git-clone PAT-injection tests
-#     (e.g. ghp_secret123, ghp_uniqueRawSecret_98765) — allowlisted by path
-#     so the exception is bounded to that one test file.
-[allowlist]
-description = "fake credentials in unit tests (no real secrets)"
-regexes = [
-  '''secret-key-12345''',
-  '''test-api-key-redaction-check''',
-]
-paths = [
-  '''gitnexus/test/unit/git-clone\.test\.ts''',
-]
@@ -39,27 +39,15 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.
 ## Reference docs

 - **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**
- **Call & inheritance resolution (RFC #909 Ring 3):** See ARCHITECTURE.md § Scope-Resolution Pipeline. All languages resolve calls and inheritance through the scope-resolution pipeline (`Registry.lookup`, `preEmitInheritanceEdges`, `emitHeritageEdges`, `buildMro` → `MethodDispatchIndex`). **Shared code in `gitnexus/src/core/ingestion/` must not name languages** — plug language behavior in via `LanguageProvider` / `ScopeResolver` hooks. A language plugs in by implementing `ScopeResolver` (`scope-resolution/contract/scope-resolver.ts`) and registering it in `SCOPE_RESOLVERS`. (The legacy call-resolution DAG + `@heritage` capture path were removed in RING4-1 #942.)
+- **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.

-## PR Swarm Review (cross-CLI)
-
-To run a production-readiness review of a GitNexus pull request from **any** AI CLI, follow
-the canonical, CLI-neutral spec **[`pr-swarm-review/orchestration.md`](pr-swarm-review/orchestration.md)**
-(seven read-only review personas under `pr-swarm-review/personas/`). It defines two
-execution modes with the same output contract: **Swarm mode** (parallel subagents, e.g.
-Claude Code) and **Solo mode** (one agent runs all lanes sequentially — Codex, Gemini,
-Cursor, Copilot, or any agent reading this file). Per-CLI entrypoints are thin wrappers
-listed in [`pr-swarm-review/README.md`](pr-swarm-review/README.md); edit review logic only
-in the canonical files, never in the wrappers. The review is read-only — it never edits,
-commits, or posts.
-
 ## Changelog

 | Date | Version | Change |
 |------|---------|--------|
-| 2026-05-22 | 1.8.0 | Kotlin added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). Closes #1756 (companion-vs-instance dispatch) and #1757 (lambda scopes); refs #1746. RFC §6.4 corpus criterion waived (corpus-mode wiring is #927-scope); fixture criterion met. |
 | 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. |
@@ -74,64 +62,112 @@ commits, or posts.
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence

-This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use MCP tools to understand code, assess impact, and navigate safely.

-> Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
+> If any tool warns the index is stale, run `npx gitnexus analyze` first.

 ## Always Do

- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
- **MUST run `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 `query({search_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 `context({name: "symbolName"})`.
+- **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"})`.
+
+## 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"})`
+
+## 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.

 ## Never Do

- NEVER edit a function, class, or method without first running `impact` on it.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.
- NEVER commit changes without running `detect_changes()` to check affected scope.
+- 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.
+
+## Tools Quick Reference
+
+| Tool | When to use | Example |
+|------|-------------|---------|
+| `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=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/context` | Codebase overview, 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 |

-## CLI
+## Self-Check Before Finishing

-| 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` |
-| Work in the Ingestion area (239 symbols) | `.claude/skills/generated/ingestion/SKILL.md` |
-| Work in the Extractors area (135 symbols) | `.claude/skills/generated/extractors/SKILL.md` |
-| Work in the Components area (112 symbols) | `.claude/skills/generated/components/SKILL.md` |
-| Work in the Lbug area (96 symbols) | `.claude/skills/generated/lbug/SKILL.md` |
-| Work in the Group area (94 symbols) | `.claude/skills/generated/group/SKILL.md` |
-| Work in the Cli area (92 symbols) | `.claude/skills/generated/cli/SKILL.md` |
-| Work in the Configs area (92 symbols) | `.claude/skills/generated/configs/SKILL.md` |
-| Work in the Type-extractors area (90 symbols) | `.claude/skills/generated/type-extractors/SKILL.md` |
-| Work in the Hooks area (88 symbols) | `.claude/skills/generated/hooks/SKILL.md` |
-| Work in the Unit area (80 symbols) | `.claude/skills/generated/unit/SKILL.md` |
-| Work in the Cpp area (73 symbols) | `.claude/skills/generated/cpp/SKILL.md` |
-| Work in the Scope-resolution area (72 symbols) | `.claude/skills/generated/scope-resolution/SKILL.md` |
-| Work in the Server area (66 symbols) | `.claude/skills/generated/server/SKILL.md` |
-| Work in the Local area (61 symbols) | `.claude/skills/generated/local/SKILL.md` |
-| Work in the Wiki area (60 symbols) | `.claude/skills/generated/wiki/SKILL.md` |
-| Work in the Workers area (57 symbols) | `.claude/skills/generated/workers/SKILL.md` |
-| Work in the Embeddings area (56 symbols) | `.claude/skills/generated/embeddings/SKILL.md` |
-| Work in the Typescript area (53 symbols) | `.claude/skills/generated/typescript/SKILL.md` |
-| Work in the Storage area (51 symbols) | `.claude/skills/generated/storage/SKILL.md` |
-| Work in the Php area (48 symbols) | `.claude/skills/generated/php/SKILL.md` |
+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
+
+## Keeping the Index Fresh
+
+```bash
+npx gitnexus analyze                 # basic refresh; preserves any existing embeddings
+npx gitnexus analyze --embeddings    # also generate embeddings for new/changed nodes
+npx gitnexus analyze --drop-embeddings  # explicit opt-in to wipe existing embeddings
+```
+
+Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe.
+
+> 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.
+
+## CLI Skills
+
+| 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` |

 <!-- gitnexus:end -->

@@ -173,6 +209,6 @@ npx gitnexus serve                         # HTTP API on port 4747 (from any ind

 ### Gotchas

- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (materializes the vendored grammars into `node_modules/`, then prefers a committed prebuild per platform-arch and only source-builds when none matches). A C/C++ toolchain (`python3`, `make`, `g++`) is needed only for that source-build fallback.
- The vendored grammars `tree-sitter-{c,dart,proto,swift,kotlin}` are handled uniformly: c is required; dart/proto/swift/kotlin are optional and skippable via `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1`. Install warnings appear only when no prebuild matches the platform-arch and no toolchain is present, and are non-fatal — only that language's parsing is unavailable.
+- `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`.
@@ -15,7 +15,7 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).

 ## End-to-end flow: index → graph → tools

-1. **Ingestion** — `analyze.ts` → `runFullAnalysis` (`run-analyze.ts`) → `runPipelineFromRepo` (`pipeline.ts`). DAG of 14 phases builds a `KnowledgeGraph` in memory, then loads into LadybugDB under `.gitnexus/`. Repo registered in `~/.gitnexus/registry.json` for MCP discovery.
+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.

 2. **Persistence** — `repo-manager.ts` (paths, registry, KuzuDB cleanup). `lbug-adapter.ts` (graph load, queries, embedding batches).

@@ -38,12 +38,9 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
 | `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 |
-| `trace` | Shortest directed path between two symbols (call + class-member edges) |
 | `route_map` | API route → handler → consumer mappings |
 | `tool_map` | MCP/RPC tool definitions and handlers |
 | `shape_check` | Response shape vs consumer property access mismatches |
-| `explain` | Persisted taint findings (source→sink data flows) — needs `analyze --pdg` |
-| `pdg_query` | Control/data dependence — CDG (`mode: controls`) / REACHING_DEF (`mode: flows`) — needs `analyze --pdg` |
 | `group_list` | List repo groups or details for one group |
 | `group_sync` | Rebuild group Contract Registry (`contracts.json`) and bridge graph |

@@ -68,7 +65,7 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
 | 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/inheritance/MRO | `src/core/ingestion/scope-resolution/` (pipeline, passes, graph-bridge) |
+| 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/` |
@@ -80,11 +77,11 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).

 ## Pipeline Phase DAG

-14 phases defined in `gitnexus/src/core/ingestion/pipeline-phases/`, each with explicit `deps` and typed output.
+12 phases defined in `gitnexus/src/core/ingestion/pipeline-phases/`, each with explicit `deps` and typed output.

 ```
 scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
-  → crossFile → scopeResolution → pruneLocalSymbols → mro → communities → processes
+  → crossFile → mro → communities → processes
 ```

 | Phase | File | Deps | Output |
@@ -98,13 +95,11 @@ scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
 | `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 |
-| `scopeResolution` | `scope-resolution/pipeline/phase.ts` | `parse`, `crossFile`, `structure` | Binding/reference + inheritance edges; disposes BindingAccumulator |
-| `pruneLocalSymbols` | `prune-local-symbols.ts` | `scopeResolution` | Drops inert block-local `Const`/`Variable`/`Static` nodes (only a `File→DEFINES` edge) post-resolution |
-| `mro` | `mro.ts` | `crossFile`, `scopeResolution`, `pruneLocalSymbols`, `structure` | METHOD_OVERRIDES + METHOD_IMPLEMENTS edges |
-| `communities` | `communities.ts` | `mro`, `pruneLocalSymbols`, `structure` | Community nodes + MEMBER_OF edges (Leiden algorithm) |
-| `processes` | `processes.ts` | `communities`, `routes`, `tools`, `pruneLocalSymbols`, `structure` | Process nodes + STEP_IN_PROCESS edges |
+| `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 |

-**Non-phase files in the same directory:** `parse-impl.ts`, `cross-file-impl.ts` (implementation), `wildcard-synthesis.ts` (whole-module import expansion), `types.ts`, `runner.ts`, `index.ts`.
+**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

@@ -124,8 +119,7 @@ scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
 - **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); `pruneLocalSymbols` still runs (it is graph cleanup, not analysis). `skipWorkers` is no longer a sequential escape hatch — it (like `--workers 0` / `GITNEXUS_WORKER_POOL_SIZE=0`) is rejected with an actionable error, since the worker pool is the sole parse path (§ Chunked parse-and-resolve).
- **Local-symbol pruning** — `pruneLocalSymbols` removes inert block-local value symbols after scope resolution has consumed them. Opt out per-call with `PipelineOptions.keepLocalValueSymbols` or globally with the `GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS` env var.
+- **Skippable phases** — `skipGraphPhases` omits MRO/communities/processes (faster tests). `skipWorkers` forces sequential parsing.

 ### How to add a new phase

@@ -153,18 +147,105 @@ export const myPhase: PipelinePhase<MyPhaseOutput> = {

 ---

-## Semantic model
+## Call-Resolution DAG

-`SemanticModel` (`gitnexus/src/core/ingestion/model/semantic-model.ts`) is the authoritative store for every symbol-indexed lookup (by `nodeId`, `simpleName`, `qualifiedName`, or `filePath`). The scope-resolution pipeline reads from here: `findOwnedMember`, `pickOverload`, and `findExportedDefByName` all consult `model.methods` / `model.fields` / `model.symbols`.
+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.

-`ParsedFile` (`gitnexus-shared/src/scope-resolution/parsed-file.ts`) is the single per-file artifact the scope-resolution pipeline consumes. 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.
+### 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: parse            ──► symbolTable.add fans into types/methods/fields
+ 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 ───────────────────────────
@@ -174,7 +255,7 @@ The scope-resolution pipeline additionally carries `WorkspaceResolutionIndex` fo

 `runScopeResolution` narrows `MutableSemanticModel` → `SemanticModel` at the phase boundary so downstream passes physically cannot mutate the model even accidentally.

-**Reconciliation pass.** `reconcileOwnership` (`scope-resolution/pipeline/reconcile-ownership.ts`) is a shim for languages whose parse-time 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 extractor already carries `ownerId` (C#).
+**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'`.

@@ -184,7 +265,7 @@ References: `semantic-model.ts` file-head (full write/read contract); `contract/

 ## Scope-Resolution Pipeline (RFC #909 Ring 3)

-Language-agnostic scope-resolution resolver. This is the resolution path for every language — it owns CALLS/ACCESSES/USES emission and inheritance edges. Adding a language is one interface implementation (`ScopeResolver`) plus one registration in the `SCOPE_RESOLVERS` map — no changes to shared code, no new pipeline phase. (RING4-1 #942 removed the legacy call-resolution DAG and the per-language `MIGRATED_LANGUAGES` flag, so `SCOPE_RESOLVERS` registration is all that's needed.)
+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

@@ -205,19 +286,7 @@ Language-agnostic scope-resolution resolver. This is the resolution path for eve
 ```

 Orchestrator: `runScopeResolution(input, provider)` in `scope-resolution/pipeline/run.ts`.
-Pipeline phase: `scopeResolutionPhase` in `scope-resolution/pipeline/phase.ts` — iterates the registered `SCOPE_RESOLVERS` over the worker-serialized `ParsedFile`s. (Per-language `emitScopeCaptures` hooks may reuse a cached Tree via the orchestrator's `treeCache`, but in worker-pool runs that cache is empty — Trees can't cross MessageChannels — so they consume the pre-extracted `ParsedFile` instead; § Performance notes.)
-
-### Optional CFG/PDG emission (`--pdg`, #2081–#2086)
-
-On a `--pdg` run the parse worker builds a per-function control-flow graph from the tree-sitter AST (`LanguageProvider.cfgVisitor`; TypeScript/JavaScript today) and serializes it onto `ParsedFile.cfgSideChannel` as plain data. Scope-resolution then emits the program-dependence layers from that side-channel **inside Phase 4 of `runScopeResolution`, while the disk-backed ParsedFile store is still live** — the only window where the worker-built CFGs are loaded (the store is cleared right after the phase returns). A standalone post-`mro` phase would read an empty store, so the emit deliberately lives in-phase, mirroring the `applyCaptureSideChannel` pattern. The opt-in is off by default (graph byte-identical), folded into the parse-cache key (a pdg-off warm cache is never reused on a `--pdg` run), and each layer is bounded by a per-function edge cap that logs any dropped edges. All layers are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table, keyed by `type`; there is **no** `Function → BasicBlock` edge — the symbol↔block join is reconstructed from the BasicBlock id prefix + line span. The layers build on each other:
-
- **M1 — CFG** (#2081): `BasicBlock` nodes + `CFG` edges. Edge *kind* (`seq`/`cond-true`/`loop-back`/…) rides the `reason` column (CFG is one `CodeRelation` type, not one per kind).
- **M2 — REACHING_DEF** (#2082): GEN/KILL def→use data dependence from a pure fixpoint solver; the variable name rides `reason`.
- **M3/M4 — TAINTED / SANITIZES / TAINT_PATH** (#2083–#2084): intra- and inter-procedural taint (source→sink) — the `explain` tool's data.
- **M5 — CDG** (#2085): Ferrante control dependence over a Cooper–Harvey–Kennedy post-dominator tree (the EXIT-rooted reverse CFG); branch sense (`'T'`/`'F'`) rides `reason`. A CFG whose EXIT is unreachable from some block is skipped for CDG (post-dominance would be unsound) while its CFG/REACHING_DEF layers are kept.
- **M6 — read surface** (#2086): the `pdg_query` MCP tool answers "what gates X?" (CDG, `mode: controls`) and "where does Y flow?" (REACHING_DEF, `mode: flows`); `explain` is the taint consumer. Both are always anchored + `LIMIT`-bounded (LadybugDB has no rel-property index) and share one `resolveBlockAnchor` helper. These PDG edge types are deliberately kept out of the default `VALID_RELATION_TYPES` / web schema.
-
-See `core/ingestion/cfg/` (emit + the pure CFG / post-dominator / control-dependence / reaching-defs / taint passes) and `mcp/local/local-backend.ts` (`_pdgQueryImpl`, `_explainImpl`, the shared `resolveBlockAnchor`).
+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

@@ -243,6 +312,7 @@ Single interface a language implements to plug into the pipeline. Contract fully

 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.

@@ -258,6 +328,7 @@ CI auto-discovers the set via `tsx`. No workflow edit required.
 | `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 |
@@ -266,7 +337,7 @@ CI auto-discovers the set via `tsx`. No workflow edit required.

 ### Performance notes

- **Cross-phase Tree cache**: the orchestrator's `treeCache` (`RunScopeResolutionInput.treeCache`) lets a scope-resolution per-language hook (`emitScopeCaptures`) reuse a tree instead of re-parsing. Workers leave it empty — Trees can't cross MessageChannels — so in normal (worker-pool) runs scope-resolution does NOT rely on it: workers serialize each file's `ParsedFile` (+ capture side-channel) and stream them in, so scope-resolution consumes the pre-extracted artifact rather than re-parsing on the main thread (§ Chunked parse-and-resolve). `PROF_SCOPE_RESOLUTION=1` emits hit/miss counters and a worker-engaged warning.
+- **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.
@@ -280,7 +351,7 @@ CI auto-discovers the set via `tsx`. No workflow edit required.
 ```
 Unified Graph Schema (44 node types, 21 relationship types)
           ↑
- Scope-Resolution Pipeline (registry lookup + 3-tier import resolution + MRO)
+ Unified Resolution (3-tier name lookup + MRO walk)
           ↑
 Language Providers (import semantics, type config, export checker, MRO strategy)
           ↑
@@ -305,7 +376,7 @@ Each language implements `LanguageProvider` (`language-provider.ts`). Key fields

 ### 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`, `@reference.inherits`. Downstream extraction needs no language branching. Defined in `tree-sitter-queries.ts`.
+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

@@ -329,26 +400,23 @@ Unified 3-tier algorithm (`model/resolution-context.ts`), per-language `importSe
 ### Chunked parse-and-resolve

 `parse` processes files in ~20 MB byte-budget chunks to bound memory. Per chunk:
-1. Worker pool dispatches files (the sole parse path — there is no sequential fallback; `skipWorkers`, `--workers 0`, and `GITNEXUS_WORKER_POOL_SIZE=0` are rejected with an actionable error)
+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
+4. Resolve imports and heritage
 5. Collect `BindingAccumulator` entries for cross-file propagation

-Inheritance edges are emitted later, by the scope-resolution phase (`preEmitInheritanceEdges` + `emitHeritageEdges`), not during `parse`.
-
 Workers: `workers/worker-pool.ts`, `workers/parse-worker.ts`.

-**Worker-serialized ParsedFiles (#2038).** To index very large repos (e.g. the Linux kernel) without OOM, the worker pool is the *sole* parse path and workers serialize each file's `ParsedFile` (plus its capture side-channel) in parallel, streaming them to scope-resolution through a disk-backed store. Scope-resolution consumes the pre-extracted artifact instead of re-parsing every file on the main thread — tree-sitter's native input buffers are not GC-reclaimable, so the former main-thread re-parse leaked native memory until the process died. Pool creation is lazy / cache-miss-gated, so a warm all-cache-hit run replays cached worker output without spawning a worker (hence `usedWorkerPool` can be false even when the repo has parseable files).
+### Heritage and MRO

-### Inheritance and MRO
-
-Inheritance is captured by the `@reference.inherits` tag and emitted by the scope-resolution phase: `preEmitInheritanceEdges` resolves each base in scope, then `emitHeritageEdges` writes the `EXTENDS`/`IMPLEMENTS` edges. The phase then computes method resolution order via each `ScopeResolver`'s `buildMro` hook, feeding a `MethodDispatchIndex` used for owner-scoped lookups. Per-language strategy:
+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)
- **`ruby-mixin`** — Ruby (mixin-aware linearization)
 - **`none`** — single-inheritance languages

+Unified walk: `lookupMethodByOwnerWithMRO()` in `model/resolve.ts`.
+
 ---

 ## Full analysis flow
@@ -394,8 +462,6 @@ Defined in `lbug/schema.ts`. Separate node tables per type, single `CodeRelation

 **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.

-**Optional `--pdg` additions** (off by default, opt-in via `gitnexus analyze --pdg`; see _Optional CFG/PDG emission_ above): a `BasicBlock` node table, plus the PDG relation types `CFG`, `REACHING_DEF`, `CDG`, `TAINTED`, `SANITIZES`, and `TAINT_PATH` on the same `CodeRelation` table. These are deliberately kept out of the default `VALID_RELATION_TYPES` / web graph schema — query them via `cypher`, `explain`, or `pdg_query`.
-
 ## 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.
@@ -4,6 +4,12 @@ All notable changes to GitNexus will be documented in this file.

 ## [Unreleased]

+### Changed
+- Migrated from KuzuDB to LadybugDB v0.15 (`@ladybugdb/core`, `@ladybugdb/wasm-core`)
+- Renamed all internal paths from `kuzu` to `lbug` (storage: `.gitnexus/kuzu` → `.gitnexus/lbug`)
+- Added automatic cleanup of stale KuzuDB index files
+- LadybugDB v0.15 requires explicit VECTOR extension loading for semantic search
+
 ## [1.5.3] - 2026-04-01

 ### Added
@@ -35,7 +35,7 @@ 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 & inheritance resolution:** See ARCHITECTURE.md § Scope-Resolution Pipeline. Shared pipeline code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` / `ScopeResolver` hooks instead (see AGENTS.md). (The legacy call-resolution DAG was removed in #942.)
+- **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
@@ -52,67 +52,3 @@ 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:start -->
-# GitNexus — Code Intelligence
-
-This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
-
-> Index stale? Run `node .gitnexus/run.cjs analyze` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? `npx gitnexus analyze` (npm 11 crash → `npm i -g gitnexus`; #1939).
-
-## Always Do
-
- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
- **MUST run `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 `query({search_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 `context({name: "symbolName"})`.
-
-## Never Do
-
- NEVER edit a function, class, or method without first running `impact` on it.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.
- NEVER commit changes without running `detect_changes()` to check affected scope.
-
-## 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 |
-
-## 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` |
-| Work in the Ingestion area (239 symbols) | `.claude/skills/generated/ingestion/SKILL.md` |
-| Work in the Extractors area (135 symbols) | `.claude/skills/generated/extractors/SKILL.md` |
-| Work in the Components area (112 symbols) | `.claude/skills/generated/components/SKILL.md` |
-| Work in the Lbug area (96 symbols) | `.claude/skills/generated/lbug/SKILL.md` |
-| Work in the Group area (94 symbols) | `.claude/skills/generated/group/SKILL.md` |
-| Work in the Cli area (92 symbols) | `.claude/skills/generated/cli/SKILL.md` |
-| Work in the Configs area (92 symbols) | `.claude/skills/generated/configs/SKILL.md` |
-| Work in the Type-extractors area (90 symbols) | `.claude/skills/generated/type-extractors/SKILL.md` |
-| Work in the Hooks area (88 symbols) | `.claude/skills/generated/hooks/SKILL.md` |
-| Work in the Unit area (80 symbols) | `.claude/skills/generated/unit/SKILL.md` |
-| Work in the Cpp area (73 symbols) | `.claude/skills/generated/cpp/SKILL.md` |
-| Work in the Scope-resolution area (72 symbols) | `.claude/skills/generated/scope-resolution/SKILL.md` |
-| Work in the Server area (66 symbols) | `.claude/skills/generated/server/SKILL.md` |
-| Work in the Local area (61 symbols) | `.claude/skills/generated/local/SKILL.md` |
-| Work in the Wiki area (60 symbols) | `.claude/skills/generated/wiki/SKILL.md` |
-| Work in the Workers area (57 symbols) | `.claude/skills/generated/workers/SKILL.md` |
-| Work in the Embeddings area (56 symbols) | `.claude/skills/generated/embeddings/SKILL.md` |
-| Work in the Typescript area (53 symbols) | `.claude/skills/generated/typescript/SKILL.md` |
-| Work in the Storage area (51 symbols) | `.claude/skills/generated/storage/SKILL.md` |
-| Work in the Php area (48 symbols) | `.claude/skills/generated/php/SKILL.md` |
-
-<!-- gitnexus:end -->
@@ -13,17 +13,11 @@ This project uses the [PolyForm Noncommercial License 1.0.0](https://polyformpro

 ## Development setup

-**Prerequisites:** Node.js — `gitnexus/` requires `>=22.0.0` and `gitnexus-web/` requires `^20.19.0 || >=22.12.0` (enforced via the `engines` field in each package). Use `nvm install` to match the local version.
-
 1. Clone the repository.
 2. **CLI / MCP package:** `cd gitnexus && npm install && npm run build`
 3. **Web UI (if needed):** `cd gitnexus-web && npm install`
 4. Run tests as described in [TESTING.md](TESTING.md).

-### Containerized development (optional)
-
-If you prefer an isolated environment with Claude Code, OpenAI Codex CLI, and Cursor CLI pre-installed, open the repo in VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and run **Dev Containers: Reopen in Container**. See [`.devcontainer/README.md`](.devcontainer/README.md) for first-time auth flows and Windows WSL2 setup.
-
 ## Branch and pull requests

 - Use short-lived branches off the default branch of the repo you are targeting.
@@ -36,17 +30,17 @@ 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)                                |
+| 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.

@@ -87,17 +81,17 @@ Every workflow under `.github/workflows/` MUST declare a top-level `concurrency:
  - **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       |
+  | 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:

@@ -109,73 +103,22 @@ Every workflow under `.github/workflows/` MUST declare a top-level `concurrency:

 - 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.
-
-### Vendored tree-sitter grammars
-
-`.github/vendored-grammars.json` is the **single source of truth** for the vendored tree-sitter grammar **set** and each grammar's policy `hold` (the ones shipped from `gitnexus/vendor/<name>` rather than installed from npm). It lists each grammar's name, upstream coords (`npm` or `github`), and any `hold`. The monitor resolves upstreams from it; the readiness report keeps its own upstream-drift coords and reads vendored ABIs from `gitnexus/vendor/`. Two workflows read it:
-
- `grammar-update-monitor.yml` (`.github/scripts/update-vendored-grammars.mjs`) — weekly; opens auto-PRs re-vendoring ABI-compatible upstream updates.
- `tree-sitter-upgrade-readiness.yml` (`.github/scripts/check-tree-sitter-upgrade-readiness.py`) — daily; renders the tree-sitter-0.25 readiness report (issue #858), reading each vendored grammar's ABI from `gitnexus/vendor/<name>/src/parser.c`.
-
-Sharing the manifest keeps the two aligned: a consistency-guard test asserts the manifest set equals the `gitnexus/vendor/tree-sitter-*` directories. **When you vendor a new grammar (or remove one), update `.github/vendored-grammars.json` in the same change** — otherwise that guard fails CI and the readiness report regresses to `?` placeholders.
-
 ## 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

-One workflow ships `gitnexus` to npm — `.github/workflows/publish.yml`. It
-routes between two modes based on the triggering event:
+Two publish workflows ship `gitnexus` to npm:

- **Stable mode** — triggered by pushing any `v<X.Y.Z>` tag (no `-rc.*`
-  suffix; RC tags are excluded at trigger via a negative glob). 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. No Docker build (RC-only). Before cutting a
-  stable release, keep `gitnexus/package.json`,
-  `gitnexus-claude-plugin/.claude-plugin/plugin.json`,
-  `.claude-plugin/marketplace.json`, and the matching `CHANGELOG.md` entry in
-  lockstep — the always-on `gitnexus` unit suite now fails if those manifest
-  versions drift.
- **Release-candidate mode** — runs on every push to `main` (typically a
-  merged PR) plus manual `workflow_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:
+- **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
@@ -192,64 +135,37 @@ routes between two modes based on the triggering event:
    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
-  RC 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). The RC tag is excluded
-  from this workflow's `push: tags:` filter, so it does **not** re-trigger
-  publishing — preventing the double-publish failure mode tracked in #1609.
-  Recovery after a partial failure: the workflow's `if: failure()` cleanup
-  step in the `publish` job auto-deletes the v-tag and marker on most
-  post-publish failures, so the typical retry is just:
-
-  ```bash
-  gh workflow run publish.yml --ref main -f force=true
-  # or push a new commit to main, which will cut a fresh RC
-  ```
-
-  If auto-cleanup didn't run (e.g. the cleanup step itself failed, or the
-  failure happened in the route/rc-guard phase before the marker was
-  pushed), manual cleanup is:
+  `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 with force: true
+  # then redispatch the workflow with force: true
  ```

-  **Release-PR-skip subject pattern.** The rc-guard job recognizes a
-  squash-merged release commit by matching the commit subject against
-  `^chore: release vX.Y.Z` (optionally followed by ` (#NNNN)` for the
-  squash-merge PR-number suffix). Match is case-insensitive — `Chore: Release v1.2.3`
-  works too. PRs that should suppress the RC build must either use this
-  subject shape, or carry the `release` label so the label-based fallback
-  fires. Other release-style subjects (`chore(release): v1.2.3`,
-  `release: v1.2.3`) will NOT trigger the skip — please name the release
-  PR exactly `chore: release vX.Y.Z` to keep the dedup deterministic.
-
  **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.
-  Recovery without cutting a new RC:
+  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
-  # Re-run only the failed docker job from the original workflow run:
-  gh run rerun <run-id> --failed
+  # 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)
  ```

-  Find the run ID via `gh run list --workflow=publish.yml --branch main`.
-  `docker.yml` intentionally has no `workflow_dispatch` trigger (images are
-  tag-driven by design), so the gh-run-rerun path is the supported recovery.
-
-  **GitHub Release transient failure** (npm publish succeeded, Release step
-  failed): the npm artifact is live but no GitHub Release page exists.
-  Recover by either re-running the failed job (`gh run rerun <run-id> --failed`),
-  or creating the Release manually:
-
-  ```bash
-  gh release create v<RC> --prerelease --generate-notes        # RC
-  gh release create v<X.Y.Z> --notes-file gitnexus/CHANGELOG.md # stable
-  ```
+  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:

@@ -1,32 +1,24 @@
 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 -----------------------------------------------------------
+# ── 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
+FROM node:22-trixie-slim AS builder

 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.
+# 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
+# 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.
@@ -36,26 +28,11 @@ RUN npm ci --prefix gitnexus
 # Drop dev dependencies for a smaller runtime layer.
 RUN npm prune --omit=dev --prefix gitnexus

-# `npm prune` removes anything not in package.json's dependency tree — which
-# includes the VENDORED tree-sitter grammars (materialized into node_modules/ by
-# postinstall, but not declared as deps) and their freshly-built native bindings.
-# The `serve` image analyzes/parses uploaded repos at runtime, so those grammars
-# must survive into the runtime layer. Re-run the grammar postinstall here in the
-# builder (which still has python3/make/g++ and the hoisted node-addon-api /
-# node-gyp-build) to re-materialize + rebuild them after the prune. This is
-# load-bearing for tree-sitter-c (a core, REQUIRED grammar now vendored, #2116):
-# as a former `dependency` it used to survive prune; vendored, it would not.
-RUN npm run postinstall --prefix gitnexus
+# ── Runtime ────────────────────────────────────────────────────────────
+FROM node:22-trixie-slim AS runtime

-# -- Runtime -----------------------------------------------------------
-# node:22-bookworm-slim
-FROM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS runtime
-
-# curl for the healthcheck; git for cloning; ca-certificates for TLS verification.
-RUN apt-get update && apt-get install -y --no-install-recommends curl git ca-certificates && 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
+# 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/*

 WORKDIR /app

@@ -66,59 +43,11 @@ 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

-# Expose the `gitnexus` binary on PATH so the documented Docker workflow
-# (`docker compose exec gitnexus-server gitnexus index /workspace/<repo>`)
-# works without users having to invoke `node /app/gitnexus/dist/cli/index.js`.
-# `npm prune --omit=dev` in the builder stage strips `node_modules/.bin/`
-# entries, so the `gitnexus` bin declared in package.json (`dist/cli/index.js`,
-# which already carries `#!/usr/bin/env node` and 755 perms) is otherwise
-# unreachable from $PATH.
-RUN ln -s /app/gitnexus/dist/cli/index.js /usr/local/bin/gitnexus
-
-# Bake the LadybugDB FTS extension into the image so BM25 keyword search works
-# at runtime. The server runs the default `load-only` extension policy (the read
-# pool pins `{ policy: 'load-only' }`), so a runtime `LOAD EXTENSION fts` never
-# INSTALLs — the extension must already exist in the runtime user's HOME
-# extension dir, or every keyword search silently degrades (no FTS indexes are
-# written and ranking falls back to vector-only with only a `warning` field).
-# Run the installer as the `node` user with the SAME HOME the server runs under,
-# so `INSTALL fts` materializes the extension under `$HOME/.lbdb/extension` where
-# the runtime `LOAD` resolves it offline. `ENV HOME` is pinned because Docker
-# does not derive HOME from `USER`, so without it build-install and runtime-load
-# would resolve different paths. Requires network egress for the one-time
-# INSTALL; the build fails loudly if it cannot fetch the extension. The DB-size
-# default comes from GITNEXUS_LBUG_MAX_DB_SIZE (single source of truth, matches
-# the runtime) — it only sizes the throwaway scratch DB used to run INSTALL.
-# The second `--verify-only` step re-LOADs the extension in a FRESH process
-# under the same HOME, so a HOME/extension-dir mismatch fails the build here
-# rather than silently degrading keyword search to vector-only at runtime.
-ENV HOME=/home/node \
-    GITNEXUS_LBUG_MAX_DB_SIZE=17179869184
-RUN su node -s /bin/sh -c "HOME=/home/node node /app/gitnexus/scripts/install-duckdb-extension.mjs fts" \
- && su node -s /bin/sh -c "HOME=/home/node node /app/gitnexus/scripts/install-duckdb-extension.mjs fts --verify-only"
-
-# Published runtime assets (in package.json `files`). Placed AFTER the DuckDB
-# FTS-extension RUN above so editing hook/skill content does not invalidate that
-# network-fetching cache layer; they have no input dependency on it.
-# `hooks/`: dist/cli/resolve-invocation.js does
-# `require('../../hooks/claude/resolve-analyze-cmd.cjs')` at module load — the
-# single source of truth for the npm-11 npx-crash invocation decision (#1939).
-# Without it, `gitnexus analyze` inside the image crashes with MODULE_NOT_FOUND
-# before it does any work (#2130). `skills/`: the CLI reads the bundled SKILL.md
-# templates from `<pkg>/skills/` for `gitnexus analyze --skills` and `gitnexus
-# setup`/`uninstall`; absent, those degrade silently (placeholder content / zero
-# skills installed). (The web UI bundle `web/`, also in `files`, is deliberately
-# NOT shipped: this builder never builds gitnexus-web, so the image is API-only;
-# the UI is the separate Dockerfile.web image / hosted app.)
-COPY --from=builder --chown=node:node /app/gitnexus/hooks ./gitnexus/hooks
-COPY --from=builder --chown=node:node /app/gitnexus/skills ./gitnexus/skills
-
 USER node

-# The web UI defaults to http://localhost:4747 - keep that contract.
+# The web UI defaults to http://localhost:4747 — keep that contract.
 ENV GITNEXUS_HOME=/data/gitnexus \
    NODE_ENV=production \
    PORT=4747
@@ -1,17 +1,10 @@
 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
+FROM --platform=$BUILDPLATFORM node:22-alpine AS builder

 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

@@ -26,13 +19,9 @@ 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
+FROM node:22-alpine 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
+RUN apk add --no-cache curl

 WORKDIR /app

@@ -30,15 +30,9 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
 ### 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.
+- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used).
 - **Why:** Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.

-### Index seems corrupt or "incremental" is misbehaving
-
- **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 the `.gitnexus/parse-cache/` directory (and any legacy `.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.
-
 ### Embeddings vanished after analyze

 - **Trigger:** Semantic search quality drops; `stats.embeddings` in `meta.json` is 0 after refresh.
@@ -1,5 +1,4 @@
 # 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">
@@ -22,9 +21,6 @@
  <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>
-  <a href="https://github.com/abhigyanpatwari/GitNexus/actions/workflows/ci.yml">
-    <img src="https://github.com/abhigyanpatwari/GitNexus/actions/workflows/ci.yml/badge.svg" alt="CI Workflows"/>
-  </a>

  <p><strong>Enterprise (SaaS & Self-hosted)</strong> - <a href="https://akonlabs.com">akonlabs.com</a></p>

@@ -34,11 +30,16 @@

 Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart tools so AI agents never miss code.

+
+
+
 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, Antigravity, 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.
+
+> *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.

 ---

@@ -46,17 +47,18 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72

 [![Star History Chart](https://api.star-history.com/svg?repos=abhigyanpatwari/GitNexus&type=date&legend=top-left)](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left)

+
 ## Two Ways to Use GitNexus

-|             | **CLI + MCP**                                                         | **Web UI**                                                           |
-| ----------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| **What**    | Index repos locally, connect AI agents via MCP                        | Visual graph explorer + AI chat in browser                           |
-| **For**     | Daily development with Cursor, Claude Code, Antigravity, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                           |
-| **Scale**   | Full repos, any size                                                  | Limited by browser memory (~5k files), or unlimited via backend mode |
-| **Install** | `npm install -g gitnexus`                                             | No install — [gitnexus.vercel.app](https://gitnexus.vercel.app)      |
-| **Storage** | LadybugDB native (fast, persistent)                                   | LadybugDB WASM (in-memory, per session)                              |
-| **Parsing** | Tree-sitter native bindings                                           | Tree-sitter WASM                                                     |
-| **Privacy** | Everything local, no network                                          | Everything in-browser, no server                                     |
+|                   | **CLI + MCP**                                            | **Web UI**                                             |
+| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
+| **What**    | Index repos locally, connect AI agents via MCP                 | Visual graph explorer + AI chat in browser                   |
+| **For**     | Daily development with Cursor, Claude Code, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                   |
+| **Scale**   | Full repos, any size                                           | Limited by browser memory (~5k files), or unlimited via backend mode |
+| **Install** | `npm install -g gitnexus`                                    | No install — [gitnexus.vercel.app](https://gitnexus.vercel.app) |
+| **Storage** | LadybugDB native (fast, persistent)                               | LadybugDB WASM (in-memory, per session)                         |
+| **Parsing** | Tree-sitter native bindings                                    | Tree-sitter WASM                                             |
+| **Privacy** | Everything local, no network                                   | Everything in-browser, no server                             |

 > **Bridge mode:** `gitnexus serve` connects the two — the web UI auto-detects the local server and can browse all your CLI-indexed repos without re-uploading or re-indexing.

@@ -67,7 +69,6 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 GitNexus is available as an **enterprise offering** - either as a fully managed **SaaS** or a **self-hosted** deployment. Also available for **commercial use** of the OSS version with proper licensing.

 Enterprise includes:
-
 - **PR Review** - automated blast radius analysis on pull requests
 - **Auto-updating Code Wiki** - always up-to-date documentation (Code Wiki is also available in OSS)
 - **Auto-reindexing** - knowledge graph stays fresh automatically
@@ -76,7 +77,6 @@ Enterprise includes:
 - **Priority feature/language support** - request new languages or features

 **Upcoming:**
-
 - Auto regression forensics
 - End-to-end test generation

@@ -107,48 +107,34 @@ npx gitnexus analyze

 That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.

-> **On npm 11.x?** `npx` can crash during install with `Cannot destructure property 'package' of 'node.target'` (an npm/arborist bug, before GitNexus runs). Use pnpm instead — it builds the native deps explicitly:
->
-> ```bash
-> pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze
-> ```
->
-> Or install globally (`npm install -g gitnexus@latest`) and run `gitnexus analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
-
 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 vendored grammar materialize/build for `tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift`, and `tree-sitter-kotlin` — those four won't be parsed, but install completes in seconds without `python3`/`make`/`g++`. Strict `=1` only — any other value falls through to the rebuild. See the `tree-sitter-kotlin` note below.
->
-> **About `tree-sitter-kotlin`:** like Dart/Proto/Swift, Kotlin is a **vendored** grammar (under `gitnexus/vendor/tree-sitter-kotlin`). Upstream `tree-sitter-kotlin` ships **source only** (no prebuilt binaries), so GitNexus builds the Kotlin platform prebuilds itself (via the `build-tree-sitter-prebuilds` GitHub Actions workflow) and vendors them — the same uniform pipeline now used for Dart, Proto, and Swift (Swift's prebuilds were originally copied from upstream; they're now GitNexus-cross-built too). `node-gyp-build` selects the right `.node` at require time, so **no C/C++ toolchain is needed**. If no prebuild matches your platform-arch, only Kotlin (`.kt`/`.kts`) parsing is unavailable; the rest of `gitnexus` is unaffected.
+> **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. To configure only selected integrations, pass `--coding-agent`/`-c` with a comma-separated list or repeat the option, for example `gitnexus setup -c cursor,codex`.
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.

 ### Editor Support

-| 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**     |
-| **Antigravity** (Google) | Yes | Yes | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))[¹](#fn-antigravity-hooks) | **Full**     |
-| **Codex**            | Yes | Yes    | —                                                                                       | MCP + Skills |
-| **Windsurf**         | Yes | —      | —                                                                                       | MCP          |
-| **OpenCode**         | Yes | Yes    | —                                                                                       | MCP + Skills |
+| Editor                | MCP | Skills | Hooks (auto-augment) | Support        |
+| --------------------- | --- | ------ | -------------------- | -------------- |
+| **Claude Code** | Yes | Yes    | Yes (PreToolUse + PostToolUse) | **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.

-<a id="fn-antigravity-hooks"></a>
-> ¹ **Antigravity hooks** follow the [Gemini CLI hooks reference](https://geminicli.com/docs/hooks/reference/) (Antigravity 2.0 is the documented successor to Gemini CLI). Augmentation runs in `AfterTool` because `BeforeTool` has no context-injection channel in the Gemini contract — the agent sees graph context appended to the tool result via `hookSpecificOutput.additionalContext`. Stale-index hints land in the same channel after a successful `git commit/merge/rebase/cherry-pick/pull`. The schema may evolve if Antigravity-specific hook docs diverge from Gemini CLI's; the implementation will track those changes.
-
 ## Community Integrations

 Built by the community — not officially maintained, but worth checking out.

-| Project                                                                       | Author                                                 | Description                                                             |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
-| [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus)                       | [@tintinweb](https://github.com/tintinweb)             | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` |
-| [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/ShunsukeHayashi) | Stable ops & deployment workflows (Miyabi ecosystem)                    |
+| Project | Author | Description |
+|---------|--------|-------------|
+| [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) | [@tintinweb](https://github.com/tintinweb) | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` |
+| [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/ShunsukeHayashi) | Stable ops & deployment workflows (Miyabi ecosystem) |

 > Have a project built on GitNexus? Open a PR to add it here!

@@ -185,21 +171,6 @@ codex mcp add gitnexus -- npx -y gitnexus@latest mcp
 }
 ```

-**Antigravity** (Google) — `~/.gemini/antigravity/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
-    }
-  }
-}
-```
-
-> `gitnexus setup` also merges an `AfterTool` entry into `~/.gemini/settings.json` (under the canonical [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/)) and installs skills to `~/.gemini/antigravity/skills/`. Existing user hooks are preserved. The hook adapter's path is rewritten at install time, so run `gitnexus setup` rather than hand-editing.
-
 **OpenCode** (`~/.config/opencode/config.json`):

 ```json
@@ -224,22 +195,16 @@ args = ["-y", "gitnexus@latest", "mcp"]
 ### CLI Commands

 ```bash
-gitnexus setup                   # Configure MCP for detected editors (one-time; use -c to select)
-gitnexus uninstall               # Preview removal of GitNexus MCP/skills/hooks (add --force to apply)
+gitnexus setup                   # Configure MCP for your editors (one-time)
 gitnexus analyze [path]          # Index a repository (or update stale index)
-gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
-gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
+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-skills     # Skip installing .claude/skills/gitnexus/ skill files
-gitnexus analyze --default-branch develop  # Branch used in the generated regression-compare example (base_ref)
 gitnexus analyze --skip-git        # Index folders that are not Git repositories
-gitnexus analyze --embeddings [limit]  # Enable embedding generation (slower, better search)
+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 analyze --wal-checkpoint-threshold 67108864  # 64 MiB. Control LadybugDB WAL auto-checkpoint threshold (default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)
-gitnexus analyze --workers <n>        # Parse worker pool size (>=1; default: cores-1, capped at 16, auto-sized to the repo). 0 is rejected — there is no sequential mode.
 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
@@ -249,7 +214,6 @@ 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
@@ -262,111 +226,33 @@ gitnexus group query <name> <q>  # Search execution flows across all repos in a
 gitnexus group status <name>     # Check staleness of repos in a group
 ```

-> **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove.
-
 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.

-#### Embeddings node limit
-
-`gitnexus analyze --embeddings` generates semantic search vectors with a default 50,000-node safety cap to protect memory on large repositories. Override the cap when you know the host has enough memory for a larger graph, or disable it entirely for a one-off full embeddings run.
-
-```bash
-# Generate embeddings with the default 50,000 node safety cap
-gitnexus analyze --embeddings
-
-# Disable the safety cap entirely
-gitnexus analyze --embeddings 0
-
-# Use a custom cap
-gitnexus analyze --embeddings 100000
-```
-
-If embeddings are skipped on a large repository, the indexed graph likely exceeds the default safety cap. Re-run with `gitnexus analyze --embeddings 0` to remove the cap, or `gitnexus analyze --embeddings <n>` to choose a higher limit while still keeping memory bounded.
-
-#### Project config (`.gitnexusrc`)
-
-Commit a `.gitnexusrc` JSON file at the repo root to preconfigure recurring `analyze` options per project, instead of re-passing the same flags every run. It is read from the resolved repo root (not `.gitnexus/`, which is gitignored index storage). **CLI flags always override `.gitnexusrc`.**
-
-```jsonc
-{
-  // Default branch used in the generated regression-compare example (base_ref).
-  // Use this so a project on `develop`/`master` doesn't get "main" rewritten
-  // over its fix on every analyze. (Alias: "branch".)
-  "defaultBranch": "develop",
-  "skipContextFiles": true, // alias of skipAgentsMd: keep your own AGENTS.md/CLAUDE.md
-  "skipSkills": true, // don't install .claude/skills/gitnexus/
-  "embeddings": true, // generate embeddings by default
-  "workerTimeout": 60
-}
-```
-
-A nested `analyze` block is also accepted (and overrides flat keys for the same option):
-
-```json
-{ "analyze": { "defaultBranch": "develop", "skipSkills": true } }
-```
-
-Notes:
-
- The default branch is resolved as: `--default-branch` > `.gitnexusrc` `defaultBranch`/`branch` > auto-detected `origin/HEAD` > `main`.
- `skipContextFiles` / `skipAiContext` are aliases for `skipAgentsMd` — they skip the `AGENTS.md` / `CLAUDE.md` block only. They do **not** imply `skipSkills`. `indexOnly` is the stronger option that skips all file injection.
- Supported keys: `defaultBranch` (`branch`), `skipAgentsMd` (`skipContextFiles`, `skipAiContext`), `skipSkills`, `indexOnly`, `stats`/`noStats`, `embeddings`, `dropEmbeddings`, `name`, `allowDuplicateName`, `maxFileSize`, `workerTimeout`, `walCheckpointThreshold`, `workers`, `embeddingThreads`, `embeddingBatchSize`, `embeddingSubBatchSize`, `embeddingDevice`.
- The file is JSON only. Unknown keys and invalid values fail fast with an actionable error before analysis starts.
-
-#### Environment variables
-
-Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max-file-size`, `--verbose`). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over env vars; env vars take precedence over built-in defaults.
-
-| Variable                               | Default                   | Effect                                                                                                                                                     | Tune when…                                                                                                                                  |
-| -------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GITNEXUS_WORKER_POOL_SIZE`            | `cores - 1`, capped at 16 | Parse worker pool size (must be ≥ 1). Equivalent to `--workers <n>`. The worker pool is the sole parse path — there is no sequential parser, so `0` is rejected with an actionable error (the pool self-heals via quarantine + respawn). | Constrained containers (cgroup CPU limits) or CI runners with explicit quotas. To narrow down a worker crash set `1` for a single-worker pool — not `0`. |
-| `GITNEXUS_PARSE_CHUNK_CONCURRENCY`     | `2`                       | Number of chunks whose file contents may be read into memory in parallel while the pool dispatches the current chunk. Worker dispatch itself stays serial. | Repos large enough to chunk (multi-MB total source) where disk I/O is a measurable fraction of analyze wall-clock.                          |
-| `GITNEXUS_VERBOSE`                     | unset                     | When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`.                      | Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput. |
-| `GITNEXUS_PROFILE_DEFERRED`            | unset                     | When `1`, emits `[deferred-profile]` timing/progress logs for the post-chunk deferred resolution band (imports → heritage → buildHeritageMap → legacy call resolution). Implied by `GITNEXUS_VERBOSE`. | Diagnosing analyze stalls in "Resolving calls (all chunks)" on large Java/Kotlin repos (issue #1741) without the full verbose ingestion noise. |
-| `GITNEXUS_PROFILE_DEFERRED_SLOW_MS`    | `3000` (verbose) / `5000` | Per-file threshold in ms above which `processCallsFromExtracted` emits a `slow file …` log line. Parsed via `Number()`: accepts integers (`5000`), scientific notation (`2.5e3`), decimals (`.5`), and hex (`0x10`). Non-finite or non-positive values fall back to the default. | Hunting a few outlier files dominating the deferred call-resolution stage; lower to surface more, raise to focus only on the worst.          |
-| `PROF_LBUG_LOAD`                       | unset                     | When `1`, emits one `[lbug-load prof]` summary line per `loadGraphToLbug` call breaking the graph-DB persistence wall into stages (`csv-emit` / `copy-nodes` / `copy-rels` / `fallback` / `total`) plus node & edge counts. Zero-cost when unset. | Attributing large-repo analyze wall time across CSV generation vs. LadybugDB `COPY` (issue #2203) — the analyze "emit" timing is the scope-resolution bucket, not this DB-write path. |
-| `GITNEXUS_MAX_FILE_SIZE`               | `512` (KB)                | Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`.                                       | Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed.                     |
-| `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS` | `30000`                   | Worker idle timeout in milliseconds before retry/fallback. Equivalent to `--worker-timeout <seconds>` × 1000.                                              | Slow-parsing files (large minified JS, deeply-nested TS types) that legitimately need more than 30s.                                        |
-| `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`       | `67108864` (64 MiB)       | LadybugDB WAL auto-checkpoint threshold in bytes. Equivalent to `--wal-checkpoint-threshold <bytes>`. `-1` keeps LadybugDB's stock threshold (~16 MiB). Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments. | You need a larger or smaller WAL auto-checkpoint threshold for your analyze workload.                                                         |
-| `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES`  | `8388608` (8 MB)          | Per-job byte budget the pool will send to a worker in one `postMessage`.                                                                                   | Very large individual files; mostly diagnostic — bumping past 8 MB risks structured-clone memory pressure.                                  |
-| `GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`        | `3`                       | Max replacement spawns per worker slot before the slot is dropped from the active rotation. Bounds respawn loops on a chronically-crashing slot.           | Hosts where a flaky worker should retry more (raise) or fail-fast (lower) before the slot is dropped.                                       |
-| `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`    | `5 × subBatchTimeoutMs`   | Total retry wall-time budget per job before quarantining. Combined with `timeoutBackoffFactor`, prevents exponentially-growing retries from stalling for hours. | Slow files that legitimately need long total retry windows; lower to fail-fast on stalls.                                                    |
-| `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`| `max(3, poolSize)`        | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, every subsequent dispatch rejects until a fresh pool is created.       | Hosts where a SIGSEGV-prone native grammar should trip the breaker sooner; CI runners that should fail loudly.                              |
-| `GITNEXUS_CHUNK_BYTE_BUDGET`           | `2097152` (2 MB)          | Chunk boundary used for cache-key composition and dispatch. Smaller = finer-grained cache hits but more dispatch overhead.                                 | Tuning incremental-analyze cache behavior on monorepos.                                                                                     |
-| `GITNEXUS_NO_GITIGNORE`                | unset                     | When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored.                                                                                  | Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup).         |
-| `GITNEXUS_SKIP_OPTIONAL_GRAMMARS`      | unset                     | When `=1` strictly, skips the vendored grammar materialize for `tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift`, and `tree-sitter-kotlin` at install time (and the Dart/Proto source builds). Those four won't be parsed; the install still succeeds. | Installing on a host without a C++ toolchain or where the vendored prebuilds don't match; willing to skip Dart/Proto/Swift/Kotlin parsing. |
-
-#### 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):

-| Tool              | What It Does                                                     | `repo` Param |
-| ----------------- | ---------------------------------------------------------------- | ------------ |
-| `list_repos`      | Discover all indexed repositories (paginated — `limit`/`offset`) | —            |
-| `query`           | Process-grouped hybrid search (BM25 + semantic + RRF)            | Optional     |
-| `context`         | 360-degree symbol view — categorized refs, process participation | Optional     |
-| `impact`          | Blast radius analysis with depth grouping and confidence         | Optional     |
-| `detect_changes`  | Git-diff impact — maps changed lines to affected processes       | Optional     |
-| `rename`          | Multi-file coordinated rename with graph + text search           | Optional     |
-| `cypher`          | Raw Cypher graph queries                                         | Optional     |
-| `group_list`      | List configured repository groups                                | —            |
-| `group_sync`      | Extract contracts and match across repos/services                | —            |
-| `group_contracts` | Inspect extracted contracts and cross-links                      | —            |
-| `group_query`     | Search execution flows across all repos in a group               | —            |
-| `group_status`    | Check staleness of repos in a group                              | —            |
+| Tool               | What It Does                                                      | `repo` Param |
+| ------------------ | ----------------------------------------------------------------- | -------------- |
+| `list_repos`     | Discover all indexed repositories                                 | —             |
+| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)             | Optional       |
+| `context`        | 360-degree symbol view — categorized refs, process participation | Optional       |
+| `impact`         | Blast radius analysis with depth grouping and confidence          | Optional       |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes       | Optional       |
+| `rename`         | Multi-file coordinated rename with graph + text search            | Optional       |
+| `cypher`         | Raw Cypher graph queries                                          | Optional       |
+| `group_list`     | List configured repository groups                                 | —             |
+| `group_sync`     | Extract contracts and match across repos/services                 | —             |
+| `group_contracts`| Inspect extracted contracts and cross-links                       | —             |
+| `group_query`    | Search execution flows across all repos in a group                | —             |
+| `group_status`   | Check staleness of repos in a group                               | —             |

-> When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({search_query: "auth", repo: "my-app"})`.
+> When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({query: "auth", repo: "my-app"})`.

 **Resources** for instant context:

-| Resource                                | Purpose                                              |
-| --------------------------------------- | ---------------------------------------------------- |
+| Resource                                  | Purpose                                              |
+| ----------------------------------------- | ---------------------------------------------------- |
 | `gitnexus://repos`                      | List all indexed repositories (read this first)      |
 | `gitnexus://repo/{name}/context`        | Codebase stats, staleness check, and available tools |
 | `gitnexus://repo/{name}/clusters`       | All functional clusters with cohesion scores         |
@@ -377,9 +263,9 @@ It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained G

 **2 MCP prompts** for guided workflows:

-| Prompt          | What It Does                                                              |
-| --------------- | ------------------------------------------------------------------------- |
-| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level        |
+| Prompt            | What It Does                                                              |
+| ----------------- | ------------------------------------------------------------------------- |
+| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level       |
 | `generate_map`  | Architecture documentation from the knowledge graph with mermaid diagrams |

 **4 agent skills** installed to `.claude/skills/` automatically:
@@ -466,10 +352,10 @@ npx gitnexus@latest serve

 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` |
+| 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
@@ -536,7 +422,7 @@ The Docker images are version-locked to the npm package:
  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 `publish.yml` calling `docker.yml`
+  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.
@@ -569,7 +455,7 @@ 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
-`publish.yml` invokes `docker.yml` as a reusable workflow):
+`release-candidate.yml` invokes `docker.yml` as a reusable workflow):

 ```bash
 cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
@@ -685,27 +571,25 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas

 ### Supported Languages

-| Language   | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
-| ---------- | ------- | -------------- | ------- | -------- | ---------------- | --------------------- | ------ | ---------- | ------------ |
-| TypeScript | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
-| JavaScript | ✓       | ✓              | ✓       | ✓        | —                | ✓                     | ✓      | ✓          | ✓            |
-| Python     | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
-| Java       | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
-| Kotlin     | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
-| C#         | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
-| Go         | ✓       | —              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
-| Rust       | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
-| PHP        | ✓       | ✓              | ✓       | —        | ✓                | ✓                     | ✓      | ✓          | ✓            |
-| Ruby       | ✓       | —              | ✓       | ✓        | —                | ✓                     | —      | ✓          | ✓            |
-| Swift      | —       | —              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
-| C          | —       | —              | ✓       | —        | ✓                | ✓                     | —      | ✓          | ✓            |
-| C++        | —       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
-| Dart       | ✓       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
+|----------|---------|----------------|---------|----------|-----------------|---------------------|--------|------------|-------------|
+| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
+| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
+| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ |
+| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| Dart | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |

 **Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics

-**Control flow (CFG, opt-in `--pdg`)** — per-function control-flow graphs (`BasicBlock` nodes + `CFG` edges) feeding the PDG/taint substrate, currently **TypeScript & JavaScript** (#2081 M1); other languages planned. Off by default.
-
 ---

 ## Tool Examples
@@ -726,20 +610,12 @@ UPSTREAM (what depends on this):
    authRouter [IMPORTS] -> src/routes/auth.ts
 ```

-Options: `maxDepth`, `minConfidence`, `relationTypes` (`CALLS`, `IMPORTS`, `EXTENDS`, `IMPLEMENTS`), `includeTests`, `limit` (max symbols per depth, default 100), `offset` (pagination start per depth), `summaryOnly` (counts and risk only, omits symbol list)
-
-**Disambiguation** — when several symbols share the target name, `impact` returns a ranked `ambiguous` candidate list instead of guessing. Narrow it with `target_uid` (exact, zero-ambiguity), `file_path`, or `kind` (`Function`, `Class`, `Method`, …). From the CLI these are `--uid`, `--file`, and `--kind`, matching `gitnexus context`:
-
-```bash
-gitnexus impact get_embeddings                       # → ambiguous: lists ranked candidates
-gitnexus impact get_embeddings --file src/embed.py   # → resolves to the one in that file
-gitnexus impact get_embeddings --uid "Function:src/embed.py:get_embeddings"  # exact
-```
+Options: `maxDepth`, `minConfidence`, `relationTypes` (`CALLS`, `IMPORTS`, `EXTENDS`, `IMPLEMENTS`), `includeTests`

 ### Process-Grouped Search

 ```
-query({search_query: "authentication middleware"})
+query({query: "authentication middleware"})

 processes:
  - summary: "LoginFlow"
@@ -839,14 +715,6 @@ gitnexus wiki --base-url https://api.anthropic.com/v1

 # Force full regeneration
 gitnexus wiki --force
-
-
-# Increase the timeout or retries for large codebase or slow LLM providers
-gitnexus wiki --timeout <seconds> # LLM request timeout in seconds (default: disabled)
-gitnexus wiki --retries <n>      # Max LLM retry attempts per request (default: 3)
-
-# Change the language generation for wiki
-gitnexus wiki --lang <lang>  # Output language for generated documentation (e.g. english, chinese, spanish, japanese)
 ```

 The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.
@@ -855,16 +723,16 @@ The wiki generator reads the indexed graph structure, groups files into modules

 ## Tech Stack

-| Layer               | CLI                                   | Web                                     |
-| ------------------- | ------------------------------------- | --------------------------------------- |
+| Layer                     | CLI                                   | Web                                     |
+| ------------------------- | ------------------------------------- | --------------------------------------- |
 | **Runtime**         | Node.js (native)                      | Browser (WASM)                          |
 | **Parsing**         | Tree-sitter native bindings           | Tree-sitter WASM                        |
-| **Database**        | LadybugDB native                      | LadybugDB WASM                          |
+| **Database**        | LadybugDB native                         | LadybugDB WASM                             |
 | **Embeddings**      | HuggingFace transformers.js (GPU/CPU) | transformers.js (WebGPU/WASM)           |
 | **Search**          | BM25 + semantic + RRF                 | BM25 + semantic + RRF                   |
 | **Agent Interface** | MCP (stdio)                           | LangChain ReAct agent                   |
-| **Visualization**   | —                                     | Sigma.js + Graphology (WebGL)           |
-| **Frontend**        | —                                     | React 18, TypeScript, Vite, Tailwind v4 |
+| **Visualization**   | —                                    | Sigma.js + Graphology (WebGL)           |
+| **Frontend**        | —                                    | React 18, TypeScript, Vite, Tailwind v4 |
 | **Clustering**      | Graphology                            | Graphology                              |
 | **Concurrency**     | Worker threads + async                | Web Workers + Comlink                   |

@@ -880,12 +748,12 @@ The wiki generator reads the indexed graph structure, groups files into modules

 ### Recently Completed

- [x] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping
- [x] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
- [x] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
- [x] Multi-Repo MCP, Zero-Config Setup, 14 Language Support
- [x] Community Detection, Process Detection, Confidence Scoring
- [x] Hybrid Search, Vector Index
+- [X] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping
+- [X] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
+- [X] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
+- [X] Multi-Repo MCP, Zero-Config Setup, 14 Language Support
+- [X] Community Detection, Process Detection, Confidence Scoring
+- [X] Hybrid Search, Vector Index

 ---

@@ -4,43 +4,38 @@ How we structure tests and which commands to run locally and in CI.

 ## Packages

-| Package        | Path            | Runner     | Notes                      |
-| -------------- | --------------- | ---------- | -------------------------- |
-| CLI + MCP core | `gitnexus/`     | Vitest     | Primary test surface in CI |
-| Web UI         | `gitnexus-web/` | Vitest     | Unit/component tests       |
-| Web UI E2E     | `gitnexus-web/` | Playwright | Run when changing UI flows |
+| Package        | Path           | Runner   | Notes                          |
+| -------------- | -------------- | -------- | ------------------------------ |
+| CLI + MCP core | `gitnexus/`    | Vitest   | Primary test surface in CI     |
+| Web UI         | `gitnexus-web/`| Vitest   | Unit/component tests           |
+| Web UI E2E     | `gitnexus-web/`| Playwright | Run when changing UI flows   |

-## Test lanes
+## Commands (local)

-### `gitnexus/` commands
+From repository root, unless noted:

-From `gitnexus/`:
-
-| Command                       | What it runs                                       | When to use                           |
-| ----------------------------- | -------------------------------------------------- | ------------------------------------- |
-| `npm test`                    | Full suite (all 3 vitest projects)                 | Before opening a PR                   |
-| `npm run test:unit`           | Unit tests only (`test/unit/`)                     | Tight development loop                |
-| `npm run test:integration`    | Integration tests (`test/integration/`)            | After changing pipelines, DB, workers |
-| `npm run test:coverage`       | Full suite + v8 coverage with thresholds           | Checking coverage impact              |
-| `npm run test:parity`         | Scope-resolution parity for all migrated languages | After changing resolver or scope code |
-| `npm run test:cross-platform` | Platform-sensitive subset only                     | Debugging a Windows/macOS issue       |
-| `npm run test:watch`          | Vitest in watch mode                               | Active development                    |
-
-### `gitnexus-web/` commands
-
-From `gitnexus-web/`:
-
-| Command                 | What it runs                  | When to use                                                         |
-| ----------------------- | ----------------------------- | ------------------------------------------------------------------- |
-| `npm test`              | Unit/component tests (vitest) | After changing web code                                             |
-| `npm run test:coverage` | Unit tests + coverage         | Checking coverage impact                                            |
-| `npm run test:e2e`      | Playwright browser tests      | After changing UI flows (requires `gitnexus serve` + `npm run dev`) |
-
-### Before opening a PR
+**`gitnexus` (CLI / library)**

 ```bash
-cd gitnexus && npx tsc --noEmit && npm test
-cd ../gitnexus-web && npx tsc -b --noEmit && npm test
+cd gitnexus
+npm install
+npm run build
+npm test                    # full suite: vitest run
+npm run test:unit           # unit only: vitest run test/unit
+npm run test:integration    # integration suite
+npm run test:coverage
+npx tsc --noEmit            # typecheck (matches CI)
+```
+
+**`gitnexus-web`**
+
+```bash
+cd gitnexus-web
+npm install
+npm test                    # unit tests (vitest)
+npx tsc -b --noEmit         # typecheck (matches CI)
+npm run test:coverage
+npm run test:e2e            # Playwright (requires gitnexus serve + npm run dev)
 ```

 ## Pre-commit hook
@@ -55,69 +50,22 @@ Tests do **not** run in the pre-commit hook — they run in CI (`ci-tests.yml`)

 Skip with `git commit --no-verify` (use sparingly).

-## Vitest projects
-
-`gitnexus/vitest.config.ts` defines three projects for safety isolation:
-
-| Project   | Files                                              | Parallelism | Purpose                                             |
-| --------- | -------------------------------------------------- | ----------- | --------------------------------------------------- |
-| `lbug-db` | Native LadybugDB integration tests (explicit list) | Sequential  | Prevents file-lock conflicts from native mmap addon |
-| `cli-e2e` | `skills-e2e.test.ts`                               | Sequential  | CLI process spawning requires serial execution      |
-| `default` | Everything else                                    | Parallel    | Fast execution for pure logic and parser tests      |
-
-When adding a new test that uses native LadybugDB (`@ladybugdb/core`), add it to the `lbug-db` project's explicit include list and the `default` project's exclude list.
-
 ## Test categories

 - **Unit** — Pure logic, parsers, graph/query helpers; fast; no network.
 - **Integration** — Real combinations (filesystem, MCP wiring, larger pipelines) as already organized under `gitnexus/test/integration`.
- **Resolver / parity** — Language-specific call-resolution tests in `test/integration/resolvers/`.
+- **Eval-style / golden sets** — For agent- or classification-style behavior, keep labeled inputs and expected outputs (JSON or table-driven tests) and run them in CI when relevant.
 - **E2E (web)** — Critical user paths only; prefer `data-testid` attributes for stable selectors. Tests run against real backend (`gitnexus serve`) and Vite dev server.

-## Scope-resolution tests
+## Performance metrics (targets)

-Every language resolves calls and inheritance through the scope-resolution pipeline — the legacy call-resolution DAG and the per-language `REGISTRY_PRIMARY_<LANG>` flag were removed in RING4-1 (#942). Each language's resolver test lives at `test/integration/resolvers/<slug>.test.ts` and runs once, on the single scope-resolution path, as part of the normal `tests` job (`vitest test/**/*.test.ts`).
+Set targets to match team expectations, then tune to this repo’s CI reality:

-Adding a language: register its `ScopeResolver` in `scope-resolution/pipeline/registry.ts` (`SCOPE_RESOLVERS`) and add the resolver test file — no workflow or config edit needed.
-
-## Cross-platform testing
-
-Windows and macOS CI runs only the platform-sensitive test subset (~50 files out of 373). The full suite runs on Ubuntu.
-
-The subset is defined in `gitnexus/scripts/cross-platform-tests.ts` and includes:
-
- **Platform-specific logic** — tests with `process.platform` guards, path.sep behavior, EPERM/EBUSY error classification
- **Native LadybugDB** — all `lbug-*` integration tests (N-API addon with known platform-varying behavior)
- **Process spawning / CLI** — tests using real `child_process.spawn`, shell quoting, CLI invocations
- **Worker threads** — tests spawning real `worker_threads`
- **Native addon loading** — tree-sitter grammar loading smoke tests
- **Filesystem behavior** — CRLF handling, directory walking, symlinks
-
-When adding a platform-sensitive test, add it to the appropriate section in `scripts/cross-platform-tests.ts`.
-
-### Confirming no tests are orphaned
-
-Every test file matches one of the three vitest projects. To verify:
-
-```bash
-cd gitnexus
-npx vitest list 2>/dev/null | wc -l  # should match total test count
-```
-
-To check the cross-platform list is up to date, run `npm run test:cross-platform` — it fails fast if any listed file is missing.
-
-## CI integration
-
-GitHub Actions (`.github/workflows/ci.yml`) orchestrate:
-
-| Workflow              | Jobs                                                              | Purpose                                                               |
-| --------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `ci-quality.yml`      | format, lint, typecheck, typecheck-web, workflow-convention       | Code quality gates                                                    |
-| `ci-tests.yml`        | ubuntu/coverage, cross-platform (Win/Mac), packaged-install-smoke | Full suite + coverage on Ubuntu; platform-sensitive subset on Win/Mac |
-| `ci-scope-parity.yml` | discover, parity                                                  | Scope-resolution parity for all migrated languages                    |
-| `ci-e2e.yml`          | e2e (chromium)                                                    | Playwright E2E, gated on `gitnexus-web/**` changes                    |
-
-The `CI Gate` job in `ci.yml` is the single required check for branch protection. It requires quality, tests, e2e, and scope-parity to all pass.
+| Metric              | Target (initial) | Notes                                      |
+| ------------------- | ---------------- | ------------------------------------------ |
+| Unit coverage       | Align with CI    | CI runs Vitest with coverage in `gitnexus` |
+| Unit wall time      | Fast PR feedback | Use `vitest run test/unit` for tight loop  |
+| Integration duration| &lt; few minutes | Guard heavy tests with env flags if needed |

 ## Regression testing

@@ -128,6 +76,23 @@ Re-run the full relevant suite when:
 - Graph schema, query contracts, or MCP tool shapes change
 - Dependencies with parsing or runtime impact upgrade

+## CI integration
+
+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-tests.yml`** — `vitest run` with coverage (ubuntu) + cross-platform (macOS, Windows)
+- **`ci-e2e.yml`** — Playwright E2E tests, gated on `gitnexus-web/**` changes
+
+Local checks before pushing:
+
+```bash
+cd gitnexus && npx tsc --noEmit && npm test
+cd ../gitnexus-web && npx tsc -b --noEmit && npm test
+```
+
+Or rely on the pre-commit hook which runs these automatically for staged files.
+
 ## User acceptance / beta (optional)

 For staged releases or UI betas: deploy to a staging environment, collect structured feedback, watch errors and latency, then iterate before a wider release.
@@ -30,12 +30,6 @@ services:
    container_name: ${WEB_CONTAINER_NAME:-gitnexus-web}
    ports:
      - '${WEB_HOST_PORT:-4173}:4173'
-    # Override the backend URL served to the browser. The default
-    # (http://localhost:4747) works when both containers run locally.
-    # Set GITNEXUS_BACKEND_URL in your .env or shell for remote/custom setups:
-    #   GITNEXUS_BACKEND_URL=http://<server-ip>:4747
-    environment:
-      - GITNEXUS_BACKEND_URL=${GITNEXUS_BACKEND_URL:-}
    depends_on:
      gitnexus-server:
        condition: service_healthy
@@ -1,39 +1,12 @@
-import { open } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { extname, isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+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');

-function isValidUrl(value) {
-  try {
-    const u = new URL(value);
-    return u.protocol === 'http:' || u.protocol === 'https:';
-  } catch {
-    return false;
-  }
-}
-
-function jsonForScriptTag(obj) {
-  return JSON.stringify(obj)
-    .replace(/</g, '\\u003c')
-    .replace(/>/g, '\\u003e')
-    .replace(/&/g, '\\u0026');
-}
-
-const rawBackendUrl = process.env.GITNEXUS_BACKEND_URL ?? null;
-if (rawBackendUrl && !isValidUrl(rawBackendUrl)) {
-  const safeRaw = rawBackendUrl.replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 200);
-  console.warn(
-    `[gitnexus-web] GITNEXUS_BACKEND_URL "${safeRaw}" is not a valid http/https URL -- ignoring.`,
-  );
-}
-const backendUrl = rawBackendUrl && isValidUrl(rawBackendUrl) ? rawBackendUrl : null;
-const configScript = backendUrl
-  ? `<script>window.__GITNEXUS_CONFIG__=${jsonForScriptTag({ backendUrl })};</script>`
-  : '';
-
 const contentTypes = {
  '.css': 'text/css; charset=utf-8',
  '.html': 'text/html; charset=utf-8',
@@ -49,22 +22,22 @@ const contentTypes = {

 // Static asset server for the gitnexus-web Docker image.
 //
-// TOCTOU prevention: every filesystem interaction uses open() to get a
-// file handle; subsequent reads use handle.readFile()/createReadStream().
+// 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:
 //
-// CodeQL js/file-system-race: the query pairs open() calls when their
-// path arguments are data-flow aliased. This handler uses exactly two
-// open() calls whose paths are provably independent:
-//   1. open(requestedPath) — derived from the URL
-//   2. open(spaFallback)   — the constant root/index.html
-// Because spaFallback has no data-flow from the request, CodeQL cannot
-// pair them as a check/use on the same path.
+//     const rel = relative(root, candidate);
+//     if (rel.startsWith('..') || isAbsolute(rel)) reject;
+//     // candidate is now proven inside `root`
 //
-// Path-injection containment: each open() is preceded by a
-// path.relative() barrier that CodeQL recognizes as a sanitizer.
-
-const spaFallback = resolve(root, 'index.html');
-
+// 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] || '/';

@@ -83,90 +56,62 @@ const server = createServer(async (req, res) => {
  }

  const cleanPath = normalize(decoded.replace(/^\/+/, ''));
-  const requestedPath = resolve(root, cleanPath);
+  const initialPath = resolve(root, cleanPath);

-  const rel = relative(root, requestedPath);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
+  // 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;
  }

-  let handle;
  try {
-    let servePath = requestedPath;
+    const initialStat = await stat(initialPath).catch(() => null);

-    // Try to open the exact path the client asked for.
-    handle = await open(requestedPath, 'r').catch(() => null);
-    if (handle) {
-      const s = await handle.stat();
-      if (!s.isFile()) {
-        // Directories and other non-files fall through to SPA fallback.
-        await handle.close();
-        handle = null;
-      }
-    }
-
-    // If the requested path wasn't a regular file, serve the SPA entry
-    // point. spaFallback is a module-level constant with no data-flow
-    // from the request, so this open() is independent of the one above.
-    if (!handle) {
-      servePath = spaFallback;
-      handle = await open(spaFallback, 'r').catch(() => null);
-      if (!handle) {
-        res.writeHead(404);
-        res.end('Not found');
-        return;
-      }
-      const s = await handle.stat();
-      if (!s.isFile()) {
-        res.writeHead(404);
-        res.end('Not found');
-        return;
-      }
-    }
-
-    const isHtml = extname(servePath) === '.html' || !extname(servePath);
-    const cacheControl = servePath.includes(`${sep}assets${sep}`)
-      ? 'public, max-age=31536000, immutable'
-      : 'no-cache';
-    const contentType = contentTypes[extname(servePath)] || 'application/octet-stream';
-
-    if (isHtml && configScript) {
-      const raw = await handle.readFile('utf8');
-      await handle.close();
-      handle = null;
-      if (!raw.includes('</head>')) {
-        console.warn('[gitnexus-web] Could not inject config: no </head> tag found in HTML');
-      }
-      const html = raw.includes('</head>') ? raw.replace('</head>', `${configScript}</head>`) : raw;
-      const buf = Buffer.from(html, 'utf8');
-      res.writeHead(200, {
-        'Cache-Control': cacheControl,
-        'Content-Type': 'text/html; charset=utf-8',
-        'Content-Length': buf.length,
-        'Cross-Origin-Opener-Policy': 'same-origin',
-        'Cross-Origin-Embedder-Policy': 'require-corp',
-      });
-      res.end(buf);
+    // 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 {
-      res.writeHead(200, {
-        'Cache-Control': cacheControl,
-        'Content-Type': contentType,
-        'Cross-Origin-Opener-Policy': 'same-origin',
-        'Cross-Origin-Embedder-Policy': 'require-corp',
-      });
-      const stream = handle.createReadStream();
-      handle = null;
-      stream.on('error', () => res.destroy());
-      stream.pipe(res);
+      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) {
-    console.error(error);
    res.writeHead(500);
-    res.end('Internal server error');
-  } finally {
-    if (handle) await handle.close().catch(() => {});
+    res.end(error instanceof Error ? error.message : 'Internal server error');
  }
 });

@@ -70,20 +70,8 @@ before(async () => {
  await waitForServer(serverPort);
 });

-function killAndWait(proc) {
-  return new Promise((resolve) => {
-    if (!proc || proc.exitCode !== null) {
-      resolve();
-      return;
-    }
-    proc.once('exit', resolve);
-    proc.kill();
-    if (proc.exitCode !== null) resolve();
-  });
-}
-
 after(async () => {
-  await killAndWait(child);
+  child?.kill();
  if (tmpDir) await rm(tmpDir, { recursive: true, force: true });
 });

@@ -134,132 +122,3 @@ it('returns 404 when dist/index.html is missing', async () => {
  const res = await rawGet(serverPort, '/nonexistent-page');
  assert.equal(res.status, 404);
 });
-
-// -- Config injection: server-level integration tests ---
-
-function spawnServerWithEnv(cwd, port, env) {
-  const proc = spawn(process.execPath, [serverScript], {
-    cwd,
-    env: { ...process.env, PORT: String(port), ...env },
-    stdio: 'pipe',
-  });
-  proc.on('error', (err) => {
-    throw err;
-  });
-  return proc;
-}
-
-async function withInjectionServer(envOverrides, fn) {
-  const dir = await mkdtemp(join(tmpdir(), 'gitnexus-inject-'));
-  const distDir = join(dir, 'dist');
-  const assetsDir = join(distDir, 'assets');
-  await mkdir(assetsDir, { recursive: true });
-  await writeFile(
-    join(distDir, 'index.html'),
-    '<!doctype html><html><head><meta charset="utf-8"></head><body>app</body></html>',
-  );
-  await writeFile(join(assetsDir, 'style.abc.css'), 'body{}');
-
-  const port = await getFreePort();
-  const proc = spawnServerWithEnv(dir, port, envOverrides);
-  try {
-    await waitForServer(port);
-    await fn(port);
-  } finally {
-    await killAndWait(proc);
-    await rm(dir, { recursive: true, force: true });
-  }
-}
-
-it('injects __GITNEXUS_CONFIG__ into / when GITNEXUS_BACKEND_URL is valid', async () => {
-  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'http://10.0.0.1:4747' }, async (port) => {
-    const res = await rawGet(port, '/');
-    assert.equal(res.status, 200);
-    assert.ok(
-      res.body.includes('window.__GITNEXUS_CONFIG__'),
-      'Expected __GITNEXUS_CONFIG__ in response body',
-    );
-    assert.ok(res.body.includes('http://10.0.0.1:4747'), 'Expected backend URL in response body');
-  });
-});
-
-it('injects __GITNEXUS_CONFIG__ into SPA fallback routes', async () => {
-  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'http://10.0.0.1:4747' }, async (port) => {
-    const res = await rawGet(port, '/some/deep/link');
-    assert.equal(res.status, 200);
-    assert.ok(
-      res.body.includes('window.__GITNEXUS_CONFIG__'),
-      'Expected __GITNEXUS_CONFIG__ in SPA fallback response',
-    );
-    assert.ok(
-      res.body.includes('http://10.0.0.1:4747'),
-      'Expected backend URL in SPA fallback response',
-    );
-  });
-});
-
-it('does not inject when GITNEXUS_BACKEND_URL is not set', async () => {
-  await withInjectionServer({}, async (port) => {
-    const res = await rawGet(port, '/');
-    assert.equal(res.status, 200);
-    assert.ok(
-      !res.body.includes('__GITNEXUS_CONFIG__'),
-      'Expected no __GITNEXUS_CONFIG__ when env var is unset',
-    );
-  });
-});
-
-it('does not inject when GITNEXUS_BACKEND_URL is invalid', async () => {
-  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'not-a-url' }, async (port) => {
-    const res = await rawGet(port, '/');
-    assert.equal(res.status, 200);
-    assert.ok(
-      !res.body.includes('__GITNEXUS_CONFIG__'),
-      'Expected no __GITNEXUS_CONFIG__ for invalid URL',
-    );
-  });
-});
-
-it('does not inject when GITNEXUS_BACKEND_URL uses a non-http protocol', async () => {
-  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'ftp://somehost:21' }, async (port) => {
-    const res = await rawGet(port, '/');
-    assert.equal(res.status, 200);
-    assert.ok(
-      !res.body.includes('__GITNEXUS_CONFIG__'),
-      'Expected no __GITNEXUS_CONFIG__ for non-http protocol',
-    );
-  });
-});
-
-it('escapes </script> in GITNEXUS_BACKEND_URL to prevent XSS', async () => {
-  const xssUrl = 'http://example.com/?x=</script><script>alert(1)</script>';
-  await withInjectionServer({ GITNEXUS_BACKEND_URL: xssUrl }, async (port) => {
-    const res = await rawGet(port, '/');
-    assert.equal(res.status, 200);
-
-    const scriptMatches = res.body.match(/<script>/gi) || [];
-    assert.equal(
-      scriptMatches.length,
-      1,
-      `Expected exactly 1 <script> tag but found ${scriptMatches.length}: XSS breakout detected`,
-    );
-
-    assert.ok(
-      !res.body.includes('</script><script>'),
-      '</script> must not appear unescaped -- would allow script breakout',
-    );
-    assert.ok(res.body.includes('\\u003c'), 'Angle brackets must be escaped as \\u003c');
-  });
-});
-
-it('does not inject config into static assets', async () => {
-  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'http://10.0.0.1:4747' }, async (port) => {
-    const res = await rawGet(port, '/assets/style.abc.css');
-    assert.equal(res.status, 200);
-    assert.ok(
-      !res.body.includes('__GITNEXUS_CONFIG__'),
-      'Static assets must not contain injected config',
-    );
-    assert.equal(res.body, 'body{}');
-  });
-});
@@ -0,0 +1,100 @@
+# COBOL Code Indexing
+
+GitNexus indexes COBOL codebases using a **regex-only extraction** strategy, bypassing tree-sitter entirely. This document explains why, how the pipeline works, and links to detailed sub-documents.
+
+## Why Regex-Only?
+
+The tree-sitter-cobol grammar (v0.0.1) has three critical limitations that make it unusable for production indexing:
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| External scanner hangs on ~5% of files | No timeout mechanism exists for the C scanner; the process blocks indefinitely | **Blocking** |
+| Only ~15% of paragraph headers detected | Most procedure-division paragraphs are invisible to the grammar | High |
+| Patch markers in cols 1-6 cause parse errors | Enterprise COBOL uses non-standard sequence area content (e.g., `mzADD`, `estero`, `#FIX`) | High |
+
+Because the external scanner hang cannot be interrupted (there is no `setTimeoutMicros` equivalent for tree-sitter), using tree-sitter-cobol would hang the indexing pipeline on a non-trivial fraction of real-world files.
+
+The regex-only approach provides:
+
+- **Speed**: ~1ms per file average extraction time
+- **Reliability**: zero hangs, zero crashes across 13,000+ files
+- **Coverage**: captures all critical symbols -- program name, paragraphs, sections, CALL, PERFORM, COPY, data items (01-77, 88-level), file declarations, FD entries, EXEC SQL/CICS blocks, ENTRY points, and MOVE statements
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A[Repository Scan] --> B{File Detection}
+    B -->|Extension match| C[COBOL file]
+    B -->|GITNEXUS_COBOL_DIRS match| C
+    B -->|No match| Z[Skip]
+
+    C --> D{Copybook?}
+    D -->|Yes| E[Add to Copybook Map]
+    D -->|No| F[Source Program]
+
+    E --> G[COPY Expansion Engine]
+    F --> G
+
+    G -->|Inline copybook content| H[Expanded Source]
+    H --> I[Patch Marker Cleanup]
+    I --> J[Regex State Machine]
+
+    J --> K[Extracted Symbols]
+    K --> L[Graph Model Builder]
+    L --> M[Knowledge Graph]
+
+    subgraph "Per-Chunk Processing"
+        G
+        H
+        I
+        J
+        K
+        L
+    end
+
+    subgraph "Post-Processing"
+        M --> N[Community Detection]
+        M --> O[Process Detection]
+        M --> P[Contract Detection]
+    end
+
+    style J fill:#e8f5e9,stroke:#2e7d32
+    style G fill:#e3f2fd,stroke:#1565c0
+```
+
+## COBOL vs Tree-Sitter Languages
+
+| Feature | COBOL (Regex) | Tree-Sitter Languages |
+|---------|--------------|----------------------|
+| Parser | Single-pass regex state machine | tree-sitter grammar + queries |
+| Speed | ~1ms/file | ~5ms/file |
+| AST available | No | Yes |
+| COPY expansion | Yes (pre-processing step) | N/A |
+| Deep indexing | Data items, SQL, CICS, FD, ENTRY | Type annotations, generics, etc. |
+| Call extraction | PERFORM (intra-file) + CALL (cross-program) | AST-based call site detection |
+| Import extraction | COPY statements | `import`/`require`/`use`/`#include` |
+| Coverage | All critical symbols | Language-dependent query coverage |
+| Failure mode | Never hangs | External scanner can hang (COBOL only) |
+
+## Sub-Documents
+
+| Document | Description |
+|----------|-------------|
+| [File Detection](./file-detection.md) | Extension mapping, `GITNEXUS_COBOL_DIRS`, copybook classification |
+| [COPY Expansion](./copy-expansion.md) | Copybook inlining, REPLACING transformations, cycle detection |
+| [Regex Extraction](./regex-extraction.md) | State machine, regex patterns, line processing |
+| [Deep Indexing](./deep-indexing.md) | Data items, EXEC SQL/CICS, file declarations, FD, ENTRY, MOVE |
+| [Graph Model](./graph-model.md) | COBOL-specific node types, edge types, full annotated example |
+| [Performance](./performance.md) | Benchmarks, worker pool tuning, caps, troubleshooting |
+
+## Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `gitnexus/src/core/ingestion/cobol-preprocessor.ts` | Patch marker cleanup + regex extraction engine |
+| `gitnexus/src/core/ingestion/cobol-copy-expander.ts` | COPY statement expansion with REPLACING |
+| `gitnexus/src/core/ingestion/utils.ts` | `getLanguageFromPath`, `getLanguageFromFilename` |
+| `gitnexus/src/core/ingestion/pipeline.ts` | `isCobolCopybook`, `expandCobolCopies`, `detectCrossProgamContracts` |
+| `gitnexus/src/core/ingestion/workers/parse-worker.ts` | `processCobolRegexOnly` -- graph model builder |
+| `gitnexus/src/core/ingestion/workers/worker-pool.ts` | Configurable sub-batch size for COBOL |
@@ -0,0 +1,157 @@
+# COBOL COPY Expansion
+
+The COPY statement is COBOL's include mechanism -- analogous to `#include` in C or `import` in modern languages. GitNexus expands COPY statements **before** regex extraction so that symbols defined inside copybooks (data items, paragraphs, etc.) are visible in the program's extracted graph.
+
+## Supported Syntax
+
+### Basic COPY
+
+```cobol
+COPY CPSESP.
+COPY "WORKGRID.CPY".
+```
+
+Inlines the content of the named copybook, replacing the COPY line(s).
+
+### COPY with REPLACING
+
+```cobol
+COPY CPSESP REPLACING "ANAZI-KEY" BY "LK-KEY".
+COPY CPSESP REPLACING LEADING "ESP-" BY "LK-ESP-"
+                       LEADING "KPSESPL" BY "LK-KPSESPL".
+COPY LINKAGE REPLACING TRAILING "-IN" BY "-OUT".
+```
+
+Three REPLACING types are supported:
+
+| Type         | Syntax                               | Behavior                                | Example                          |
+| ------------ | ------------------------------------ | --------------------------------------- | -------------------------------- |
+| **EXACT**    | `REPLACING "OLD" BY "NEW"`           | Replace exact identifier matches        | `ANAZI-KEY` becomes `LK-KEY`     |
+| **LEADING**  | `REPLACING LEADING "PFX-" BY "NEW-"` | Replace prefix on all COBOL identifiers | `ESP-NAME` becomes `LK-ESP-NAME` |
+| **TRAILING** | `REPLACING TRAILING "-IN" BY "-OUT"` | Replace suffix on all COBOL identifiers | `DATA-IN` becomes `DATA-OUT`     |
+
+Multiple REPLACING clauses can appear in a single COPY statement. They are applied in order to each COBOL identifier in the copybook content.
+
+### Multi-Line COPY
+
+COPY statements can span multiple lines (standard COBOL continuation rules apply):
+
+```cobol
+       COPY CPSESP REPLACING
+      -    LEADING "ESP-" BY "LK-ESP-"
+      -    LEADING "KPSESPL" BY "LK-KPSESPL".
+```
+
+Continuation lines (indicator `-` in column 7) are merged before COPY statement scanning.
+
+## Expansion Flow
+
+```mermaid
+sequenceDiagram
+    participant Pipeline
+    participant Expander as COPY Expander
+    participant Resolver
+    participant Reader
+
+    Pipeline->>Pipeline: Identify all COBOL files
+    Pipeline->>Pipeline: Classify copybooks vs programs
+    Pipeline->>Reader: Read all copybook content upfront
+    Reader-->>Pipeline: Copybook content map (name -> content)
+
+    loop For each source file in chunk
+        Pipeline->>Expander: expandCopies(content, filePath, resolveFile, readFile)
+        Expander->>Expander: Merge continuation lines
+        Expander->>Expander: Detect COPY statements via regex
+
+        loop For each COPY statement (reverse order)
+            Expander->>Resolver: resolveFile(copyTarget)
+            Resolver-->>Expander: Copybook key or null
+
+            alt Resolved successfully
+                Expander->>Reader: readFile(resolvedKey)
+                Reader-->>Expander: Copybook content
+
+                Expander->>Expander: Apply REPLACING transformations
+                Expander->>Expander: Recurse for nested COPYs (depth + 1)
+                Expander->>Expander: Splice expanded content into output
+            else Not resolved
+                Expander->>Expander: Keep original COPY line
+            end
+        end
+
+        Expander-->>Pipeline: Expanded content + resolution metadata
+        Pipeline->>Pipeline: Replace file content with expanded content
+    end
+```
+
+The return type `CopyExpansionResult` contains `expandedContent` and `copyResolutions`. The `expansionDepth` field has been removed from the return type (it was unused by callers).
+
+COPY statement line numbers in `CopyResolution` are 1-based (consistent with the preprocessor's line numbering). The splice operation that replaces COPY lines with expanded content adjusts for 0-based array indexing internally.
+
+## Cycle Detection
+
+Circular COPY references (e.g., copybook A includes copybook B which includes copybook A) are detected and handled:
+
+1. Each expansion chain maintains a `visited` set of resolved copybook paths
+2. If a copybook path is already in the visited set, the expansion is skipped
+3. A `warnedCircular` set (internal to `expandCopies()`, not a parameter) deduplicates warning messages within a single file expansion
+
+Known circular copybooks in PROJECT-NAME: `ANAZI`, `ANDIP`, `QDIPE` (self-referential includes).
+
+## Max Depth
+
+Nested COPY expansion is limited to **10 levels** (`DEFAULT_MAX_DEPTH`). If a COPY chain exceeds this depth, a warning is logged and the remaining COPY statements are left unexpanded.
+
+## Max Total Expansions
+
+A breadth amplification guard caps the total number of COPY expansions across all branches within a single file to **500** (`MAX_TOTAL_EXPANSIONS`). This prevents exponential blowup from diamond-shaped COPY graphs where N copybooks each include N other copybooks. Once the limit is reached, further COPY statements in that file are left unexpanded and a single warning is logged.
+
+## REPLACING Application Detail
+
+The REPLACING engine works by scanning all COBOL identifiers (matching `\b[A-Z][A-Z0-9-]*\b`) in the copybook content and applying each replacement rule:
+
+```
+Original copybook content:
+       05  ESP-NAME          PIC X(30).
+       05  ESP-CODE          PIC X(10).
+       05  KPSESPL-FLAG      PIC X(01).
+
+After REPLACING LEADING "ESP-" BY "LK-ESP-" LEADING "KPSESPL" BY "LK-KPSESPL":
+       05  LK-ESP-NAME       PIC X(30).
+       05  LK-ESP-CODE       PIC X(10).
+       05  LK-KPSESPL-FLAG   PIC X(01).
+```
+
+For LEADING replacements, the engine checks if each identifier starts with the `from` prefix (case-insensitive) and replaces only the prefix portion, preserving the rest of the identifier.
+
+For TRAILING replacements, the same logic applies to suffixes.
+
+For EXACT replacements, only identifiers that match the `from` value exactly (case-insensitive) are replaced.
+
+## Copybook Resolution
+
+The resolver tries multiple strategies to match a COPY target name to a copybook file:
+
+1. **Exact match**: `COPY CPSESP` resolves to copybook named `CPSESP`
+2. **Strip extension**: `COPY WORKGRID.CPY` strips `.CPY` and resolves to `WORKGRID`
+3. **Add extension**: `COPY CPSESP` tries `CPSESP.CPY` and `CPSESP.COPY`
+
+If no match is found, the COPY statement is left in place (unexpanded) and a resolution record with `resolvedPath: null` is created.
+
+## Pipeline Integration
+
+The expansion runs **per chunk**, after file content is read but before dispatch to worker threads:
+
+1. All copybook files are read upfront (they are typically small, collectively under 100MB)
+2. Per chunk, the copybook map is merged with chunk content (in case a chunk contains copybooks)
+3. Only programs (not copybooks themselves) undergo expansion
+4. The expanded content replaces the original content in-place before worker dispatch
+
+## Inline Comment Handling
+
+The copy expander's `stripInlineComment()` helper is quote-aware: pipe characters (`|`) inside single- or double-quoted strings are preserved. This matches the same quote-aware logic used by the preprocessor.
+
+## Source Files
+
+- `gitnexus/src/core/ingestion/cobol-copy-expander.ts` -- `expandCopies()`, `parseReplacingClause()`, `applyReplacing()`
+- `gitnexus/src/core/ingestion/pipeline.ts` -- `expandCobolCopies()`, copybook map construction, chunk integration
@@ -0,0 +1,312 @@
+# COBOL Deep Indexing
+
+Beyond basic symbol extraction (program name, paragraphs, CALL, PERFORM, COPY), GitNexus performs deep indexing of COBOL-specific constructs: data items, EXEC SQL/CICS blocks, file declarations, FD entries, ENTRY points, and MOVE statements.
+
+## Data Items
+
+### Level Numbers
+
+| Level Range | Meaning | Graph Node Type |
+|-------------|---------|-----------------|
+| 01 | Record (group item) | `Record` |
+| 02-49 | Elementary/group items | `Property` |
+| 66 | RENAMES | `Property` |
+| 77 | Independent item | `Property` |
+| 88 | Condition name | `Const` |
+
+FILLER items are skipped (no useful name for the graph).
+
+### Clauses Parsed
+
+The `parseDataItemClauses()` function extracts these clauses from the trailing text of a data item declaration:
+
+| Clause | Pattern | Example |
+|--------|---------|---------|
+| `PIC` / `PICTURE` | `\bPIC(?:TURE)?\s+(?:IS\s+)?(\S+)` | `PIC X(30)`, `PICTURE IS 9(5)V99` |
+| `USAGE` | `\bUSAGE\s+(?:IS\s+)?(COMP\|BINARY\|...)` | `USAGE IS COMP-3`, `BINARY` |
+| `REDEFINES` | `\bREDEFINES\s+([A-Z][A-Z0-9-]+)` | `REDEFINES WK-DATE-NUM` |
+| `OCCURS` | `\bOCCURS\s+(\d+)` | `OCCURS 12 TIMES` |
+
+Standalone COMP variants (without the `USAGE` keyword) are also detected: `COMP`, `COMP-1` through `COMP-6`, `COMP-X`, `BINARY`, `PACKED-DECIMAL`.
+
+### Data Hierarchy
+
+Data items form a hierarchical structure based on level numbers. The extractor uses a **stack algorithm**:
+
+```
+Processing order:
+  01 WK-RECORD          -> push {01, WK-RECORD}   -> parent: Module
+  05 WK-NAME            -> push {05, WK-NAME}     -> parent: WK-RECORD (01 < 05)
+  10 WK-FIRST           -> push {10, WK-FIRST}    -> parent: WK-NAME (05 < 10)
+  10 WK-LAST            -> pop WK-FIRST, push      -> parent: WK-NAME (05 < 10)
+  05 WK-CODE            -> pop WK-LAST, WK-NAME    -> parent: WK-RECORD (01 < 05)
+  88 WK-ACTIVE          -> (88 handled separately)  -> parent: WK-CODE
+```
+
+The stack maintains items where each entry's level is strictly less than the next. When a new item arrives with a level <= the top of stack, items are popped until the stack top has a smaller level. A `CONTAINS` edge is created from the stack top to the new item.
+
+For 88-level condition names, the parent is the immediately preceding non-88 data item (found by scanning backwards).
+
+### Annotated Example
+
+```cobol
+       01  WK-EMPLOYEE.
+           05  WK-EMP-ID          PIC 9(6).
+           05  WK-EMP-NAME        PIC X(30).
+           05  WK-EMP-STATUS      PIC X(01).
+               88  WK-ACTIVE      VALUE "A".
+               88  WK-INACTIVE    VALUE "I".
+           05  WK-SALARY          PIC 9(7)V99 COMP-3.
+           05  WK-DEPT            PIC X(04) OCCURS 3 TIMES.
+```
+
+Produces:
+- `Record` node: `WK-EMPLOYEE` (level 01, section: working-storage)
+- `Property` nodes: `WK-EMP-ID`, `WK-EMP-NAME`, `WK-EMP-STATUS`, `WK-SALARY`, `WK-DEPT`
+- `Const` nodes: `WK-ACTIVE` (values: `A`), `WK-INACTIVE` (values: `I`)
+- `CONTAINS` edges: `WK-EMPLOYEE -> WK-EMP-ID`, `WK-EMPLOYEE -> WK-EMP-NAME`, etc.
+- `CONTAINS` edges: `WK-EMP-STATUS -> WK-ACTIVE`, `WK-EMP-STATUS -> WK-INACTIVE`
+
+### Data Item Cap
+
+A maximum of **500 data items per file** (`MAX_DATA_ITEMS_PER_FILE`) are processed. Some COBOL programs (especially after COPY expansion) can have 10,000+ data items, which would cause graph bloat and push the V8 relationship Map past its 16.7M entry limit across thousands of files.
+
+The cap applies after extraction: the first 500 items in source order are kept. Since 01-level records appear first, critical top-level structure is preserved.
+
+## EXEC SQL
+
+EXEC SQL blocks are accumulated across lines between `EXEC SQL` and `END-EXEC`, then parsed as a unit.
+
+### Operation Classification
+
+The first SQL keyword determines the operation:
+
+| First Keyword | Operation |
+|---------------|-----------|
+| `SELECT` | SELECT |
+| `INSERT` | INSERT |
+| `UPDATE` | UPDATE |
+| `DELETE` | DELETE |
+| `DECLARE` | DECLARE |
+| `OPEN` | OPEN |
+| `CLOSE` | CLOSE |
+| `FETCH` | FETCH |
+| *(anything else)* | OTHER |
+
+### Table Extraction
+
+Tables are extracted from SQL clauses:
+
+| Clause Pattern | Example |
+|----------------|---------|
+| `FROM <table>` | `SELECT * FROM EMPLOYEES` |
+| `INSERT INTO <table>` | `INSERT INTO EMPLOYEES` |
+| `UPDATE <table>` | `UPDATE EMPLOYEES SET ...` |
+| `JOIN <table>` | `LEFT JOIN DEPARTMENTS ON ...` |
+
+Note: The `INTO` pattern is restricted to `INSERT INTO` to avoid false positives from `FETCH ... INTO :host-var` and `SELECT ... INTO :host-var` statements, where `INTO` introduces host variables rather than table names.
+
+### Cursor Detection
+
+```cobol
+           EXEC SQL
+               DECLARE C-EMPLOYEES CURSOR FOR
+               SELECT EMP-ID, EMP-NAME FROM EMPLOYEES
+               WHERE DEPT = :WK-DEPT
+           END-EXEC
+```
+
+Extracts: cursor `C-EMPLOYEES`, table `EMPLOYEES`, host variable `WK-DEPT`.
+
+### Host Variables
+
+Host variables are COBOL variables referenced in SQL with a `:` prefix. The colon is stripped:
+
+```sql
+WHERE EMP-ID = :WK-EMP-ID AND DEPT = :WK-DEPT
+```
+
+Extracts: `WK-EMP-ID`, `WK-DEPT`.
+
+### Graph Output
+
+- `CodeElement` node per table, with description `sql-table op:{OP}`
+- `CodeElement` node per cursor, with description `sql-cursor`
+- `ACCESSES` edge from Module to each CodeElement
+- Deduplication: if the same table appears in multiple SQL blocks, only one node is created
+
+## EXEC CICS
+
+EXEC CICS blocks are accumulated and parsed similarly to SQL blocks.
+
+### Command Detection
+
+Two-word commands are detected first (matched against the block start):
+
+```
+SEND MAP, RECEIVE MAP, SEND TEXT, SEND CONTROL, READ NEXT, READ PREV
+```
+
+If no two-word command matches, the first word is used (e.g., `LINK`, `XCTL`, `RETURN`, `READ`, `WRITE`).
+
+### Extraction
+
+| Element | Pattern | Example |
+|---------|---------|---------|
+| MAP name | `MAP('name')` or `MAP("name")` | `EXEC CICS SEND MAP('EMPMENU')` |
+| PROGRAM name | `PROGRAM('name')` or `PROGRAM("name")` | `EXEC CICS LINK PROGRAM('BGTABUP')` |
+| TRANSID | `TRANSID('name')` or `TRANSID("name")` | `EXEC CICS START TRANSID('EMP1')` |
+
+### Graph Output
+
+- MAP: `CodeElement` node with description `cics-map cmd:{CMD}` + `ACCESSES` edge from Module
+- PROGRAM: `CALLS` edge (cross-program call via CICS LINK/XCTL)
+- TRANSID: `CodeElement` node with description `cics-transid cmd:{CMD}` + `ACCESSES` edge from Module
+
+### Annotated Example
+
+```cobol
+           EXEC CICS
+               SEND MAP('EMPMENU')
+               MAPSET('EMPSET')
+               FROM(WK-MAP-DATA)
+               ERASE
+           END-EXEC
+```
+
+Produces:
+- `CodeElement` node: `EMPMENU` (description: `cics-map cmd:SEND MAP`)
+- `ACCESSES` edge: Module -> `EMPMENU`
+
+## File Declarations
+
+SELECT statements in the INPUT-OUTPUT SECTION are accumulated across multiple lines (until a period terminator) and parsed for:
+
+| Clause | Pattern | Example |
+|--------|---------|---------|
+| SELECT | `SELECT <name>` | `SELECT MASTER-FILE` |
+| ASSIGN | `ASSIGN TO <file>` | `ASSIGN TO "MASTER.DAT"` |
+| ORGANIZATION | `ORGANIZATION IS <type>` | `ORGANIZATION IS INDEXED` |
+| ACCESS | `ACCESS MODE IS <mode>` | `ACCESS MODE IS DYNAMIC` |
+| RECORD KEY | `RECORD KEY IS <field>` | `RECORD KEY IS WK-EMP-ID` |
+| FILE STATUS | `FILE STATUS IS <field>` | `FILE STATUS IS WK-FILE-STATUS` |
+
+### Graph Output
+
+- `CodeElement` node with description containing all parsed clauses (e.g., `select org:INDEXED access:DYNAMIC key:WK-EMP-ID status:WK-FILE-STATUS assign:MASTER.DAT`)
+- `RECORD_KEY_OF` edge: from Property node to CodeElement (confidence 0.8)
+- `FILE_STATUS_OF` edge: from Property node to CodeElement (confidence 0.8)
+
+## FD Entries
+
+FD (File Description) entries associate a file name with its record layout:
+
+```cobol
+       FD  MASTER-FILE.
+       01  MASTER-RECORD.
+           05  MR-EMP-ID       PIC 9(6).
+           05  MR-EMP-NAME     PIC X(30).
+```
+
+The extractor tracks `pendingFdName` state: when an `FD` line is seen, the next 01-level data item becomes its record.
+
+### Graph Output
+
+- `CodeElement` node with description `fd record:{recordName}`
+- `CONTAINS` edge: FD CodeElement -> Record node
+- `CONTAINS` edge: SELECT CodeElement -> FD CodeElement (linking file declaration to file description)
+
+## ENTRY Points
+
+The `ENTRY` statement defines additional entry points into a COBOL program (in addition to the main program entry):
+
+```cobol
+       ENTRY "SUBPROG" USING WK-PARAM-1 WK-PARAM-2.
+```
+
+### Graph Output
+
+- `Constructor` node with description `entry params:{param1},{param2}` (or just `entry` if no parameters)
+- `CONTAINS` edge: Module -> Constructor
+- Symbol table entry (so the entry point is discoverable by name)
+
+## PROCEDURE DIVISION USING
+
+```cobol
+       PROCEDURE DIVISION USING WK-INPUT-REC WK-OUTPUT-REC.
+```
+
+The USING clause identifies parameters received by the program from its caller.
+
+### Graph Output
+
+- `RECEIVES` edge: Module -> Property (for each parameter name, confidence 0.8)
+
+## MOVE Statements
+
+MOVE statements produce `ACCESSES` edges in the graph:
+
+```cobol
+       MOVE WK-NAME TO OUT-NAME.
+       MOVE CORRESPONDING WK-INPUT TO WK-OUTPUT.
+       MOVE CORR WK-IN TO WK-OUT.
+```
+
+### Extraction Details
+
+- Source and target identifiers are captured
+- `CORRESPONDING` and its abbreviation `CORR` are both recognized (bulk field-by-field move)
+- Figurative constants (SPACES, ZEROS, LOW-VALUES, HIGH-VALUES, QUOTES, ALL) are skipped
+- The enclosing paragraph (`caller`) is tracked for context
+
+### MOVE CORRESPONDING / CORR Edge Reasons
+
+MOVE CORRESPONDING (and CORR) produces distinct edge reasons to differentiate from simple MOVE:
+
+| Edge | Reason (simple MOVE) | Reason (CORRESPONDING/CORR) |
+|------|---------------------|-----------------------------|
+| Read (source) | `cobol-move-read` | `cobol-move-corresponding-read` |
+| Write (target) | `cobol-move-write` | `cobol-move-corresponding-write` |
+
+This distinction allows queries to find bulk field-by-field moves separately from simple variable assignments.
+
+## GO TO DEPENDING ON
+
+The `GO TO` statement with multiple targets and a `DEPENDING ON` clause is a computed branch:
+
+```cobol
+       GO TO PARA-1 PARA-2 PARA-3
+           DEPENDING ON WK-SELECTOR.
+```
+
+All target paragraph names are extracted and emitted as separate `gotos` entries. Each target produces a `CALLS` edge in the graph (same semantics as PERFORM). The `DEPENDING ON` variable is not currently tracked as a data-flow dependency.
+
+## SORT INPUT/OUTPUT PROCEDURE
+
+SORT and MERGE statements can specify procedural entry points instead of file-based I/O:
+
+```cobol
+       SORT SORT-FILE ON ASCENDING KEY SORT-KEY
+           INPUT PROCEDURE IS PREPARE-INPUT
+           OUTPUT PROCEDURE IS FORMAT-OUTPUT.
+```
+
+`INPUT PROCEDURE IS` and `OUTPUT PROCEDURE IS` targets are extracted as control-flow targets (same as PERFORM). They produce `performs` entries and corresponding `CALLS` edges in the graph.
+
+## Fixed-Format Literal Continuation
+
+In fixed-format COBOL, string literals can span multiple lines using the continuation indicator (`-` in column 7). When a continuation line starts with a quote character, the extractor joins it with the predecessor by removing the trailing quote from the previous line and the opening quote from the continuation:
+
+```
+Line N:          MOVE "THIS IS A LONG STRI
+Line N+1 (cont): -    "NG VALUE" TO WK-FIELD.
+Merged:          MOVE "THIS IS A LONG STRING VALUE" TO WK-FIELD.
+```
+
+The trailing `"` on line N and the opening `"` on line N+1 are both removed, producing a seamless literal. If no matching quote is found on the predecessor line, the continuation is appended as-is.
+
+## Source Files
+
+- `gitnexus/src/core/ingestion/cobol-preprocessor.ts` -- All extraction logic, clause parsers, EXEC block parsers
+- `gitnexus/src/core/ingestion/workers/parse-worker.ts` -- `processCobolRegexOnly()`, graph node/edge emission
+- `gitnexus/src/core/ingestion/parsing-processor.ts` -- Sequential fallback with same `MAX_DATA_ITEMS_PER_FILE` cap
@@ -0,0 +1,126 @@
+# COBOL File Detection
+
+GitNexus detects COBOL files through two mechanisms: extension-based mapping and directory-based override for extensionless files. This document covers both, plus the copybook/program classification logic.
+
+## Extension Mapping
+
+### Program Extensions
+
+| Extension | Type |
+|-----------|------|
+| `.cbl` | COBOL program |
+| `.cob` | COBOL program |
+| `.cobol` | COBOL program |
+
+### Copybook Extensions
+
+| Extension | Type | Notes |
+|-----------|------|-------|
+| `.cpy` | Copybook | Standard |
+| `.copy` | Copybook | Standard |
+| `.gnm` / `.GNM` | Copybook | Enterprise (GnuCOBOL naming) |
+| `.fd` / `.FD` | Copybook | File Description fragment |
+| `.wrk` / `.WRK` | Copybook | Working-Storage fragment |
+| `.sel` / `.SEL` | Copybook | SELECT clause fragment |
+| `.open` / `.OPEN` | Copybook | File OPEN fragment |
+| `.close` / `.CLOSE` | Copybook | File CLOSE fragment |
+| `.ini` / `.INI` | Copybook | Initialization fragment |
+| `.def` / `.DEF` | Copybook | Definition fragment |
+
+All extension matching is case-sensitive in `getLanguageFromFilename` (the extensions above are matched as written, including uppercase variants like `.GNM`).
+
+## Extensionless File Detection: `GITNEXUS_COBOL_DIRS`
+
+Many enterprise COBOL repositories use extensionless files -- the filename alone identifies the program (e.g., `s/BGTABFL` is the source for program `BGTABFL`). GitNexus handles this via the `GITNEXUS_COBOL_DIRS` environment variable.
+
+### Configuration
+
+Set `GITNEXUS_COBOL_DIRS` to a comma-separated list of directory names:
+
+```bash
+# Files in s/, c/, and wfproc/ directories (at any depth) are treated as COBOL
+export GITNEXUS_COBOL_DIRS=s,c,wfproc
+```
+
+The matching is **case-insensitive** and checks all path segments:
+
+- `/repo/s/BGTABFL` -- matches segment `s` -- COBOL
+- `/repo/src/c/CPSESP` -- matches segment `c` -- COBOL
+- `/repo/wfproc/WF001` -- matches segment `wfproc` -- COBOL
+- `/repo/docs/README` -- no matching segment -- skipped
+
+### Decision Tree
+
+```mermaid
+flowchart TD
+    A[getLanguageFromPath] --> B[getLanguageFromFilename]
+    B --> C{Known extension?}
+    C -->|Yes .cbl/.cob/.cobol/.cpy/...| D[Return COBOL]
+    C -->|Yes .ts/.py/.java/...| E[Return other language]
+    C -->|No match| F{Has extension?}
+
+    F -->|"Has dot in basename"| G[Return null]
+    F -->|"No dot = extensionless"| H{GITNEXUS_COBOL_DIRS set?}
+
+    H -->|No| G
+    H -->|Yes| I{Any path segment<br/>matches a configured dir?}
+
+    I -->|Yes| D
+    I -->|No| G
+
+    style D fill:#e8f5e9,stroke:#2e7d32
+    style G fill:#ffebee,stroke:#c62828
+```
+
+### Implementation Detail
+
+The `GITNEXUS_COBOL_DIRS` value is parsed once (on first call) and cached in a `Set<string>`:
+
+```typescript
+// From gitnexus/src/core/ingestion/utils.ts
+const getCobolDirs = (): Set<string> => {
+  if (_cobolDirs) return _cobolDirs;
+  const raw = process.env.GITNEXUS_COBOL_DIRS;
+  _cobolDirs = raw
+    ? new Set(raw.split(',').map(d => d.trim().toLowerCase()))
+    : new Set();
+  return _cobolDirs;
+};
+```
+
+The path segment check splits the full path on `/` and tests each segment against the cached set.
+
+## Copybook vs Program Classification
+
+After a file is identified as COBOL, it must be classified as either a **program** (to be parsed for symbols) or a **copybook** (to be loaded into the copybook map for COPY expansion).
+
+### Classification Rules
+
+A COBOL file is classified as a **copybook** if ANY of these conditions is true:
+
+1. It has a recognized copybook extension (`.cpy`, `.copy`, `.gnm`, `.fd`, `.wrk`, `.sel`, `.open`, `.close`, `.ini`, `.def`)
+2. It is an extensionless file whose path contains a directory segment matching one of: `c`, `copy`, `copybooks`, `copylib`, `cpy`
+
+A file is classified as a **program** if:
+
+1. It has a program extension (`.cbl`, `.cob`, `.cobol`), OR
+2. It is extensionless and does NOT match any copybook directory pattern
+
+### Copybook Name Resolution
+
+Copybook names are derived from the filename:
+
+- Strip the extension (if any)
+- Convert to uppercase
+
+Examples:
+- `c/CPSESP` -- name: `CPSESP`
+- `copy/workgrid.cpy` -- name: `WORKGRID`
+- `c/ANAZI.GNM` -- name: `ANAZI`
+
+This name is used to resolve `COPY CPSESP.` statements during expansion.
+
+## Source Files
+
+- `gitnexus/src/core/ingestion/utils.ts` -- `getLanguageFromPath()`, `getLanguageFromFilename()`, `getCobolDirs()`
+- `gitnexus/src/core/ingestion/pipeline.ts` -- `isCobolCopybook()`, `getCopybookName()`, `COPYBOOK_EXTENSIONS`, `COBOL_PROGRAM_EXTENSIONS`
@@ -0,0 +1,193 @@
+# COBOL Graph Model
+
+This document describes the graph nodes and edges that GitNexus creates for COBOL codebases. The COBOL graph model is richer than most tree-sitter languages because it captures domain-specific constructs: file declarations, FD entries, data hierarchies, SQL tables, CICS maps, and cross-program contracts.
+
+## Entity-Relationship Diagram
+
+```mermaid
+erDiagram
+    File ||--o{ Module : DEFINES
+    File ||--o{ Function : DEFINES
+    File ||--o{ Namespace : DEFINES
+    File ||--o{ Record : DEFINES
+    File ||--o{ Property : DEFINES
+    File ||--o{ Const : DEFINES
+    File ||--o{ CodeElement : DEFINES
+    File ||--o{ Constructor : DEFINES
+    File }o--o{ File : IMPORTS
+
+    Module ||--o{ Record : CONTAINS
+    Module ||--o{ Constructor : CONTAINS
+    Module }o--o{ CodeElement : ACCESSES
+    Module }o--o{ Module : CALLS
+    Module }o--o{ Module : CONTRACTS
+    Module }o--o{ Property : RECEIVES
+
+    Record ||--o{ Property : CONTAINS
+    Record ||--o{ Const : CONTAINS
+    Record }o--o{ Record : REDEFINES
+
+    Property ||--o{ Property : CONTAINS
+    Property ||--o{ Const : CONTAINS
+    Property }o--o{ Property : REDEFINES
+    Property }o--o{ CodeElement : RECORD_KEY_OF
+    Property }o--o{ CodeElement : FILE_STATUS_OF
+
+    CodeElement ||--o{ CodeElement : CONTAINS
+    CodeElement ||--o{ Record : CONTAINS
+
+    Function }o--o{ Function : CALLS
+```
+
+## Node Types
+
+| Node Type | COBOL Concept | Created From | Example |
+|-----------|--------------|--------------|---------|
+| `Module` | PROGRAM-ID | `PROGRAM-ID. BGTABFL` | Name: `BGTABFL`, description may include author and date |
+| `Function` | Paragraph | `PROCESS-RECORD.` at column 8 | Name: `PROCESS-RECORD` |
+| `Namespace` | Procedure section | `MAIN-LOGIC SECTION.` at column 8 | Name: `MAIN-LOGIC` |
+| `Record` | 01-level data item | `01 WK-EMPLOYEE.` | Description: `level:01 section:working-storage` |
+| `Property` | 02-49/66/77 data item | `05 WK-NAME PIC X(30).` | Description: `level:05 pic:X(30) section:working-storage` |
+| `Const` | 88-level condition | `88 WK-ACTIVE VALUE "A".` | Description: `level:88 values:A` |
+| `CodeElement` | SELECT, FD, SQL table, CICS map, cursor, transid | Various | Description varies by subtype |
+| `Constructor` | ENTRY point | `ENTRY "SUBPROG" USING WK-DATA` | Description: `entry params:WK-DATA` |
+
+### CodeElement Subtypes
+
+CodeElement is used for multiple COBOL constructs, distinguished by their description prefix:
+
+| Subtype | ID Pattern | Description Format | Example |
+|---------|-----------|-------------------|---------|
+| File SELECT | `CodeElement:{path}:SELECT:{name}` | `select org:INDEXED access:DYNAMIC ...` | `SELECT MASTER-FILE` |
+| FD entry | `CodeElement:{path}:FD:{name}` | `fd record:{recordName}` | `FD MASTER-FILE` |
+| SQL table | `CodeElement:{path}:sql-table:{name}` | `sql-table op:SELECT` | Table `EMPLOYEES` |
+| SQL cursor | `CodeElement:{path}:sql-cursor:{name}` | `sql-cursor` | Cursor `C-EMPLOYEES` |
+| CICS map | `CodeElement:{path}:cics-map:{name}` | `cics-map cmd:SEND MAP` | Map `EMPMENU` |
+| CICS transid | `CodeElement:{path}:cics-transid:{name}` | `cics-transid cmd:START` | Transid `EMP1` |
+
+## Edge Types
+
+| Edge Type | Source | Target | Created By | Confidence | Example |
+|-----------|--------|--------|-----------|------------|---------|
+| `DEFINES` | File | any node | File defines its symbols | 1.0 | File -> Module `BGTABFL` |
+| `CALLS` | Function | Function | `PERFORM X [THRU Y]` | (via call-processor) | `PROCESS-RECORD` -> `CALC-TAX` |
+| `CALLS` | Module | Module | `CALL "BGTABUP"` | (via call-processor) | `BGTABFL` -> `BGTABUP` |
+| `CALLS` | Module | Module | `EXEC CICS LINK PROGRAM('X')` | (via call-processor) | `BGTABFL` -> `BGTABUP` |
+| `IMPORTS` | File | File | `COPY copybook` | (via import-processor) | Source file -> Copybook file |
+| `CONTAINS` | Module | Record | Data hierarchy root | 1.0 | `BGTABFL` -> `WK-EMPLOYEE` |
+| `CONTAINS` | Record | Property | Data hierarchy | 1.0 | `WK-EMPLOYEE` -> `WK-NAME` |
+| `CONTAINS` | Property | Property | Nested data items | 1.0 | `WK-ADDRESS` -> `WK-CITY` |
+| `CONTAINS` | Record/Property | Const | 88-level parent | 1.0 | `WK-STATUS` -> `WK-ACTIVE` |
+| `CONTAINS` | CodeElement (FD) | Record | FD record link | 1.0 | `FD:MASTER-FILE` -> `MASTER-RECORD` |
+| `CONTAINS` | CodeElement (SELECT) | CodeElement (FD) | SELECT-FD link | 0.9 | `SELECT:MASTER-FILE` -> `FD:MASTER-FILE` |
+| `CONTAINS` | Module | Constructor | ENTRY in module | 1.0 | `BGTABFL` -> `SUBPROG` |
+| `REDEFINES` | Record | Record | `01 X REDEFINES Y` | 1.0 | `WK-DATE-NUM` -> `WK-DATE-ALPHA` |
+| `REDEFINES` | Property | Property | `05 X REDEFINES Y` | 1.0 | `WK-CODE-NUM` -> `WK-CODE-ALPHA` |
+| `RECORD_KEY_OF` | Property | CodeElement (SELECT) | `RECORD KEY IS field` | 0.8 | `WK-EMP-ID` -> `SELECT:MASTER-FILE` |
+| `FILE_STATUS_OF` | Property | CodeElement (SELECT) | `FILE STATUS IS field` | 0.8 | `WK-FS` -> `SELECT:MASTER-FILE` |
+| `ACCESSES` | Module | CodeElement | EXEC SQL/CICS | 0.9 | `BGTABFL` -> `sql-table:EMPLOYEES` |
+| `RECEIVES` | Module | Property | `PROCEDURE USING` | 0.8 | `BGTABFL` -> `WK-INPUT-REC` |
+| `CONTRACTS` | Module | Module | Shared copybook detection | 0.9 | `BGTABFL` -> `BGTABUP` (via `CPSESP`) |
+
+## Full Annotated Example
+
+Given this COBOL program:
+
+```cobol
+       IDENTIFICATION DIVISION.
+       PROGRAM-ID. EMPMAINT.
+       AUTHOR. Development Team.
+
+       ENVIRONMENT DIVISION.
+       INPUT-OUTPUT SECTION.
+       FILE-CONTROL.
+           SELECT EMP-FILE
+               ASSIGN TO "EMPLOYEE.DAT"
+               ORGANIZATION IS INDEXED
+               ACCESS MODE IS DYNAMIC
+               RECORD KEY IS EMP-ID
+               FILE STATUS IS WS-FILE-STATUS.
+
+       DATA DIVISION.
+       FILE SECTION.
+       FD  EMP-FILE.
+       01  EMP-RECORD.
+           05  EMP-ID             PIC 9(6).
+           05  EMP-NAME           PIC X(30).
+
+       WORKING-STORAGE SECTION.
+       01  WS-FLAGS.
+           05  WS-FILE-STATUS     PIC X(02).
+           05  WS-EOF-FLAG        PIC X(01).
+               88  WS-EOF         VALUE "Y".
+
+       LINKAGE SECTION.
+       01  LK-SEARCH-KEY          PIC 9(6).
+
+       PROCEDURE DIVISION USING LK-SEARCH-KEY.
+       MAIN-LOGIC SECTION.
+       MAIN-START.
+           PERFORM OPEN-FILE
+           PERFORM PROCESS-RECORDS
+           PERFORM CLOSE-FILE
+           STOP RUN.
+
+       OPEN-FILE.
+           OPEN I-O EMP-FILE.
+
+       PROCESS-RECORDS.
+           MOVE LK-SEARCH-KEY TO EMP-ID
+           EXEC SQL
+               SELECT EMP_SALARY INTO :WS-SALARY
+               FROM EMPLOYEES
+               WHERE EMP_ID = :EMP-ID
+           END-EXEC
+           CALL "EMPREPORT".
+
+       CLOSE-FILE.
+           CLOSE EMP-FILE.
+```
+
+The graph produced contains:
+
+**Nodes:**
+- `Module`: EMPMAINT (description: `author:Development Team`)
+- `Namespace`: MAIN-LOGIC
+- `Function`: MAIN-START, OPEN-FILE, PROCESS-RECORDS, CLOSE-FILE
+- `Record`: EMP-RECORD, WS-FLAGS, LK-SEARCH-KEY
+- `Property`: EMP-ID, EMP-NAME, WS-FILE-STATUS, WS-EOF-FLAG
+- `Const`: WS-EOF (values: Y)
+- `CodeElement`: SELECT:EMP-FILE, FD:EMP-FILE, sql-table:EMPLOYEES
+- (COPY imports, if any, would produce File IMPORTS edges)
+
+**Edges:**
+- `DEFINES`: File -> all nodes
+- `CONTAINS`: EMPMAINT -> EMP-RECORD, EMPMAINT -> WS-FLAGS, EMPMAINT -> LK-SEARCH-KEY
+- `CONTAINS`: EMP-RECORD -> EMP-ID, EMP-RECORD -> EMP-NAME
+- `CONTAINS`: WS-FLAGS -> WS-FILE-STATUS, WS-FLAGS -> WS-EOF-FLAG
+- `CONTAINS`: WS-EOF-FLAG -> WS-EOF
+- `CONTAINS`: FD:EMP-FILE -> EMP-RECORD
+- `CONTAINS`: SELECT:EMP-FILE -> FD:EMP-FILE
+- `CALLS`: MAIN-START -> OPEN-FILE, MAIN-START -> PROCESS-RECORDS, MAIN-START -> CLOSE-FILE
+- `CALLS`: EMPMAINT -> EMPREPORT (external CALL)
+- `ACCESSES`: EMPMAINT -> sql-table:EMPLOYEES
+- `RECEIVES`: EMPMAINT -> LK-SEARCH-KEY (PROCEDURE USING)
+- `RECORD_KEY_OF`: EMP-ID -> SELECT:EMP-FILE
+- `FILE_STATUS_OF`: WS-FILE-STATUS -> SELECT:EMP-FILE
+
+## How COBOL Differs from Tree-Sitter Languages
+
+| Aspect | COBOL | Tree-Sitter Languages |
+|--------|-------|----------------------|
+| Node variety | 8 types (Module, Function, Namespace, Record, Property, Const, CodeElement, Constructor) | Typically 4-6 (Function, Class, Method, Interface, Module, Const) |
+| Domain edges | RECORD_KEY_OF, FILE_STATUS_OF, ACCESSES, RECEIVES, CONTRACTS, REDEFINES | Primarily CALLS, IMPORTS, EXTENDS, IMPLEMENTS |
+| Data hierarchy | Deep CONTAINS chains (01 -> 05 -> 10 -> 88) | Flat class members |
+| Cross-program calls | CALL "name" + CICS LINK PROGRAM | Import-based resolution |
+| Contract detection | Shared COPY copybook between caller/callee | Not applicable |
+| Metadata | AUTHOR, DATE-WRITTEN on Module | JSDoc/docstring (not indexed) |
+
+## Source Files
+
+- `gitnexus/src/core/ingestion/workers/parse-worker.ts` -- `processCobolRegexOnly()`, node/edge emission logic
+- `gitnexus/src/core/ingestion/pipeline.ts` -- `detectCrossProgamContracts()` for CONTRACTS edges
+- `gitnexus/src/core/ingestion/cobol-preprocessor.ts` -- `CobolRegexResults` interface (all extracted data)
@@ -0,0 +1,261 @@
+# COBOL Performance and Tuning
+
+This document covers real-world benchmarks, worker pool configuration, memory management, known limitations, and troubleshooting for COBOL indexing.
+
+## PROJECT-NAME Benchmark
+
+The PROJECT-NAME project is a large Italian payroll system written in COBOL. It serves as the primary benchmark for COBOL indexing performance.
+
+### Input
+
+| Metric                      | Value                                                                        |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| Paths scanned               | 14,217                                                                       |
+| Parseable files             | 13,129                                                                       |
+| Total source size           | 224 MB                                                                       |
+| Chunks                      | 12 (at 20 MB budget)                                                         |
+| Copybooks loaded            | 2,976                                                                        |
+| Copybooks used in expansion | 2,955                                                                        |
+| Key directories             | `s/` (7773 programs), `c/` (3036 copybooks), `wfproc/` (1973 workflow files) |
+
+### Output
+
+| Metric                 | Value  |
+| ---------------------- | ------ |
+| Graph nodes            | 2.79M  |
+| Graph edges            | 5.67M  |
+| Clusters (communities) | 16,679 |
+| Execution flows        | 300    |
+
+### Timing
+
+| Phase                           | Duration          |
+| ------------------------------- | ----------------- |
+| Total                           | ~251s             |
+| KuzuDB write                    | 132s              |
+| Full-text search indexing       | 6.7s              |
+| Regex extraction (avg per file) | ~1ms              |
+| COPY expansion + deep indexing  | Remainder (~112s) |
+
+### Indexing Command
+
+```bash
+cd /path/to/PROJECT-NAME
+GITNEXUS_COBOL_DIRS=s,c,wfproc GITNEXUS_VERBOSE=1 node --max-old-space-size=8192 \
+  /path/to/gitnexus/dist/cli/index.js analyze --force
+```
+
+## Open-Source Benchmarks
+
+### CardDemo (AWS)
+
+| Metric | Value |
+| ------ | ----- |
+| Graph nodes | 12,323 |
+| Graph edges | 8,893 |
+| Total time | 7.4s |
+
+### ACAS
+
+| Metric | Value |
+| ------ | ----- |
+| Graph nodes | 14,016 |
+| Graph edges | 15,452 |
+| Total time | 9.3s |
+
+### Micro-Benchmark (Single-File Extraction)
+
+| Metric | Value |
+| ------ | ----- |
+| Per-iteration | 0.65ms |
+| Throughput | ~382K lines/sec |
+
+## Worker Pool Tuning
+
+### Sub-Batch Size
+
+The worker pool splits each worker's chunk into sub-batches to bound peak memory per `postMessage` serialization. COBOL repos use a smaller sub-batch size than the default:
+
+| Parameter             | Default     | COBOL Mode          |
+| --------------------- | ----------- | ------------------- |
+| Sub-batch size        | 1,500 files | 200 files           |
+| Per sub-batch timeout | 120s        | 120s (configurable) |
+
+**Why 200?** COBOL regex extraction + preprocessing takes ~1ms per file on average, but with COPY expansion and deep indexing the effective time is ~150ms per file. At sub-batch size 1500, that would be ~225s per sub-batch, exceeding the 120s timeout.
+
+COBOL mode is activated automatically when `GITNEXUS_COBOL_DIRS` is set:
+
+```typescript
+// From pipeline.ts
+const cobolSubBatch = process.env.GITNEXUS_COBOL_DIRS ? 200 : undefined;
+workerPool = createWorkerPool(workerUrl, undefined, cobolSubBatch);
+```
+
+### Worker Count
+
+Workers default to `min(8, cpus - 1)`. For COBOL repos, this is usually sufficient since regex extraction is CPU-bound but fast. The bottleneck is typically KuzuDB write, not extraction.
+
+### Timeout Configuration
+
+| Environment Variable                 | Default         | Purpose                                             |
+| ------------------------------------ | --------------- | --------------------------------------------------- |
+| `GITNEXUS_WORKER_TIMEOUT_MS`         | 120,000 (2 min) | Per sub-batch processing timeout                    |
+| `GITNEXUS_WORKER_STARTUP_TIMEOUT_MS` | 60,000 (1 min)  | Worker initialization timeout (tree-sitter loading) |
+
+For COBOL-only repos, worker startup is faster because tree-sitter native modules are loaded lazily (skipped entirely if only COBOL files are present).
+
+## Data Item Cap
+
+### Configuration
+
+```typescript
+const MAX_DATA_ITEMS_PER_FILE = 500;
+```
+
+This constant appears in both `parse-worker.ts` (worker path) and `parsing-processor.ts` (sequential fallback).
+
+### Rationale
+
+Some COBOL programs, especially after COPY expansion, can have 10,000+ data items. At that scale:
+
+- The in-memory relationship Map (for CONTAINS, REDEFINES, etc.) approaches the V8 16.7M entry limit across thousands of files
+- KuzuDB write time increases linearly with edge count
+- Most deep-nested items (level 20+) are rarely queried individually
+
+### Impact
+
+The cap truncates data items beyond the 500th in source order. Since 01-level Records appear first in COBOL source, the cap preserves:
+
+- All 01-level record definitions
+- The most important 02-49 level items (those closest to the record root)
+- 88-level conditions associated with early items
+
+To increase the cap for specific needs, modify the `MAX_DATA_ITEMS_PER_FILE` constant in both files.
+
+## Memory Management
+
+### COPY Expansion Breadth Guard
+
+A per-file `MAX_TOTAL_EXPANSIONS = 500` limit prevents exponential blowup from diamond-shaped COPY graphs (e.g., N copybooks each containing N COPY statements). Once the limit is reached, further COPY statements in that file are left unexpanded. See [copy-expansion.md](copy-expansion.md) for details.
+
+### COPY Expansion Memory
+
+All copybook content is loaded upfront into a Map before chunk processing begins. For PROJECT-NAME:
+
+- 2,976 copybooks, typically under 100MB total
+- The Map is shared (read-only) across chunk iterations
+- Per-chunk, the copybook map is merged with chunk file content (in case a chunk contains copybooks not in the pre-loaded set)
+- After all chunks are processed, the copybook map is freed (`cobolCopybookContents = undefined`)
+
+### Chunk Budget
+
+Source files are grouped into chunks of max 20MB (`CHUNK_BYTE_BUDGET`). Each chunk's lifecycle:
+
+1. Read file content into memory
+2. Expand COPY statements (mutates content in-place)
+3. Dispatch to workers for extraction
+4. Workers return serialized results
+5. Merge results into graph
+6. Chunk content goes out of scope (GC reclaims)
+
+This ensures only ~20MB of source + ~200-400MB of working memory (ASTs, extracted records, serialization) is active at any time.
+
+### Shared Warning Deduplication
+
+The `warnedCircular` set (used by the COPY expansion engine) is shared across all files in a chunk. This prevents the same circular copybook warning (e.g., `ANAZI includes itself`) from being logged thousands of times.
+
+## Known Limitations
+
+| Limitation                               | Impact                                                                                                          | Workaround                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| tree-sitter-cobol hangs on ~5% of files  | Cannot use tree-sitter for COBOL                                                                                | Regex-only extraction (current approach)                   |
+| Data item cap (500/file)                 | May miss deeply nested items in large programs                                                                  | Increase `MAX_DATA_ITEMS_PER_FILE` in source               |
+| Circular copybooks (ANAZI, ANDIP, QDIPE) | Self-referential includes cannot be expanded                                                                    | Detected and skipped with warning                          |
+| wfproc/ files may not be pure COBOL      | Workflow files may produce extraction noise                                                                     | Exclude `wfproc` from `GITNEXUS_COBOL_DIRS` if problematic |
+| No MOVE DATA_FLOW edges yet              | Data flow between variables not in graph                                                                        | Reserved for future release                                |
+| Continuation line handling               | Some complex multi-line continuations (especially in string literals spanning 3+ lines) may not merge correctly | Known edge case; affects <0.1% of lines                    |
+| Single-line EXEC blocks                  | `EXEC SQL SELECT ... END-EXEC` on one line is handled, but pathological nesting is not                          | Extremely rare in practice                                 |
+| Extension case sensitivity               | `.GNM` and `.gnm` are matched differently                                                                       | Use the exact case from the codebase                       |
+
+## Troubleshooting
+
+### "COPY expansion failed"
+
+```
+[pipeline] COPY expansion failed for s/BGTABFL: Cannot read properties of null
+```
+
+**Cause:** A copybook referenced by a COPY statement cannot be found.
+
+**Fix:**
+
+1. Verify `GITNEXUS_COBOL_DIRS` includes the directory containing copybooks (typically `c`)
+2. Check that copybook filenames match the COPY target (case-insensitive, after stripping extensions)
+3. Ensure copybook files are not in `.gitignore`
+
+### Worker sub-batch timeout
+
+```
+Worker 3 sub-batch timed out after 120s (chunk: 200 items)
+```
+
+**Cause:** A sub-batch took longer than the timeout. Typically happens when one file is extremely large (50,000+ lines after COPY expansion).
+
+**Fix:** Increase the timeout:
+
+```bash
+GITNEXUS_WORKER_TIMEOUT_MS=300000 gitnexus analyze
+```
+
+### Memory errors (heap out of memory)
+
+```
+FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
+```
+
+**Fix:** Increase Node.js heap size:
+
+```bash
+node --max-old-space-size=16384 /path/to/gitnexus/dist/cli/index.js analyze
+```
+
+For very large repos (>500MB source), consider `--max-old-space-size=32768`.
+
+### Concurrent analyze corruption
+
+**Rule:** Only ONE `gitnexus analyze` process should run at a time per repository. Concurrent writes to KuzuDB corrupt the database.
+
+If corruption occurs:
+
+```bash
+# Remove the KuzuDB directory and re-index
+rm -rf .gitnexus/kuzu
+gitnexus analyze --force
+```
+
+### Slow KuzuDB write phase
+
+The KuzuDB write phase (132s for PROJECT-NAME) is the bottleneck for large COBOL repos. This is proportional to the number of nodes and edges being written. Reducing `MAX_DATA_ITEMS_PER_FILE` or excluding non-essential directories from `GITNEXUS_COBOL_DIRS` can help.
+
+### Verbose output
+
+Enable verbose logging to see per-phase timing and statistics:
+
+```bash
+GITNEXUS_VERBOSE=1 gitnexus analyze
+```
+
+This outputs:
+
+- Scan statistics (paths, parseable files, chunk count)
+- Worker pool configuration (worker count, sub-batch size)
+- COPY expansion statistics (copybooks loaded, files expanded)
+- Community and process detection results
+- Contract detection results
+
+## Source Files
+
+- `gitnexus/src/core/ingestion/workers/worker-pool.ts` -- `DEFAULT_SUB_BATCH_SIZE`, `SUB_BATCH_TIMEOUT_MS`, `WORKER_STARTUP_TIMEOUT_MS`
+- `gitnexus/src/core/ingestion/pipeline.ts` -- `CHUNK_BYTE_BUDGET`, COBOL sub-batch configuration, chunk lifecycle
+- `gitnexus/src/core/ingestion/workers/parse-worker.ts` -- `MAX_DATA_ITEMS_PER_FILE`, `processCobolRegexOnly()`
+- `gitnexus/src/core/ingestion/parsing-processor.ts` -- Sequential fallback `MAX_DATA_ITEMS_PER_FILE`
@@ -0,0 +1,206 @@
+# COBOL Regex Extraction
+
+The `extractCobolSymbolsWithRegex()` function in `cobol-preprocessor.ts` performs single-pass, state-machine-driven extraction of all COBOL symbols. This document describes the state machine, line processing flow, and every regex pattern used.
+
+## State Machine: Division Tracking
+
+The extractor tracks which COBOL division is currently being processed. Division transitions are detected by the `RE_DIVISION` pattern.
+
+```mermaid
+stateDiagram-v2
+    [*] --> null : Start of file
+    null --> identification : IDENTIFICATION DIVISION
+    identification --> environment : ENVIRONMENT DIVISION
+    environment --> data : DATA DIVISION
+    data --> procedure : PROCEDURE DIVISION
+
+    note right of identification
+        Extracts: PROGRAM-ID, AUTHOR, DATE-WRITTEN
+    end note
+    note right of environment
+        Extracts: SELECT ... ASSIGN ... (file declarations)
+    end note
+    note right of data
+        Extracts: FD entries, data items (01-77, 88), COPY
+    end note
+    note right of procedure
+        Extracts: paragraphs, sections, PERFORM, CALL,
+        ENTRY, MOVE, EXEC SQL/CICS
+    end note
+```
+
+## State Machine: Data Section Tracking
+
+Within the DATA DIVISION, a secondary state machine tracks the current section to tag data items with their origin.
+
+```mermaid
+stateDiagram-v2
+    [*] --> unknown : DATA DIVISION entered
+    unknown --> working_storage : WORKING-STORAGE SECTION
+    unknown --> linkage : LINKAGE SECTION
+    unknown --> file : FILE SECTION
+    unknown --> local_storage : LOCAL-STORAGE SECTION
+    working_storage --> linkage : LINKAGE SECTION
+    working_storage --> file : FILE SECTION
+    linkage --> working_storage : WORKING-STORAGE SECTION
+    file --> working_storage : WORKING-STORAGE SECTION
+    file --> linkage : LINKAGE SECTION
+    local_storage --> working_storage : WORKING-STORAGE SECTION
+```
+
+Within the ENVIRONMENT DIVISION, the `currentEnvSection` tracks whether we are in `INPUT-OUTPUT` or `CONFIGURATION` section. SELECT statement accumulation only occurs in `INPUT-OUTPUT`.
+
+## Line Processing Flow
+
+Each raw source line goes through this pipeline:
+
+```
+Raw line
+  |
+  v
+Length < 7? ---------> Skip (flush pending if any)
+  |
+  v
+Indicator col 7
+  |
+  +-- '*' or '/' -----> Comment: skip entirely
+  |
+  +-- '-' ------------> Continuation: append to pending line
+  |
+  +-- other ----------> Normal: flush pending, strip inline comments (|),
+                        buffer as new pending logical line
+```
+
+After all lines are processed, the final pending line is flushed, along with any accumulated SELECT statement, SORT/MERGE accumulator, and any open EXEC block (truncated file without `END-EXEC`).
+
+### Inline Comment Stripping
+
+Enterprise COBOL (particularly Italian dialect) uses the pipe character `|` as an inline comment marker. The `stripInlineComment()` helper is **quote-aware**: it tracks whether the scan position is inside a single- or double-quoted string and only treats `|` as a comment marker when outside quotes. Pipe characters inside string literals are preserved.
+
+Free-format `*>` inline comment stripping uses the same quote-aware approach: the scanner walks character by character, toggling quote state, and only recognizes `*>` as a comment marker when not inside a quoted string.
+
+### Patch Marker Handling
+
+The `preprocessCobolSource()` function (run before extraction in the worker) replaces non-standard content in columns 1-6. Standard COBOL expects spaces or digit sequence numbers in this area. If any letter or `#` character is found, the entire sequence area is replaced with 6 spaces:
+
+```
+Before: mzADD MOVE WK-AMT TO WK-TOTAL
+After:        MOVE WK-AMT TO WK-TOTAL
+```
+
+This preserves exact line count for position mapping.
+
+## Regex Pattern Reference
+
+All patterns are compiled once as module-level constants and reused across calls.
+
+### Division and Section Detection
+
+| Constant | Pattern | Purpose | Example Match |
+|----------|---------|---------|---------------|
+| `RE_DIVISION` | `\b(IDENTIFICATION\|ENVIRONMENT\|DATA\|PROCEDURE)\s+DIVISION\b` | Division boundary | `PROCEDURE DIVISION` |
+| `RE_SECTION` | `\b(WORKING-STORAGE\|LINKAGE\|FILE\|LOCAL-STORAGE\|INPUT-OUTPUT\|CONFIGURATION)\s+SECTION\b` | Section boundary | `WORKING-STORAGE SECTION` |
+
+### IDENTIFICATION DIVISION
+
+| Constant | Pattern | Purpose | Example Match |
+|----------|---------|---------|---------------|
+| `RE_PROGRAM_ID` | `\bPROGRAM-ID\.\s*([A-Z][A-Z0-9-]*)` | Program name | `PROGRAM-ID. BGTABFL` |
+| `RE_AUTHOR` | `^\s+AUTHOR\.\s*(.+)` | Author metadata | `AUTHOR. D. Smith` |
+| `RE_DATE_WRITTEN` | `^\s+DATE-WRITTEN\.\s*(.+)` | Date metadata | `DATE-WRITTEN. 2024-01-15` |
+
+### ENVIRONMENT DIVISION
+
+| Constant | Pattern | Purpose | Example Match |
+|----------|---------|---------|---------------|
+| `RE_SELECT_START` | `\bSELECT\s+(?:OPTIONAL\s+)?([A-Z][A-Z0-9-]+)` | File SELECT start (with optional `SELECT OPTIONAL` support) | `SELECT MASTER-FILE`, `SELECT OPTIONAL TRANS-FILE` |
+
+SELECT statements are accumulated across multiple lines until a period terminator is found, then parsed for ASSIGN, ORGANIZATION, ACCESS, RECORD KEY, and FILE STATUS clauses.
+
+### DATA DIVISION
+
+| Constant | Pattern | Purpose | Example Match |
+|----------|---------|---------|---------------|
+| `RE_FD` | `^\s+FD\s+([A-Z][A-Z0-9-]+)` | File description | `FD MASTER-FILE` |
+| `RE_DATA_ITEM` | `^\s+(\d{1,2})\s+([A-Z][A-Z0-9-]+)\s*(.*)` | Data item (01-77) | `05 WK-NAME PIC X(30)` |
+| `RE_ANONYMOUS_REDEFINES` | `^\s+(\d{1,2})\s+REDEFINES\s+([A-Z][A-Z0-9-]+)` | Anonymous REDEFINES | `01 REDEFINES WK-REC` |
+| `RE_88_LEVEL` | `^\s+88\s+([A-Z][A-Z0-9-]+)\s+VALUES?\s+(?:ARE\s+)?(.+)` | Condition name | `88 WK-ACTIVE VALUE "Y"` |
+
+The trailing clauses of `RE_DATA_ITEM` are parsed by `parseDataItemClauses()` for PIC, USAGE, OCCURS, and REDEFINES.
+
+### PROCEDURE DIVISION
+
+| Constant | Pattern | Purpose | Example Match |
+|----------|---------|---------|---------------|
+| `RE_PROC_SECTION` | `^       ([A-Z][A-Z0-9-]+)\s+SECTION\.\s*$` | Procedure section header | `       MAIN-LOGIC SECTION.` |
+| `RE_PROC_PARAGRAPH` | `^       ([A-Z][A-Z0-9-]+)\.\s*$` | Paragraph header | `       PROCESS-RECORD.` |
+| `RE_PERFORM` | `\bPERFORM\s+([A-Z][A-Z0-9-]+)(?:\s+THRU\s+([A-Z][A-Z0-9-]+))?` | PERFORM call | `PERFORM CALC-TAX THRU CALC-TAX-EXIT` |
+| `RE_PROC_USING` | `\bPROCEDURE\s+DIVISION\s+USING\s+([\s\S]*?)(?:\.\|$)` | USING parameters | `PROCEDURE DIVISION USING WK-PARAM` |
+| `RE_ENTRY` | `\bENTRY\s+"([^"]+)"(?:\s+USING\s+([\s\S]*?))?(?:\.\|$)` | ENTRY point | `ENTRY "SUBPROG" USING WK-DATA` |
+| `RE_MOVE` | `\bMOVE\s+((?:CORRESPONDING\|CORR)\s+)?([A-Z][A-Z0-9-]+)\s+TO\s+(.+)` | MOVE statement (supports CORR abbreviation and multi-target) | `MOVE WK-NAME TO OUT-NAME`, `MOVE CORR WK-IN TO WK-OUT` |
+
+The USING parameter list (`RE_PROC_USING`) is split on `\bRETURNING\b` before tokenization -- any RETURNING clause and everything after it is excluded from the parameter list (`.split(/\bRETURNING\b/i)[0]`).
+
+Note: `RE_PROC_SECTION` and `RE_PROC_PARAGRAPH` require exactly 7 spaces of leading indentation (COBOL area A starting at column 8). This is the standard COBOL paragraph indentation.
+
+### All-Division Patterns
+
+These patterns are checked regardless of current division:
+
+| Constant | Pattern | Purpose | Example Match |
+|----------|---------|---------|---------------|
+| `RE_CALL` | `\bCALL\s+"([^"]+)"` | External program call | `CALL "BGTABUP"` |
+| `RE_COPY_UNQUOTED` | `\bCOPY\s+([A-Z][A-Z0-9-]+)(?:\s\|\.)` | COPY (unquoted) | `COPY CPSESP.` |
+| `RE_COPY_QUOTED` | `\bCOPY\s+"([^"]+)"(?:\s\|\.)` | COPY (quoted) | `COPY "WORKGRID.CPY".` |
+
+### SORT/MERGE Support
+
+| Constant | Purpose |
+|----------|---------|
+| `SORT_CLAUSE_NOISE` | Set of SORT/MERGE clause keywords filtered from USING/GIVING file lists: `ON`, `ASCENDING`, `DESCENDING`, `KEY`, `WITH`, `DUPLICATES`, `IN`, `ORDER`, `COLLATING`, `SEQUENCE`, `IS`, `THROUGH`, `THRU`, `INPUT`, `OUTPUT`, `PROCEDURE` |
+
+SORT and MERGE statements are accumulated across multiple lines (like SELECT) until a period terminator is found, then parsed for USING/GIVING file lists and INPUT/OUTPUT PROCEDURE targets. The `flushSort()` helper encapsulates the flush-and-parse logic, mirroring the existing `flushSelect()` pattern. Both helpers are called at EOF to handle truncated files.
+
+### GO TO Multi-Target
+
+`RE_GOTO` captures all paragraph names in a `GO TO` statement, including the multi-target form `GO TO p1 p2 p3 DEPENDING ON x`. The captured group contains all target names (space-separated), which are split into individual targets. Each target produces a separate `gotos` entry.
+
+### PROGRAM-ID Detection
+
+PROGRAM-ID is detected regardless of the current division state. This handles sibling programs that appear after `END PROGRAM` and omit the `IDENTIFICATION DIVISION` header -- the extractor will still capture the PROGRAM-ID and push a new program boundary.
+
+### EXEC Block Patterns
+
+| Constant | Pattern | Purpose | Example Match |
+|----------|---------|---------|---------------|
+| `RE_EXEC_SQL_START` | `\bEXEC\s+SQL\b` | Start of EXEC SQL block | `EXEC SQL` |
+| `RE_EXEC_CICS_START` | `\bEXEC\s+CICS\b` | Start of EXEC CICS block | `EXEC CICS` |
+| `RE_END_EXEC` | `\bEND-EXEC\b` | End of EXEC block | `END-EXEC` |
+
+EXEC blocks accumulate all lines between `EXEC SQL/CICS` and `END-EXEC`, then delegate to `parseExecSqlBlock()` or `parseExecCicsBlock()` for detailed extraction.
+
+## Excluded Paragraph Names
+
+The following names are excluded from paragraph detection to avoid false positives from division/section headers:
+
+```
+DECLARATIVES, END, PROCEDURE, IDENTIFICATION,
+ENVIRONMENT, DATA, WORKING-STORAGE, LINKAGE,
+FILE, LOCAL-STORAGE, COMMUNICATION, REPORT,
+SCREEN, INPUT-OUTPUT, CONFIGURATION
+```
+
+Additionally, paragraph candidates containing `DIVISION` or `SECTION` as substrings are excluded.
+
+## MOVE Skip List (Figurative Constants)
+
+MOVE statements where the source is a figurative constant are skipped:
+
+```
+SPACES, ZEROS, ZEROES, LOW-VALUES, LOW-VALUE,
+HIGH-VALUES, HIGH-VALUE, QUOTES, QUOTE, ALL
+```
+
+## Source Files
+
+- `gitnexus/src/core/ingestion/cobol-preprocessor.ts` -- `preprocessCobolSource()`, `extractCobolSymbolsWithRegex()`, all regex constants
@@ -0,0 +1,300 @@
+# 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).
@@ -0,0 +1,185 @@
+# 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.
@@ -0,0 +1,326 @@
+---
+title: "feat: Complete COBOL language feature coverage for maximum knowledge graph value"
+type: feat
+status: active
+date: 2026-03-26
+origin: Feature audit from v3-integration-architect agent (session 8642401e)
+---
+
+## Enhancement Summary
+
+**Deepened on:** 2026-03-26
+**Research agents used:** COBOL expert (Phase 1+2), graph value analyst, codebase explorer
+**Sections enhanced:** Phase 1 (5 features), Phase 2 (4 features), graph value ranking
+
+### Key Improvements from Research
+1. **CALL USING** is the #1 highest-value edge type (9.2/10) — fixes ~40% of missing caller references
+2. **EXEC DLI** requires dual-interface support (EXEC DLI + CBLTDLI CALL) for full IMS coverage
+3. **DECLARATIVES** is lowest-risk Phase 2 item — existing section/paragraph detection already captures structure
+4. **SET TO TRUE** accounts for 80-90% of all SET statements — prioritize this form
+5. **INSPECT** needs multi-line accumulator (like SORT) — can span 5+ continuation lines
+6. **Graph value ranking**: cobol-call-using (9.2) > cobol-error-handler (9.0) > dli-gu (8.2) > cobol-string (6.2)
+
+### New Edge Cases Discovered
+- CALL USING supports mixed modes: `USING BY REFERENCE WS-A BY CONTENT WS-B BY VALUE WS-C`
+- CALL USING `ADDRESS OF` and `OMITTED` must be filtered from parameter lists
+- EXEC DLI can have multiple SEGMENT levels in hierarchical retrieval (use matchAll)
+- DECLARATIVES can have multiple USE sections (one per file + catch-all for INPUT/OUTPUT/I-O/EXTEND)
+- INSPECT TALLYING can have multiple counters in a single statement
+- STRING/UNSTRING can span multiple lines (need accumulator pattern)
+
+---
+
+# Complete COBOL Language Feature Coverage
+
+## Overview
+
+Implement the remaining 25 unhandled COBOL language features and fix 10 partial features to achieve ~95% coverage (up from 71.9%). The goal is to build the richest possible knowledge graph from COBOL codebases, enabling a future `modernize` MCP command (out of scope for this plan) that would use the graph to assist with COBOL-to-modern-language migration.
+
+## Problem Statement
+
+The COBOL processor currently handles 54 of 89 applicable language features (71.9%). The 25 unhandled features represent real data loss in the knowledge graph:
+- **Cross-program data flow** is invisible (CALL ... USING parameters not extracted)
+- **IMS/DB programs** produce empty graphs (EXEC DLI not recognized)
+- **String transformation logic** is invisible (STRING/UNSTRING/INSPECT not tracked)
+- **SQL copybook dependencies** are missing (EXEC SQL INCLUDE not mapped)
+- **Error handling flows** are lost (DECLARATIVES/USE AFTER not captured)
+
+## Proposed Solution
+
+Implement features in 4 phases, ordered by graph value density (edges created per LOC of implementation). Each phase is independently shippable and testable.
+
+## Technical Approach
+
+### Phase 1: High-Value Data Flow Edges (~150 LOC, ~8 new edge types)
+
+The highest-ROI features: they create new ACCESSES and IMPORTS edges that directly improve impact analysis.
+
+**Critical research finding**: Multi-line statement accumulation is the dominant challenge. CALL USING, STRING/UNSTRING, and multi-line data item clauses all span multiple lines in production COBOL. The free-format path processes each line independently — these features need statement accumulators (like SORT/SELECT) or the free-format path needs multi-line awareness. Estimated LOC increased from 110 to 150 to account for accumulator infrastructure.
+
+#### 1.1 EXEC SQL INCLUDE -> IMPORTS edges
+- **File:** `cobol-preprocessor.ts` (parseExecSqlBlock)
+- **What:** Detect `INCLUDE` as the operation, extract member name, emit as a `copies[]` entry
+- **Graph:** IMPORTS edge from File to included copybook/SQLCA with reason `sql-include`
+- **Tests:** Unit test for `EXEC SQL INCLUDE SQLCA END-EXEC` and `EXEC SQL INCLUDE CUSTCOPY END-EXEC`
+
+**Research insights (EXEC SQL INCLUDE):**
+- DB2 member names can contain underscores: `EXEC SQL INCLUDE CUST_TBL_DCL END-EXEC` — regex must use `[A-Z][A-Z0-9_-]+`
+- Quoted literal form: `EXEC SQL INCLUDE 'DBRMLIB.MEMBER' END-EXEC` (z/OS PDS qualified name)
+- SQLCA/SQLDA are DB2 builtins — won't resolve to repo files. Emit unresolved IMPORTS edge (still valuable)
+- No REPLACING support on EXEC SQL INCLUDE (unlike COPY)
+- Add `INCLUDE` to `OP_MAP` in `parseExecSqlBlock`; extract member via `RE_SQL_INCLUDE = /^INCLUDE\s+(?:'([^']+)'|"([^"]+)"|([A-Z][A-Z0-9_-]+))/i`
+
+#### 1.2 CALL ... USING parameter extraction -> ACCESSES edges (Graph value: 9.2/10)
+- **File:** `cobol-preprocessor.ts` (processLogicalLine CALL section)
+- **What:** After capturing CALL target, scan for USING clause. Extract parameter names (reuse USING_KEYWORDS filter). Store as `calls[].parameters: string[]`
+- **Interface:** Add `parameters?: string[]` to calls array type in CobolRegexResults
+- **File:** `cobol-processor.ts` (CALL edge block)
+- **Graph:** For each USING parameter, create ACCESSES edge from caller to data item Property node with reason `cobol-call-using`
+- **Tests:** `CALL 'AUDITLOG' USING CUST-ID WS-AMOUNT` -> 2 ACCESSES edges
+
+**Research insights (CALL USING forms):**
+- Mixed modes: `CALL 'PGM' USING BY REFERENCE WS-A BY CONTENT WS-B BY VALUE WS-C`
+- Pointer passing: `CALL 'PGM' USING ADDRESS OF WS-A`
+- Placeholder: `CALL 'PGM' USING OMITTED WS-B`
+- Filter keywords: add `ADDRESS`, `OMITTED`, `LENGTH` to USING_KEYWORDS (already has BY/VALUE/REFERENCE/CONTENT)
+- **Impact tool enhancement:** CALL-USING edges enable BFS traversal through parameter data flow — single most impactful edge type for COBOL impact analysis
+
+#### 1.3 STRING/UNSTRING data flow -> ACCESSES edges
+- **File:** `cobol-preprocessor.ts` (new section in extractProcedure)
+- **What:** Accumulate multi-line STRING/UNSTRING until period or END-STRING/END-UNSTRING. Extract sources and INTO targets.
+- **Interface:** Add `strings: Array<{ sources: string[]; target: string; type: 'string' | 'unstring'; line: number; caller: string | null }>` to CobolRegexResults
+- **Graph:** read-ACCESSES on sources, write-ACCESSES on INTO target with reason `cobol-string-read` / `cobol-string-write`
+- **Tests:** 2 unit tests + integration test assertions
+
+**Research insights (STRING/UNSTRING):**
+- **Needs statement accumulator** — STRING/UNSTRING always span multiple lines in production
+- Terminate accumulation at: period, END-STRING/END-UNSTRING, or start of next COBOL verb
+- STRING sources: identifiers before each `DELIMITED BY`. Filter: STRING, DELIMITED, BY, SIZE, ALL, INTO, WITH, POINTER, ON, OVERFLOW, NOT, END-STRING
+- UNSTRING: source is first identifier after UNSTRING; INTO targets are identifiers after INTO. Filter: DELIMITER, IN, COUNT, TALLYING, OR
+- WITH POINTER field is both read AND written (starting position updated)
+- TALLYING IN / COUNT IN fields are write targets
+- Literal sources (`'text'`) must be filtered — quote-aware tokenization needed
+- **Edge case**: STRING terminated by next verb, not period — existing fixture has `STRING ... DISPLAY` without period between them
+
+#### 1.4 OCCURS DEPENDING ON -> ACCESSES edge
+- **File:** `cobol-preprocessor.ts` (parseDataItemClauses)
+- **What:** Extend OCCURS regex to capture DEPENDING ON field, KEY fields, and INDEXED BY names
+- **Interface:** Add `dependingOn?: string`, `occursMax?: number`, `occursKeys?: Array<{direction: string; fields: string[]}>`, `indexedBy?: string[]` to data items
+- **Graph:** ACCESSES edge from table item to controlling field with reason `cobol-depends-on`
+- **Tests:** `05 WS-TABLE OCCURS 100 DEPENDING ON WS-COUNT` -> edge
+
+**Research insights (OCCURS):**
+- IBM allows `OCCURS 0 TO n DEPENDING ON` (zero minimum) and `OCCURS UNBOUNDED DEPENDING ON` (V6.4)
+- Subscripted controlling fields: `DEPENDING ON WS-COUNT(WS-IDX)` — strip subscripts before storing
+- **Pre-existing gap**: Multi-line data item clauses without continuation indicator are NOT captured. `05 WS-TABLE\n    OCCURS 100\n    DEPENDING ON WS-COUNT.` — the current RE_DATA_ITEM only gets the first line, `rest` is empty. Fixing properly requires a data item accumulator (like SELECT). **Defer full fix to Phase 3; implement same-line capture now.**
+- KEY IS fields: `ASCENDING KEY IS WS-KEY-1 WS-KEY-2` — capture for SEARCH ALL resolution
+- INDEXED BY: `INDEXED BY IDX-1 IDX-2` — capture for SET/SEARCH context
+
+#### 1.5 VALUE clause for standard data items
+- **File:** `cobol-preprocessor.ts` (parseDataItemClauses)
+- **What:** Extract VALUE using a pragmatic function that handles quoted strings, numerics, figurative constants, hex/national literals
+- **Interface:** Already exists as `values?: string[]` on data items (currently only populated for 88-level)
+- **Graph:** Stored in Property node description (no new edges)
+- **Tests:** `01 WS-STATUS PIC X VALUE 'A'` -> values: ['A']
+
+**Research insights (VALUE forms):**
+- Hex literals: `VALUE X'F1F2F3F4'`, National: `VALUE N'text'`, DBCS: `VALUE G'text'`
+- Figurative constants: SPACES, ZEROS, ZEROES, LOW-VALUES, HIGH-VALUES, QUOTES, NULL, NULLS
+- ALL literal: `VALUE ALL '*'`
+- Numeric with sign/decimal: `VALUE -123.45`, `VALUE +1`
+- `VALUE IS` optional — both `VALUE 'A'` and `VALUE IS 'A'` valid
+- **Decimal vs period ambiguity**: `VALUE 100.` — is `.` decimal or terminator? `parseDataItemClauses` already strips trailing period, so this is handled
+- IBM V6.4: floating-point `VALUE 1.0E5` — extend numeric regex if needed
+- Implementation: use a pragmatic `extractValue(rest)` function, not a single complex regex
+
+### Phase 2: EXEC DLI + DECLARATIVES (~90 LOC, ~4 new edge types)
+
+IMS/DB support and error handling flows.
+
+#### 2.1 EXEC DLI (IMS/DB) -> ACCESSES edges (Graph value: 8.2/10)
+- **File:** `cobol-preprocessor.ts` (processLogicalLine — add RE_EXEC_DLI_START check alongside SQL/CICS)
+- **What:** Accumulate EXEC DLI blocks like EXEC SQL. Parse DLI verbs (GU, GN, GNP, GHU, GHN, GHNP, ISRT, DLET, REPL, CHKP, SCHD, TERM). Extract segment name, PCB number, INTO/FROM areas, WHERE fields, PSB name.
+- **Interface:** Add `execDliBlocks: Array<{ line: number; verb: string; pcbNumber?: number; segmentName?: string; intoField?: string; fromField?: string; whereField?: string; psbName?: string }>` to CobolRegexResults
+- **Graph:** CodeElement node + ACCESSES edge to `<ims>:<segmentName>` Record node with reason `dli-{verb}`; ACCESSES edges to INTO/FROM data areas; PSB ACCESSES for SCHD
+- **Tests:** `EXEC DLI GU USING PCB(1) SEGMENT(CUSTOMER) INTO(WS-CUST) END-EXEC`
+
+**Research insights (dual IMS interface):**
+- **EXEC DLI**: Embedded command interface for CICS-DL/I programs only
+- **CBLTDLI CALL**: Batch interface via `CALL 'CBLTDLI' USING function-code PCB io-area SSA1..SSA15`
+- CBLTDLI is already captured as a CALL to 'CBLTDLI' — enrich with USING parameter semantics later
+- Multiple SEGMENT levels in hierarchical retrieval — use `matchAll` on segment regex
+- DLI verbs: GU (most common), GN, GNP, GHU, GHN, GHNP, ISRT, REPL, DLET, CHKP, SCHD, TERM, ROLL, ROLB
+- **Edge case**: DLET/REPL have no SEGMENT clause (operate on current position)
+- **Recommended order**: Implement AFTER DECLARATIVES and SET (lower risk, higher frequency)
+
+#### 2.2 DECLARATIVES / USE AFTER STANDARD EXCEPTION (Graph value: 9.0/10)
+- **File:** `cobol-preprocessor.ts` (processLogicalLine — detect DECLARATIVES keyword, track USE AFTER blocks)
+- **What:** When `DECLARATIVES.` is encountered, switch to declaratives mode. Extract USE statements binding sections to files/modes.
+- **Interface:** Add `declaratives: Array<{ sectionName: string; useType: 'error' | 'debug' | 'label' | 'reporting'; target: string; line: number }>` to CobolRegexResults
+- **Graph:** ACCESSES edge from declarative Namespace to file Record with reason `cobol-declarative-error-handler`
+- **Tests:** Unit test with DECLARATIVES section, integration test for error flow
+
+**Research insights (DECLARATIVES syntax):**
+- `USE AFTER STANDARD {EXCEPTION|ERROR} ON {file-name|INPUT|OUTPUT|I-O|EXTEND}`
+- EXCEPTION and ERROR are synonymous; STANDARD is optional in IBM dialects
+- Multiple USE sections allowed (one per file + catch-all for I/O modes)
+- `END DECLARATIVES.` must NOT reset PROCEDURE DIVISION state
+- `DECLARATIVES` is already in EXCLUDED_PARA_NAMES — no false paragraph risk
+- Existing section/paragraph detection already captures structural elements — just need USE binding
+- **Lowest risk Phase 2 item** — implement first
+
+#### 2.3 SET statement -> ACCESSES edges
+- **File:** `cobol-preprocessor.ts` (extractProcedure — new RE_SET regex)
+- **Interface:** Add `sets: Array<{ targets: string[]; form: 'to-true'|'to-value'|'up-by'|'down-by'|'address-of'|'to-null'|'to-entry'; value?: string; entryTarget?: string; entryIsLiteral?: boolean; line: number; caller: string | null }>` to CobolRegexResults
+- **Graph:** ACCESSES write edge with reason `cobol-set-condition` (TO TRUE), `cobol-set-index` (TO/UP/DOWN), `cobol-set-address` (ADDRESS OF). SET ENTRY with literal -> CALLS edge.
+- **Tests:** `SET WS-EOF TO TRUE`, `SET IDX-1 TO 5`, `SET IDX-1 UP BY 1`
+
+**Research insights (SET forms by frequency):**
+- `SET condition TO TRUE` — 80-90% of all SET usage. Multiple targets: `SET COND-A COND-B TO TRUE`
+- `SET index TO/UP BY/DOWN BY` — ~8%. Multiple indices: `SET IDX-1 IDX-2 UP BY 1`
+- `SET pointer TO ADDRESS OF data-item` / `SET ADDRESS OF data-item TO pointer` — ~2%
+- `SET proc-ptr TO ENTRY "PROGNAME"` — rare but creates CALLS edge (like dynamic CALL)
+- Filter OF/IN qualifiers: `SET COND-A OF WS-RECORD TO TRUE` (strip OF WS-RECORD)
+- **Prioritize**: SET TO TRUE alone covers 80-90% — implement this form first
+
+#### 2.4 INSPECT -> ACCESSES edges
+- **File:** `cobol-preprocessor.ts` (extractProcedure — new `inspectAccum` accumulator like SORT)
+- **What:** Accumulate multi-line INSPECT until period. Extract inspected field + tally counters.
+- **Interface:** Add `inspects: Array<{ inspectedField: string; counters: string[]; form: 'tallying'|'replacing'|'converting'|'tallying-replacing'; line: number; caller: string | null }>` to CobolRegexResults
+- **Graph:** ACCESSES read on inspected field always; write if REPLACING/CONVERTING. Write edges for tally counters. Reason: `cobol-inspect-read`/`cobol-inspect-write`/`cobol-inspect-tally`
+- **Tests:** `INSPECT WS-FIELD TALLYING WS-COUNT FOR ALL 'A'` -> read on WS-FIELD, write on WS-COUNT
+
+**Research insights (INSPECT forms by frequency):**
+- REPLACING (~60%): `INSPECT WS-STR REPLACING ALL 'A' BY 'B'`
+- TALLYING (~25%): `INSPECT WS-STR TALLYING WS-CNT FOR ALL 'A'` — multiple counters possible
+- CONVERTING (~10%): `INSPECT WS-STR CONVERTING 'abc' TO 'ABC'`
+- Combined (~5%): TALLYING + REPLACING in single statement
+- **Needs multi-line accumulator** — INSPECT frequently spans 3-5 lines in production
+- Extract tally counters with `([A-Z][A-Z0-9-]+)\s+FOR\b` matchAll pattern
+- Filter figurative constants (SPACES, ZEROS) using existing MOVE_SKIP set
+
+### Phase 3: Completeness Fixes (~60 LOC)
+
+Fix the 10 partial features and small gaps.
+
+#### 3.1 CALL ... RETURNING extraction
+- Extend RE_CALL processing to capture RETURNING target after the USING clause
+- Store as `calls[].returning?: string`
+- Graph: ACCESSES write edge with reason `cobol-call-returning`
+
+#### 3.2 SELECT OPTIONAL flag preservation
+- Store `isOptional: boolean` in FileDeclaration interface
+- Include in Record node description
+
+#### 3.3 ALTERNATE RECORD KEY extraction
+- Add regex in parseSelectStatement: `/\bALTERNATE\s+RECORD\s+KEY\s+(?:IS\s+)?([A-Z][A-Z0-9-]+)/i`
+- Store as `alternateKeys?: string[]`
+
+#### 3.4 COMMON attribute on nested programs
+- Extend RE_PROGRAM_ID: `/\bPROGRAM-ID\.\s*([A-Z][A-Z0-9-]+)(?:\s+IS\s+COMMON)?/i`
+- Store `isCommon: boolean` on Module node
+- Affects cross-program CALL resolution scope
+
+#### 3.5 IS EXTERNAL / IS GLOBAL as first-class properties
+- Change from usage string hack to proper boolean fields on data items
+- Add `isExternal?: boolean`, `isGlobal?: boolean` to data item interface
+
+#### 3.6 AUTHOR / DATE-WRITTEN mapped to Module node
+- Already extracted as programMetadata — map to Module node properties
+- `graph.addNode({ ..., properties: { ..., author, dateWritten } })`
+
+#### 3.7 REPLACE statement
+- Track REPLACE / REPLACE OFF state in preprocessor
+- Apply text substitutions during preprocessing (before regex extraction)
+- Complex: requires careful scoping rules
+
+### Phase 4: Niche Features (~30 LOC)
+
+Low-priority but nice for completeness.
+
+#### 4.1 INITIALIZE statement -> write ACCESSES
+- `/\bINITIALIZE\s+([A-Z][A-Z0-9-]+)/i`
+- ACCESSES write edge with reason `cobol-initialize`
+
+#### 4.2 Remaining IDENTIFICATION DIVISION paragraphs
+- DATE-COMPILED, INSTALLATION, SECURITY, REMARKS
+- Map to Module node description properties
+
+#### 4.3 EXEC SQL INCLUDE -> IMPORTS edge (expansion)
+- For EXEC SQL INCLUDE inside EXEC blocks that reference copybooks containing SQL
+- Create IMPORTS edge similar to COPY
+
+## Acceptance Criteria
+
+### Functional Requirements
+
+- [ ] Phase 1: All 5 features implemented with unit + integration tests
+- [ ] Phase 2: All 4 features implemented with unit + integration tests
+- [ ] Phase 3: All 7 partial features fixed
+- [ ] Phase 4: At least 2 of 3 niche features implemented
+- [ ] All existing 145 tests continue to pass
+- [ ] TypeScript compiles cleanly
+
+### Non-Functional Requirements
+
+- [ ] No performance regression: CardDemo benchmark stays under 8s
+- [ ] No file exceeds 1500 LOC (preprocessor currently 1326)
+- [ ] ACAS benchmark shows increased node/edge counts (more data extracted)
+- [ ] CardDemo benchmark shows increased edge counts (CALL USING, STRING, etc.)
+
+### Quality Gates
+
+- [ ] Each phase has its own commit
+- [ ] Integration test assertions updated with exact counts per phase
+- [ ] Benchmark run after each phase to track graph growth
+
+## Dependencies & Risks
+
+### Dependencies
+- None. All changes are additive to existing COBOL processor code.
+- No LanguageProvider changes needed.
+- No graph schema changes needed (all new constructs map to existing node labels + edge types).
+
+### Risks
+- **preprocessor.ts size**: Currently 1326 LOC. Phase 1+2 adds ~200 LOC -> 1526 LOC. May need to extract helpers into a separate `cobol-data-flow.ts` module if it exceeds 1500.
+- **REPLACE statement** (Phase 3.7) is the most complex feature — requires tracking text substitution state across logical lines. Consider deferring to a separate PR if it takes >100 LOC.
+- **EXEC DLI** (Phase 2.1) is only testable against IMS codebases. Need fixture data or synthetic test cases.
+
+## Graph Value Ranking by MCP Tool Impact
+
+Research agent analyzed all 5 MCP tools (query, context, impact, detect_changes, rename) against planned edge types:
+
+| Edge Type | QUERY | CONTEXT | IMPACT | DETECT | RENAME | **Overall** |
+|-----------|-------|---------|--------|--------|--------|-------------|
+| `cobol-call-using` | 4/5 | 5/5 | 5/5 | 4/5 | 4/5 | **9.2/10** |
+| `cobol-error-handler` | 5/5 | 4/5 | 5/5 | 5/5 | 2/5 | **9.0/10** |
+| `dli-*` (IMS verbs) | 4/5 | 4/5 | 5/5 | 4/5 | 2/5 | **8.2/10** |
+| `cobol-string-*` | 4/5 | 3/5 | 3/5 | 3/5 | 2/5 | **6.2/10** |
+
+**Key finding**: `cobol-call-using` alone would fix ~40% of missing caller references in COBOL graphs.
+
+## Future Considerations
+
+This plan provides the graph data foundation for a future `modernize` MCP command (out of scope) that would:
+- Use CALL USING edges to map data contracts between programs
+- Use STRING/UNSTRING edges to identify data transformation logic
+- Use EXEC SQL/DLI edges to map database access patterns
+- Use DECLARATIVES to understand error handling architecture
+- Use the complete knowledge graph to generate migration plans
+
+**MCP tool enhancements needed** (after this plan ships):
+- Add `cobol-call-using`, `cobol-error-handler`, `dli-*` to IMPACT tool's default `relationTypes` for COBOL repos
+- Add confidence floors for new edge types in `IMPACT_RELATION_CONFIDENCE`
+- Register new edge types in `VALID_RELATION_TYPES` set (`local-backend.ts:52`)
+
+## Sources & References
+
+### Internal References
+- Feature audit: session 8642401e (COBOL expert agent, 123 features audited)
+- Prior plans: `docs/plans/2026-03-25-feat-cobol-100-percent-feature-coverage-plan.md`
+- Architecture: `docs/code-indexing/cobol/` (7 documentation files)
+
+### External References
+- COBOL features reference: mainframestechhelp.com/tutorials/cobol/features.htm
+- COBOL-85 standard: ISO/IEC 1989:1985
+- IBM Enterprise COBOL reference
@@ -0,0 +1,725 @@
+# PR #626 HIGH-Priority Fixes Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix 4 HIGH-priority issues from PR #626 code review before merge.
+
+**Architecture:** Minimal targeted fixes — each task is independent. TDD: tests first, then implementation. No refactoring beyond what's needed.
+
+**Tech Stack:** TypeScript, Vitest, Node.js fs/path APIs
+
+**Spec:** `docs/superpowers/specs/2026-04-02-pr626-high-fixes-design.md`
+
+**Paths:** All file paths are relative to the monorepo root (`GitNexus/`). Git commands run from the root. The `gitnexus/` prefix is a package subdirectory, not a separate repo.
+
+---
+
+### Task 1: Path Traversal — Validate Group Name
+
+**Files:**
+- Modify: `gitnexus/src/core/group/storage.ts:17-19` (getGroupDir) and `:63-68` (createGroupDir)
+- Test: `gitnexus/test/unit/group/storage.test.ts`
+
+- [ ] **Step 1: Write failing tests for validateGroupName**
+
+In `gitnexus/test/unit/group/storage.test.ts`, add `createGroupDir` and `validateGroupName` to the existing import from `'../../../src/core/group/storage.js'` (line 6-11). Then add these describe blocks at the end of the outer `describe('Group storage', ...)`:
+
+```typescript
+  describe('validateGroupName', () => {
+    it('test_validateGroupName_traversal_path_throws', () => {
+      expect(() => validateGroupName('../../evil')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_slash_in_name_throws', () => {
+      expect(() => validateGroupName('foo/bar')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_empty_string_throws', () => {
+      expect(() => validateGroupName('')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_starts_with_dash_throws', () => {
+      expect(() => validateGroupName('-leading-dash')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_starts_with_underscore_throws', () => {
+      expect(() => validateGroupName('_leading')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_dots_throws', () => {
+      expect(() => validateGroupName('com.example')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_valid_alphanumeric_passes', () => {
+      expect(() => validateGroupName('my-group_01')).not.toThrow();
+    });
+
+    it('test_validateGroupName_single_char_passes', () => {
+      expect(() => validateGroupName('A')).not.toThrow();
+    });
+
+    it('test_validateGroupName_all_digits_passes', () => {
+      expect(() => validateGroupName('123')).not.toThrow();
+    });
+  });
+
+  describe('getGroupDir rejects invalid names', () => {
+    it('test_getGroupDir_traversal_throws', () => {
+      expect(() => getGroupDir(tmpDir, '../../etc')).toThrow(/Invalid group name/);
+    });
+
+    it('test_getGroupDir_valid_name_returns_path', () => {
+      const dir = getGroupDir(tmpDir, 'company');
+      expect(dir).toBe(path.join(tmpDir, 'groups', 'company'));
+    });
+  });
+
+  describe('createGroupDir rejects invalid names', () => {
+    it('test_createGroupDir_traversal_throws', async () => {
+      await expect(createGroupDir(tmpDir, '../evil')).rejects.toThrow(/Invalid group name/);
+    });
+  });
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/storage.test.ts`
+Expected: FAIL — `validateGroupName` is not exported, `getGroupDir` does not throw.
+
+- [ ] **Step 3: Implement validateGroupName and wire into getGroupDir and createGroupDir**
+
+In `gitnexus/src/core/group/storage.ts`, add the validation function before `getGroupDir` and call it:
+
+```typescript
+const GROUP_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+
+export function validateGroupName(name: string): void {
+  if (!GROUP_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid group name "${name}". Names must start with a letter or digit and contain only [a-zA-Z0-9_-].`,
+    );
+  }
+}
+
+export function getGroupDir(gitnexusDir: string, groupName: string): string {
+  validateGroupName(groupName);
+  return path.join(gitnexusDir, 'groups', groupName);
+}
+```
+
+`createGroupDir` already calls `getGroupDir` at line 68, so it inherits validation automatically. No change needed in `createGroupDir`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/storage.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd gitnexus && git add src/core/group/storage.ts test/unit/group/storage.test.ts
+git commit -m "fix(group): validate group name to prevent path traversal
+
+Add validateGroupName() with regex [a-zA-Z0-9][a-zA-Z0-9_-]*.
+Called in getGroupDir (defense in depth) which covers all CLI entry
+points: create, add, remove, status, sync.
+
+Addresses PR #626 review item 1 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Directory Exclusions in Service Boundary Detector
+
+**Files:**
+- Modify: `gitnexus/src/core/group/service-boundary-detector.ts:24-51` (add constant), `:78` (walkForBoundaries), `:130` (hasSourceFilesInSubdirs)
+- Test: `gitnexus/test/unit/group/service-boundary-detector.test.ts`
+
+- [ ] **Step 1: Write failing tests for excluded directories**
+
+Add this describe block inside the existing `detectServiceBoundaries` describe in `gitnexus/test/unit/group/service-boundary-detector.test.ts`:
+
+```typescript
+    it('test_detect_skips_vendor_directory', async () => {
+      writeFile('services/auth/package.json', '{}');
+      writeFile('services/auth/src/index.ts', '');
+      // vendor should be skipped — its contents should not create a boundary
+      writeFile('vendor/some-dep/package.json', '{}');
+      writeFile('vendor/some-dep/src/lib.go', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/auth');
+      expect(paths).not.toContain('vendor/some-dep');
+    });
+
+    it('test_detect_skips_target_directory', async () => {
+      writeFile('services/api/go.mod', 'module api');
+      writeFile('services/api/main.go', '');
+      writeFile('target/classes/Main.java', '');
+      writeFile('target/pom.xml', '<project/>');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/api');
+      expect(paths).not.toContain('target');
+    });
+
+    it('test_detect_skips_pycache_directory', async () => {
+      writeFile('services/ml/pyproject.toml', '[project]');
+      writeFile('services/ml/model.py', '');
+      // __pycache__ with a marker + source files — would be detected as
+      // a boundary if not excluded, since it has package.json + .py file
+      writeFile('__pycache__/package.json', '{}');
+      writeFile('__pycache__/cached.py', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/ml');
+      expect(paths.every((p) => !p.includes('__pycache__'))).toBe(true);
+    });
+
+    it('test_detect_skips_dotfile_directories_regression', async () => {
+      writeFile('services/api/package.json', '{}');
+      writeFile('services/api/src/index.ts', '');
+      writeFile('.hidden/package.json', '{}');
+      writeFile('.hidden/src/index.ts', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/api');
+      expect(paths).not.toContain('.hidden');
+    });
+
+    it('test_detect_does_not_skip_regular_source_directories', async () => {
+      writeFile('services/api/package.json', '{}');
+      writeFile('services/api/src/index.ts', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      expect(boundaries).toHaveLength(1);
+      expect(boundaries[0].serviceName).toBe('api');
+    });
+```
+
+- [ ] **Step 2: Run tests to verify `vendor` and `target` tests fail**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/service-boundary-detector.test.ts`
+Expected: `test_detect_skips_vendor_directory` and `test_detect_skips_target_directory` FAIL (vendor/target not excluded). Other new tests may pass since dotfile exclusion already exists.
+
+- [ ] **Step 3: Add EXCLUDED_DIRS constant and update both walking functions**
+
+In `gitnexus/src/core/group/service-boundary-detector.ts`:
+
+After `SOURCE_EXTENSIONS` (after line 51), add:
+
+```typescript
+const EXCLUDED_DIRS = new Set([
+  'node_modules',
+  'vendor',
+  'target',
+  'build',
+  'dist',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.tox',
+  '.mypy_cache',
+  '.gradle',
+  '.mvn',
+  'out',
+  'bin',
+]);
+```
+
+In `walkForBoundaries`, replace line 78:
+```typescript
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+```
+with:
+```typescript
+    if (entry.name.startsWith('.') || EXCLUDED_DIRS.has(entry.name)) continue;
+```
+
+In `hasSourceFilesInSubdirs`, replace line 130:
+```typescript
+      if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+```
+with:
+```typescript
+      if (entry.isDirectory() && !entry.name.startsWith('.') && !EXCLUDED_DIRS.has(entry.name)) {
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/service-boundary-detector.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd gitnexus && git add src/core/group/service-boundary-detector.ts test/unit/group/service-boundary-detector.test.ts
+git commit -m "fix(group): add directory exclusions to service boundary detector
+
+Add EXCLUDED_DIRS set: vendor, target, build, dist, __pycache__,
+.venv, venv, .tox, .mypy_cache, .gradle, .mvn, out, bin.
+Applied in walkForBoundaries and hasSourceFilesInSubdirs.
+Replaces inline node_modules check.
+
+Addresses PR #626 review item 3 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Remove Double-Close of LadybugDB Pools
+
+**Files:**
+- Modify: `gitnexus/src/cli/group.ts:160` (remove import), `:187-189` (remove finally block body)
+- Test: `gitnexus/test/unit/group/sync.test.ts` (add pool cleanup test)
+- Test: `gitnexus/test/integration/group/group-cli.test.ts` (verify no blanket close in source)
+
+- [ ] **Step 1: Write unit tests for per-id pool cleanup in sync.ts**
+
+Add to `gitnexus/test/unit/group/sync.test.ts`, inside the existing `describe('syncGroup', ...)`:
+
+```typescript
+  it('test_syncGroup_closes_only_opened_pools', async () => {
+    const config = makeConfig({
+      'app/backend': 'backend-repo',
+      'app/frontend': 'frontend-repo',
+    });
+
+    const closedIds: string[] = [];
+
+    // Mock initLbug/closeLbug via per-repo override that tracks pool lifecycle
+    const { vi } = await import('vitest');
+    const poolAdapter = await import('../../../src/core/lbug/pool-adapter.js');
+    const initSpy = vi.spyOn(poolAdapter, 'initLbug').mockResolvedValue(undefined);
+    const closeSpy = vi.spyOn(poolAdapter, 'closeLbug').mockImplementation(async (id?: string) => {
+      if (id) closedIds.push(id);
+    });
+
+    try {
+      await syncGroup(config, {
+        resolveRepoHandle: async (_name, groupPath) => ({
+          id: groupPath.replace(/\//g, '-'),
+          path: groupPath,
+          repoPath: '/tmp/' + groupPath,
+          storagePath: '/tmp/' + groupPath + '/.gitnexus',
+        }),
+        skipWrite: true,
+      }).catch(() => {});
+      // Regardless of extraction errors, closeLbug should be called per id
+      // closeLbug should only receive specific pool ids, never undefined/empty
+      for (const id of closedIds) {
+        expect(id).toBeTruthy();
+        expect(typeof id).toBe('string');
+      }
+      // No blanket close (no-arg call)
+      const blanketCalls = closeSpy.mock.calls.filter((args) => args.length === 0 || !args[0]);
+      expect(blanketCalls).toHaveLength(0);
+    } finally {
+      initSpy.mockRestore();
+      closeSpy.mockRestore();
+    }
+  });
+```
+
+- [ ] **Step 2: Run sync unit test to verify it passes (sync.ts already does per-id cleanup)**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/sync.test.ts`
+Expected: PASS — sync.ts already cleans up correctly. This test locks the behavior.
+
+- [ ] **Step 3: Write test verifying CLI source has no blanket closeLbug()**
+
+Add to `gitnexus/test/integration/group/group-cli.test.ts`:
+
+```typescript
+  it('test_sync_command_source_does_not_call_blanket_closeLbug', () => {
+    const cliGroupPath = path.join(repoRoot, 'src', 'cli', 'group.ts');
+    const source = fs.readFileSync(cliGroupPath, 'utf-8');
+
+    // closeLbug() without arguments (blanket close) must not appear.
+    // closeLbug(id) with argument is fine (that's in sync.ts, not here).
+    // Match closeLbug() but not closeLbug(someArg)
+    const blanketClosePattern = /closeLbug\s*\(\s*\)/;
+    expect(source).not.toMatch(blanketClosePattern);
+  });
+```
+
+- [ ] **Step 4: Run test to verify it fails**
+
+Run: `cd gitnexus && npx vitest run test/integration/group/group-cli.test.ts`
+Expected: FAIL — `closeLbug()` (no args) exists at line 188.
+
+- [ ] **Step 5: Remove blanket closeLbug() from cli/group.ts**
+
+In `gitnexus/src/cli/group.ts`:
+
+Remove the `closeLbug` import at line 160:
+```typescript
+      const { closeLbug } = await import('../core/lbug/pool-adapter.js');
+```
+
+Replace the try/finally wrapper (lines 162-189):
+```typescript
+      try {
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+
+        console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
+
+        const result = await syncGroup(config, {
+          groupDir,
+          allowStale: Boolean(opts.allowStale),
+          verbose: Boolean(opts.verbose),
+          skipEmbeddings: Boolean(opts.skipEmbeddings),
+          exactOnly: Boolean(opts.exactOnly),
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`\nMatching cascade:`);
+          const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
+          console.log(`  exact:     ${exactLinks.length} cross-links (confidence 1.0)`);
+          console.log(`  unmatched: ${result.unmatched.length} contracts`);
+          console.log(
+            `\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`,
+          );
+        }
+      } finally {
+        await closeLbug().catch(() => {});
+      }
+```
+
+Becomes (remove try/finally entirely, since sync.ts handles its own cleanup):
+```typescript
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+
+        console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
+
+        const result = await syncGroup(config, {
+          groupDir,
+          allowStale: Boolean(opts.allowStale),
+          verbose: Boolean(opts.verbose),
+          skipEmbeddings: Boolean(opts.skipEmbeddings),
+          exactOnly: Boolean(opts.exactOnly),
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`\nMatching cascade:`);
+          const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
+          console.log(`  exact:     ${exactLinks.length} cross-links (confidence 1.0)`);
+          console.log(`  unmatched: ${result.unmatched.length} contracts`);
+          console.log(
+            `\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`,
+          );
+        }
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/integration/group/group-cli.test.ts test/unit/group/sync.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd gitnexus && git add src/cli/group.ts test/integration/group/group-cli.test.ts test/unit/group/sync.test.ts
+git commit -m "fix(group): remove blanket closeLbug() from CLI sync command
+
+sync.ts already closes pools per-id in its finally block.
+The blanket closeLbug() in cli/group.ts tears down ALL active pools
+including unrelated ones in MCP server context.
+
+Addresses PR #626 review item 4 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: gRPC Proto Regex — Brace-Depth Counter
+
+**Files:**
+- Modify: `gitnexus/src/core/group/extractors/grpc-extractor.ts:101-130` (parseProtoFile)
+- Test: `gitnexus/test/unit/group/grpc-extractor.test.ts`
+
+- [ ] **Step 1: Write failing tests for nested braces in proto services**
+
+Add this describe block inside the existing `proto file parsing` describe in `gitnexus/test/unit/group/grpc-extractor.test.ts`:
+
+```typescript
+    it('test_extract_proto_with_google_api_http_nested_braces', async () => {
+      writeFile(
+        'api/gateway.proto',
+        `syntax = "proto3";
+package gateway.v1;
+
+import "google/api/annotations.proto";
+
+service GatewayService {
+  rpc GetUser (GetUserRequest) returns (UserResponse) {
+    option (google.api.http) = {
+      get: "/v1/users/{user_id}"
+    };
+  }
+  rpc CreateUser (CreateUserRequest) returns (UserResponse) {
+    option (google.api.http) = {
+      post: "/v1/users"
+      body: "*"
+    };
+  }
+}`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/gateway.proto',
+      );
+
+      expect(providers).toHaveLength(2);
+      const ids = providers.map((c) => c.contractId).sort();
+      expect(ids).toEqual([
+        'grpc::gateway.v1.GatewayService/CreateUser',
+        'grpc::gateway.v1.GatewayService/GetUser',
+      ]);
+    });
+
+    it('test_extract_proto_with_multiple_services', async () => {
+      writeFile(
+        'api/multi.proto',
+        `syntax = "proto3";
+package multi;
+
+service ServiceA {
+  rpc MethodA (Req) returns (Res);
+}
+
+service ServiceB {
+  rpc MethodB1 (Req) returns (Res);
+  rpc MethodB2 (Req) returns (Res);
+}`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/multi.proto',
+      );
+
+      expect(providers).toHaveLength(3);
+      const ids = providers.map((c) => c.contractId).sort();
+      expect(ids).toEqual([
+        'grpc::multi.ServiceA/MethodA',
+        'grpc::multi.ServiceB/MethodB1',
+        'grpc::multi.ServiceB/MethodB2',
+      ]);
+    });
+
+    it('test_extract_proto_with_nested_option_blocks_in_rpc', async () => {
+      writeFile(
+        'api/nested.proto',
+        `syntax = "proto3";
+package nested;
+
+service DeepService {
+  rpc DeepMethod (Req) returns (Res) {
+    option (google.api.http) = {
+      post: "/v1/deep"
+      body: "*"
+      additional_bindings {
+        get: "/v1/deep/{id}"
+      }
+    };
+  }
+}`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/nested.proto',
+      );
+
+      expect(providers).toHaveLength(1);
+      expect(providers[0].contractId).toBe('grpc::nested.DeepService/DeepMethod');
+    });
+
+    it('test_extract_proto_malformed_unclosed_brace_skips_service', async () => {
+      writeFile(
+        'api/broken.proto',
+        `syntax = "proto3";
+package broken;
+
+service IncompleteService {
+  rpc SomeMethod (Req) returns (Res);
+  // Missing closing brace — EOF before depth returns to 0
+`,
+      );
+
+      // Should not throw; incomplete service is silently skipped
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/broken.proto',
+      );
+
+      // The old regex would find partial match; the new parser should skip it
+      expect(providers).toHaveLength(0);
+    });
+```
+
+- [ ] **Step 2: Run tests to verify the nested brace test fails**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/grpc-extractor.test.ts`
+Expected: `test_extract_proto_with_google_api_http_nested_braces` FAIL — regex stops at first `}` inside the `option` block.
+
+- [ ] **Step 3: Replace serviceRe regex with extractServiceBlocks function**
+
+In `gitnexus/src/core/group/extractors/grpc-extractor.ts`, replace the `parseProtoFile` method (lines 101-130):
+
+```typescript
+  private parseProtoFile(content: string, filePath: string): ExtractedContract[] {
+    const out: ExtractedContract[] = [];
+
+    const pkgMatch = content.match(/^package\s+([\w.]+)\s*;/m);
+    const pkg = pkgMatch ? pkgMatch[1] : '';
+
+    for (const { name: serviceName, body } of extractServiceBlocks(content)) {
+      const rpcRe = /rpc\s+(\w+)\s*\(/g;
+      let rpcMatch: RegExpExecArray | null;
+      while ((rpcMatch = rpcRe.exec(body)) !== null) {
+        const methodName = rpcMatch[1];
+        const cid = contractId(pkg, serviceName, methodName);
+        out.push(
+          makeContract(cid, 'provider', filePath, `${serviceName}.${methodName}`, 0.85, {
+            package: pkg,
+            service: serviceName,
+            method: methodName,
+            source: 'proto',
+          }),
+        );
+      }
+    }
+
+    return out;
+  }
+```
+
+Add this function before the class (e.g. after `serviceOnlyContractId`, around line 26):
+
+```typescript
+function extractServiceBlocks(content: string): Array<{ name: string; body: string }> {
+  const results: Array<{ name: string; body: string }> = [];
+  const headerRe = /service\s+(\w+)\s*\{/g;
+  let headerMatch: RegExpExecArray | null;
+
+  while ((headerMatch = headerRe.exec(content)) !== null) {
+    const serviceName = headerMatch[1];
+    const bodyStart = headerMatch.index + headerMatch[0].length;
+    let depth = 1;
+    let pos = bodyStart;
+
+    while (pos < content.length && depth > 0) {
+      const ch = content[pos];
+      if (ch === '{') depth++;
+      else if (ch === '}') depth--;
+      pos++;
+    }
+
+    // If EOF before depth returns to 0, skip incomplete service
+    if (depth !== 0) continue;
+
+    // body is between opening { (consumed by regex) and closing } (pos is one past it)
+    const body = content.slice(bodyStart, pos - 1);
+    results.push({ name: serviceName, body });
+  }
+
+  return results;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/grpc-extractor.test.ts`
+Expected: ALL PASS (including existing regression tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd gitnexus && git add src/core/group/extractors/grpc-extractor.ts test/unit/group/grpc-extractor.test.ts
+git commit -m "fix(group): replace gRPC proto regex with brace-depth counter
+
+The serviceRe regex used [^}]* which stopped at the first '}'.
+Proto services with google.api.http annotations contain nested {}
+blocks, causing methods to be missed.
+
+New extractServiceBlocks() uses a brace-depth counter (init depth=1
+after opening {, scan char-by-char). Malformed protos with unclosed
+braces are silently skipped.
+
+Addresses PR #626 review item 2 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Run Full Test Suite
+
+- [ ] **Step 1: Run all group-related tests**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/ test/integration/group/`
+Expected: ALL PASS
+
+- [ ] **Step 2: Run full test suite to catch regressions**
+
+Run: `cd gitnexus && npx vitest run`
+Expected: ALL PASS, 0 failures
+
+- [ ] **Step 3: Run typecheck**
+
+Run: `cd gitnexus && npx tsc --noEmit`
+Expected: No errors
+
+---
+
+### Task 6: CLI Integration Smoke Test
+
+- [ ] **Step 1: Add CLI smoke test for path traversal**
+
+Add to `gitnexus/test/integration/group/group-cli.test.ts` inside the existing `group CLI` describe:
+
+```typescript
+  it('test_create_with_invalid_name_fails', () => {
+    const result = runGroup(['create', '../../evil']);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('Invalid group name');
+  });
+```
+
+- [ ] **Step 2: Run test**
+
+Run: `cd gitnexus && npx vitest run test/integration/group/group-cli.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd gitnexus && git add test/integration/group/group-cli.test.ts
+git commit -m "test(group): add CLI smoke test for path traversal rejection
+
+Verifies that 'group create ../../evil' fails with Invalid group name.
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
@@ -0,0 +1,175 @@
+# PR #626 HIGH-Priority Fixes Design
+
+**Date:** 2026-04-02
+**PR:** abhigyanpatwari/GitNexus#626 — Intra-repo service communication tracking
+**Scope:** 4 HIGH-priority issues identified by abhigyanpatwari and xkonjin
+**Approach:** Minimal targeted fixes (option A) — no refactoring, no scope creep
+
+---
+
+## Fix 1: Path Traversal via Group Name
+
+**File:** `gitnexus/src/core/group/storage.ts`
+**Risk:** A group name like `../../etc` creates directories outside the intended path.
+
+### Solution
+
+Add `validateGroupName(name: string): void` that enforces `/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/`.
+
+- Call in `createGroupDir` (primary entry point)
+- Call in `getGroupDir` (defense in depth)
+- Throw descriptive error on invalid names
+
+**Legacy:** Groups already on disk with names outside this pattern are not auto-renamed; only new `create` / resolved paths are validated.
+
+### Why regex over path.resolve + startsWith
+
+- abhigyanpatwari explicitly requested `[a-zA-Z0-9_-]`
+- Stricter: disallows spaces, dots, Unicode edge cases
+- Simpler to reason about
+
+### Tests
+
+- `../../evil` throws
+- `foo/bar` throws
+- Empty string throws
+- `my-group_01` passes
+- `A` (single char) passes
+- CLI smoke: one integration test that hits `getGroupDir` / `createGroupDir` (e.g. `group create` or `group add`) with an invalid name proves wiring for every subcommand that resolves a group through storage
+
+### CLI/API entry points accepting groupName
+
+All paths flow through `getGroupDir` (which validates), so coverage is implicit. For reference:
+
+| Command | Entry | Calls |
+|---------|-------|-------|
+| `group create` | `cli/group.ts` action | `createGroupDir` -> `getGroupDir` |
+| `group add` | `cli/group.ts` action | `getGroupDir` |
+| `group remove` | `cli/group.ts` action | `getGroupDir` |
+| `group list` | `cli/group.ts` action | reads `groups/` dir directly — no traversal risk (reads, not writes) |
+| `group status` | `cli/group.ts` action | `getGroupDir` |
+| `group sync` | `cli/group.ts` action | `getGroupDir` |
+
+**`listGroups`:** Reads directory names from disk without validation. Not a write path, so no traversal risk. May surface manually-created directories with non-conforming names — accepted as-is, not in scope.
+
+---
+
+## Fix 2: gRPC Proto Regex -> Brace-Depth Counter
+
+**File:** `gitnexus/src/core/group/extractors/grpc-extractor.ts`
+**Risk:** `serviceRe = /service\s+(\w+)\s*\{([^}]*)}/gs` stops at first `}`. Proto services with `google.api.http` annotations inside RPCs contain nested `{ }` blocks.
+
+### Solution
+
+Replace `serviceRe` regex with `extractServiceBlocks(content: string): Array<{ name: string; body: string }>`:
+
+1. Use regex only to find `service <Name> {` start positions (regex consumes the opening `{`)
+2. Initialise depth to 1 immediately after the opening `{`
+3. Scan forward char by char: `{` -> depth++, `}` -> depth--; collect into body
+4. Stop when depth reaches 0 (the matching closing `}`)
+5. Return name + body pairs
+
+Inner `rpcRe` regex remains unchanged — it operates on the already-extracted body.
+
+**Malformed input:** If EOF is reached before `depth` returns to 0, skip the incomplete service (do not add to results). Lock this in the test.
+
+**Scope limitation (v1):** Brace-depth only — no lexer for string literals or comments containing `{`/`}`. Sufficient for `google.api.http` annotations. Known false positive: braces inside `//` comments or quoted strings within proto options. Accepted for v1; a proper proto lexer is out of scope.
+
+### Tests
+
+- Proto with single service, no nesting (regression)
+- Proto with `google.api.http` nested braces inside RPC options
+- Proto with multiple services
+- Proto with nested `option` blocks inside RPC (e.g. `google.api.http`)
+- Malformed proto with unclosed brace (graceful handling)
+
+---
+
+## Fix 3: Directory Exclusions in Service Boundary Detector
+
+**File:** `gitnexus/src/core/group/service-boundary-detector.ts`
+**Risk:** Walks entire repo tree, only skipping dotfiles and `node_modules`. Extremely slow on repos with `vendor/`, `target/`, `__pycache__/`, `.venv/`.
+
+### Solution
+
+Create `EXCLUDED_DIRS` as a `Set<string>` (alongside existing `SERVICE_MARKERS`, `SOURCE_EXTENSIONS`), for example:
+
+```text
+node_modules, vendor, target, build, dist,
+__pycache__, .venv, venv, .tox, .mypy_cache,
+.gradle, .mvn, out, bin
+```
+
+(Implement as `new Set([...])` — the list above is the membership, not a string literal.)
+
+Apply in both:
+- `walkForBoundaries` (line 77-78) — replace current inline `=== 'node_modules'` check with `EXCLUDED_DIRS.has(entry.name)`
+- `hasSourceFilesInSubdirs` (line 130) — replace `entry.name !== 'node_modules'` with `!EXCLUDED_DIRS.has(entry.name)`
+
+Note: remove the old `=== 'node_modules'` literal from both locations — it is covered by `EXCLUDED_DIRS`.
+Dotfile exclusion (`.` prefix) remains as a separate check since it's a pattern, not a name.
+Exclusions apply only to `isDirectory()` entries — file names are never checked against `EXCLUDED_DIRS`.
+
+**Tradeoff:** Rare layouts that keep source under names like `out/` or `bin/` will be skipped; accepted for performance on typical monorepos.
+
+**Case sensitivity:** `Set.has` is case-sensitive (matches current `=== 'node_modules'` behavior). Windows case-insensitive FS not handled — accepted as-is, consistent with existing code.
+
+### Tests
+
+- Directory named `vendor/` is skipped
+- Directory named `target/` is skipped
+- Directory named `__pycache__/` is skipped
+- Regular source directories are NOT skipped
+- Dotfile directories still skipped (regression)
+
+---
+
+## Fix 4: Double-Close of LadybugDB Pools
+
+**Files:**
+- `gitnexus/src/core/group/sync.ts` (lines 155-157) — per-id cleanup (KEEP)
+- `gitnexus/src/cli/group.ts` (line 188) — blanket `closeLbug()` (REMOVE)
+
+**Risk:** In MCP server context, `closeLbug()` without arguments tears down ALL active pools, including ones from unrelated operations.
+
+### Solution
+
+Remove the `closeLbug()` call (no arguments) from `cli/group.ts` finally block. The per-id cleanup in `sync.ts` is sufficient:
+
+```typescript
+// sync.ts — KEEP: cleans up only pools opened by this sync
+finally {
+  for (const id of [...new Set(openPoolIds)]) {
+    await closeLbug(id).catch(() => {});
+  }
+}
+```
+
+```typescript
+// cli/group.ts — REMOVE: blanket close that kills all pools
+finally {
+  await closeLbug().catch(() => {});  // DELETE THIS
+}
+```
+
+Remove the `closeLbug` import from `cli/group.ts` — after removing the `finally` call it has no remaining usages.
+
+### Tests (unit level — mock pool adapter)
+
+- `syncGroup` closes only the pools it opened (mock `closeLbug`, assert called with specific ids)
+- Two-pool scenario: sync opens pools A and B, both closed in finally; pool C (opened elsewhere) not touched
+- CLI `sync` command does not call blanket `closeLbug()` (verify no zero-arg call in source — static check or grep-based test)
+
+---
+
+## Out of Scope
+
+- JSON -> LadybugDB migration (tracked in #606)
+- MEDIUM/LOW issues (items 5-10 from review summary)
+- Test gap coverage beyond what's needed for these 4 fixes
+- Any refactoring or architectural changes
+
+## Execution Order
+
+Fixes are independent — can be implemented in parallel or any order.
+Recommended order for review clarity: 1 -> 3 -> 4 -> 2 (simplest to most complex).
@@ -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})`);
-          },
-        });
-      },
-    };
-  },
-};
@@ -3,15 +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;
@@ -144,23 +135,6 @@ export default [
    },
  },

-  // 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',
-    },
-  },
-
  // React-specific rules for gitnexus-web
  {
    files: ['gitnexus-web/src/**/*.{ts,tsx}'],
@@ -162,8 +162,8 @@ Each mode has a `system_{mode}.jinja` + `instance_{mode}.jinja` pair. The agent

 ```
 Agent → bash command → /usr/local/bin/gitnexus-query
-  → curl http://127.0.0.1:4848/tool/query   (fast path: eval-server, ~100ms)
-  → npx gitnexus query                       (fallback: cold CLI, ~5-10s)
+  → curl localhost:4848/tool/query     (fast path: eval-server, ~100ms)
+  → npx gitnexus query                 (fallback: cold CLI, ~5-10s)
 ```

 Each tool script in `/usr/local/bin/` is standalone — no sourcing, no env inheritance needed. This is critical because mini-swe-agent runs every command via `subprocess.run` in a fresh subshell.
@@ -176,61 +176,6 @@ The eval-server is a lightweight HTTP daemon that:
 - Includes next-step hints to guide tool chaining (query → context → impact → fix)
 - Auto-shuts down after idle timeout

-**CLI flags:**
-
-| Flag | Default | Purpose |
-|------|---------|---------|
-| `--port <port>` | `4848` | Port to listen on |
-| `--host <host>` | `127.0.0.1` | Bind address — use `0.0.0.0` for cross-container access |
-| `--idle-timeout <seconds>` | `0` (disabled) | Auto-shutdown after N seconds of inactivity |
-
-**READY signal:**
-
-When the server is ready, it writes to stdout:
-
-```
-# IPv4
-GITNEXUS_EVAL_SERVER_READY:127.0.0.1:4848
-
-# IPv6 (bracketed to avoid colon ambiguity)
-GITNEXUS_EVAL_SERVER_READY:[::1]:4848
-```
-
-Parse the port as the last colon-segment (`split(':').pop()`) — not `split(':')[1]`, which breaks for IPv6 and for non-loopback IPv4 hosts added in this release.
-
-### Custom port and host
-
-`run_eval.py` does not expose `--port` or `--host` as CLI flags. Configure them in your mode YAML under the `environment:` key:
-
-```yaml
-# configs/modes/native_augment.yaml (or whichever mode you're running)
-environment:
-  eval_server_port: 4849         # change if 4848 is already in use on the host
-  eval_server_host: "0.0.0.0"   # bind all interfaces — needed for cross-container setups
-```
-
-Defaults are `port: 4848` and `host: 127.0.0.1` (loopback only). Use `0.0.0.0` only when the agent container needs to reach the eval-server from a separate network namespace. The health probe and tool scripts connect via the configured bind host (defaulting to `127.0.0.1`), which is reachable for both loopback and all-interface binds.
-
-`"localhost"` is also a valid `eval_server_host` value. The OS resolves it at bind time — typically `127.0.0.1` on dual-stack or IPv4-only systems, and `::1` on IPv6-only systems. The exact result depends on your `/etc/hosts` and `gai.conf`. The READY signal will reflect the actual bound address (e.g. `GITNEXUS_EVAL_SERVER_READY:127.0.0.1:4848` or `GITNEXUS_EVAL_SERVER_READY:[::1]:4848`), not the literal string `localhost`. Use this when you want the server to bind to whichever loopback address the OS prefers rather than forcing IPv4.
-
-**Running eval-server directly in Docker / Docker Compose:**
-
-```bash
-# Bind to all interfaces so sibling containers can reach it
-gitnexus eval-server --host 0.0.0.0 --port 4848
-
-# Then probe from a sibling container via its service hostname
-curl http://eval-container:4848/health
-```
-
-If you need a non-default port (e.g. to avoid conflicts), pass `--port <port>` alongside `--host`. The READY signal will reflect both:
-
-```
-GITNEXUS_EVAL_SERVER_READY:0.0.0.0:5000
-```
-
-Parse the port as the last colon-segment (`split(':').pop()`) — safe for both IPv4 and bracketed IPv6 forms.
-
 ### Index caching

 SWE-bench repos repeat (Django has 200+ instances at different commits). The harness caches GitNexus indexes per `(repo, commit)` hash in `~/.gitnexus-eval-cache/` to avoid redundant re-indexing.
@@ -39,7 +39,6 @@ logger = logging.getLogger("gitnexus_docker")

 DEFAULT_CACHE_DIR = Path.home() / ".gitnexus-eval-cache"
 EVAL_SERVER_PORT = 4848
-EVAL_SERVER_HOST = "127.0.0.1"


 class GitNexusDockerEnvironment(DockerEnvironment):
@@ -63,7 +62,6 @@ class GitNexusDockerEnvironment(DockerEnvironment):
        skip_embeddings: bool = True,
        gitnexus_timeout: int = 120,
        eval_server_port: int = EVAL_SERVER_PORT,
-        eval_server_host: str = EVAL_SERVER_HOST,
        **kwargs,
    ):
        super().__init__(**kwargs)
@@ -72,7 +70,6 @@ class GitNexusDockerEnvironment(DockerEnvironment):
        self.skip_embeddings = skip_embeddings
        self.gitnexus_timeout = gitnexus_timeout
        self.eval_server_port = eval_server_port
-        self.eval_server_host = eval_server_host
        self.index_time: float = 0.0
        self._gitnexus_ready = False

@@ -168,29 +165,22 @@ class GitNexusDockerEnvironment(DockerEnvironment):

    def _start_eval_server(self):
        """Start the GitNexus eval-server daemon in the background."""
-        logger.info(
-            f"Starting eval-server on {self.eval_server_host}:{self.eval_server_port}..."
-        )
+        logger.info(f"Starting eval-server on port {self.eval_server_port}...")

        self.execute({
            "command": (
                f"nohup npx gitnexus eval-server --port {self.eval_server_port} "
-                f"--host {self.eval_server_host} "
                f"--idle-timeout 600 "
                f"> /tmp/gitnexus-eval-server.log 2>&1 &"
            ),
            "timeout": 5,
        })

-        # Use 127.0.0.1 for the health probe — reachable whether server binds
-        # loopback or all interfaces (0.0.0.0), avoiding DNS resolution issues.
-        health_host = "127.0.0.1"
-
        # Wait for the server to be ready (up to ~15s for KuzuDB init)
        for i in range(EVAL_SERVER_HEALTH_RETRIES):
            time.sleep(EVAL_SERVER_HEALTH_INTERVAL_SECONDS)
            health = self.execute({
-                "command": f"curl -sf http://{health_host}:{self.eval_server_port}/health 2>/dev/null || echo 'NOT_READY'",
+                "command": f"curl -sf http://127.0.0.1:{self.eval_server_port}/health 2>/dev/null || echo 'NOT_READY'",
                "timeout": EVAL_SERVER_HEALTH_TIMEOUT_SECONDS,
            })
            output = health.get("output", "").strip()
@@ -211,7 +201,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
        )

    @staticmethod
-    def _render_tool_script(spec: ToolScriptSpec, port: str, host: str = EVAL_SERVER_HOST) -> str:
+    def _render_tool_script(spec: ToolScriptSpec, port: str) -> str:
        """
        Render a standalone bash script for a GitNexus tool.

@@ -222,7 +212,6 @@ class GitNexusDockerEnvironment(DockerEnvironment):

        if spec.endpoint:
            lines.append(f'PORT="${{GITNEXUS_EVAL_PORT:-{port}}}"')
-            lines.append(f'HOST="${{GITNEXUS_EVAL_HOST:-{host}}}"')

        if spec.header:
            lines.append(spec.header.strip())
@@ -232,7 +221,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):

        if spec.endpoint:
            lines.append(
-                f'result=$(curl -sf -X POST "http://${{HOST}}:${{PORT}}{spec.endpoint}" '
+                f'result=$(curl -sf -X POST "http://127.0.0.1:${{PORT}}{spec.endpoint}" '
                '-H "Content-Type: application/json" -d "$payload" 2>/dev/null)'
            )
            lines.append('if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi')
@@ -255,10 +244,9 @@ class GitNexusDockerEnvironment(DockerEnvironment):
        Uses heredocs with quoted delimiter to avoid all quoting/escaping issues.
        """
        port = str(self.eval_server_port)
-        host = self.eval_server_host

        for spec in TOOL_SPECS.values():
-            script_content = self._render_tool_script(spec, port, host).strip()
+            script_content = self._render_tool_script(spec, port).strip()
            # Use heredoc with quoted delimiter — prevents all variable expansion and quoting issues
            self.execute({
                "command": (
@@ -399,6 +387,5 @@ class GitNexusDockerEnvironment(DockerEnvironment):
            "index_time_seconds": round(self.index_time, 2),
            "skip_embeddings": self.skip_embeddings,
            "eval_server_port": self.eval_server_port,
-            "eval_server_host": self.eval_server_host,
        }
        return base
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Gergo MagyarandClaude Opus 4.7	4d27ce26bb	fix(group): drop macro-style #include from consumer contracts Tree-sitter's `(_) @import.source` wildcard matches the identifier node of `#include PLATFORM_HEADER`, so the cleaned value `PLATFORM_HEADER` slipped past the system-header / `..` filters and was emitted as a permanently orphaned consumer contract (no file is named after a macro identifier, so no provider can ever match). Add a shape guard that skips cleaned values lacking both a path separator and an extension dot, plus regression tests for single and multi-macro files. Also document `IncludeExtractor.canExtract()` as unused by sync.ts (gated via `config.detect.includes` instead) and kept solely for ContractExtractor interface uniformity. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-09 06:49:18 +01:00
Gergo Magyar	ee39f5b448	merge: bring fix/windows-lbug-lock-retry (PR #1430 ) — closes Windows lbug lock flakes on cli-e2e Brings open-time retry for , post-close handle-release probe (main file + .wal sidecar) on Windows, schema-init lock-warning filter, and serialized lbug-db vitest project. Without this, the cli-e2e tests for cypher/query/impact intermittently fail on windows-latest because the CLI's read-only lbug open hits the documented Windows lock-acquisition race.	2026-05-08 15:24:12 +01:00
Gergo MagyarandClaude Opus 4.7	a462febad6	fix(group): use retryRename in writeContractRegistry to absorb Windows EPERM `storage.ts:62` used raw `fsp.rename` for the contracts.json atomic swap. On Windows, AV scanners and concurrent renames briefly hold the destination handle between rename calls, surfacing as EPERM/EBUSY. The `insecure-tempfile.test.ts > concurrent writes do not collide` test was flaking with `EPERM: operation not permitted, rename` on windows-latest CI. `bridge-db.ts` already has a battle-tested `retryRename(src, dst, 3)` helper used at six call sites for exactly this pattern. Reusing it here keeps the Windows-rename policy single-source-of-truth across the group package. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 15:22:19 +01:00
Gergo MagyarandClaude Opus 4.7	72f854f7de	fix(review): apply autofix feedback ce-code-review surfaced 6 safe_auto findings on commit `a9936a9b`: - T1 (testing, P2): the sync.ts:174 gate was untested with includes:false. Added a sync-level test mirroring the existing thrift-off pattern at sync.test.ts:545, asserting zero include contracts when the gate is disabled in a real syncGroup call. - T3 (testing, P3): third_party and 3rdparty entries in DEFAULT_IGNORE_LIST had no regression test. Added both to ignore-service.test.ts's dependency-directories it.each block. - M1 (maintainability, P3): discoverIndexableFiles JSDoc lacked a fork-warning relative to walkRepositoryPaths. Added a MAINTENANCE note explaining why the duplication is tolerated and the contract the two implementations must keep. - M2 (maintainability, P3): thrift-extractor still hand-rolls its ignore array with no signal that DEFAULT_IGNORE_LIST additions silently do not apply there. Added TODO(#1156-followup) comments above both call sites. - M3 (maintainability, P3): SOURCE_EXTENSIONS duplicated the four HEADER_EXTENSIONS entries with no expressed subset relationship. Spread HEADER_EXTENSIONS into SOURCE_EXTENSIONS so future header- extension additions propagate. - C1+T4 (correctness+testing, P3, cross-reviewer corroborated): discoverIndexableFiles swallowed all fs.stat errors silently, including EACCES/EMFILE/EIO. Narrowed the catch to ENOENT (the documented benign glob/stat race) and added a logger.warn for any other code so operators can spot permission/resource issues. All 629 tests pass; typecheck + prettier clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 13:44:49 +01:00
Gergo MagyarandClaude Opus 4.7	a9936a9b97	fix(group): close PR #1156 Codex adversarial findings Two HIGH findings from the Codex adversarial review on feat/group-include-extractor: 1. Default-on extraction silently changes existing groups (BLOCKER) DEFAULT_DETECT.includes was true, so any pre-existing group.yaml that omits the new field would gain a wave of include::* contracts on the next sync after upgrade. Flipped to false (opt-in). The integration test already declares includes: true explicitly so it survives unchanged; the unit extractor tests bypass parseGroupConfig entirely; the sync test uses extractorOverride. Only config-parser needed regression tests covering omitted/explicit/false variants. 2. IncludeExtractor scans outside the indexed file universe (BLOCKER) The extractor was running glob('*/', { ignore: STANDARD_IGNORES }) twice with a hand-rolled 9-pattern list, no .gitignore/.gitnexusignore honoring, and no max-file-size cap. That meant File:<path> contracts could appear for files ingestion would never index, producing cross-links group impact cannot fan out to (silent false-negatives). Refactored to a single discoverIndexableFiles() helper that mirrors walkRepositoryPaths exactly: createIgnoreFilter + getMaxFileSizeBytes, one discovery pass shared by provider and consumer paths. Dropped STANDARD_IGNORES and SOURCE_GLOB entirely. third_party and 3rdparty (the C/C++ vendored-deps conventions) were in the local ignore list but not in the canonical DEFAULT_IGNORE_LIST used by ingestion. Folded both into the canonical set rather than keep a parallel list — the whole point of the Codex finding is that two file-discovery implementations drift. Single source of truth. Tests: 5 new regression tests for the discovery alignment (.gitignore, .gitnexusignore, max-file-size on both provider and consumer paths) plus 4 for the opt-in default. All 30 include-extractor tests + the 494-test group suite + ignore-service tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 13:32:58 +01:00
Gergo MagyarandClaude Opus 4.7	fadbb32c2f	fix(group): address PR #1156 follow-up review findings Addresses two blockers and two mediums from the deep review. BLOCKER 1: Windows CI ENOTEMPTY in sync.test.ts After this PR added writeBridge() to syncGroup, the existing test "writes registry to groupDir when skipWrite is false" fails on windows-latest. LadybugDB's checkpoint thread briefly outlives closeBridgeDb, holding a Win32 lock on bridge.lbug; the test's fs.rmSync then fails with ENOTEMPTY. Switched the test cleanup to cleanupTempDir from test/helpers/test-db.ts which already tolerates EBUSY/EPERM/EACCES/ENOTEMPTY with bounded retries — same pattern used elsewhere for LadybugDB-touching tests. BLOCKER 2: Graph provider absolute-path bug extractProvidersGraph queried File.filePath from the LadybugDB graph but never stripped the repo root, so provider contract IDs ended up as include::/abs/path/foo.h while consumers emitted include::foo.h. These never matched through runExactMatch — silently producing 0 cross-links for any indexed C++ repo (the primary use case). Now passes repoPath into extractProvidersGraph and applies path.relative(); rows that resolve outside repoPath (stale absolute paths from another machine, system headers somehow indexed) are dropped instead of polluting the registry. MEDIUM: `../` relative includes produce spurious noise `#include "../foo.h"` is almost always intra-repo, but the suffix index can never match a `..`-prefixed path so it became a consumer contract no provider could satisfy. Now skipped before matching; covers both forward-slash and backslash forms. MEDIUM: writeBridge error in sync.ts propagates uncaught contracts.json is the canonical source of truth and was just written successfully when writeBridge runs. A bridge-only failure (disk full, schema error, permission denied) shouldn't mask the registry. Wrapped writeBridge in try/catch with a logger.warn surfacing the path and recovery instructions. Tests added: - extractProvidersGraph repo-relative ID generation (stub Cypher executor returns absolute paths) - extractProvidersGraph drops rows whose path resolves outside repo - `../foo.h` forward-slash skip - `..\foo.h` backslash-form skip Skipped findings: - canExtract() removal (#5, low): canExtract is part of the ContractExtractor interface; every other extractor implements the same `return true` shape. Removing it from IncludeExtractor would break the interface contract — keeping for consistency. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 13:07:21 +01:00
Gergő Magyar	28a3d99a92	Merge branch 'main' into feat/group-include-extractor	2026-05-08 11:58:16 +01:00
Gergo MagyarandClaude Opus 4.7	6ffef3ab99	chore(lbug): isDbBusyError review fixes - Drop redundant `could not set lock` term — already subsumed by `lock`. - Document the intentionally-broad matcher: graph-DB lock-shaped errors ("deadlock", "unlock failed", "lock contention", "could not open lock file") are all treated as transient. If a non-transient surfaces, tighten the matcher rather than raise the retry budget. - Add positive test cases covering those lock-shaped strings so the intent is visible and a future tightening would deliberately break these. - Fix the open-retry back-off comment: max sleep is 100+200+300+400 = 1000ms (no sleep after the final attempt), not 1.5s. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 11:33:33 +01:00
Gergő Magyar	f6a9d5f5cc	Merge branch 'main' into feat/group-include-extractor	2026-05-08 11:30:50 +01:00
Gergő Magyar	c4782e2db9	Merge branch 'main' into fix/windows-lbug-lock-retry	2026-05-08 11:28:45 +01:00
Gergő Magyar	48b01fb781	Merge branch 'main' into fix/windows-lbug-lock-retry	2026-05-08 10:38:16 +01:00
Gergő Magyar	ed4b738435	Merge branch 'main' into feat/group-include-extractor	2026-05-08 10:36:59 +01:00
Gergo MagyarandClaude Opus 4.7	11affdd797	fix(lbug): silence benign LadybugDB v0.16.1 schema-init lock warnings on Windows doInitLbug logs "⚠️ Schema creation warning: ... Could not set lock on file" on every CREATE NODE TABLE call after the first init on a given dbPath, on Windows. The lock is internal to LadybugDB v0.16.1 and is resolved before the table is created — same tolerance pattern as the existing "already exists" filter. Genuine cross-process lock contention still surfaces on the next operation through withLbugDb's retry, so filtering at the schema-init catch only suppresses noise, not signal. Also extend the safeClose Windows handle-release probe to cover the .wal sidecar (the previous Database's WAL handle was the slowest to release, surfacing as the schema-query lock contention) and switch the probe back to 'r+' so it actually detects exclusive locks. Test loop in lbug-close-handle-release.test.ts simplified to 10 plain iterations now that the underlying noise is filtered upstream. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 10:35:15 +01:00
Gergo MagyarandClaude Opus 4.7	a96455afca	refactor(lbug): drop isDbBusyError re-export, import from lbug-config directly The re-export from lbug-adapter.ts was a transitional convenience — with the matcher now living in lbug-config.ts, having two import paths for the same symbol invites future drift. Updated the two real consumers (lbug-lock-retry.test.ts, lbug-open-retry.test.ts) to import from lbug-config directly, removed the re-export equality test (now vacuous), and refreshed the explanatory comment so it no longer references a re-export pattern that doesn't exist. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 09:33:25 +01:00
Gergő Magyar	8170c7913c	Merge branch 'main' into feat/group-include-extractor	2026-05-08 09:30:17 +01:00
Gergo MagyarandClaude Opus 4.7	e6924f31a7	fix(lbug): robust Windows lock acquisition for CI integration tests LadybugDB's `new Database()` raises `Could not set lock on file` from local_file_system.cpp synchronously inside the constructor — before any query is issued, so `withLbugDb`'s query-time retry never sees it. On Windows CI this surfaces as flaky integration tests due to AV-scanner holds, libuv handle-release lag, and stale `.wal` sidecars from aborted prior runs. This change closes the gap at open time: - `openLbugConnection` now wraps `new lbug.Database()` in a bounded busy-retry (5x100ms back-off) inside `lbug-config.ts`. Errors that exhaust the budget are tagged via `LBUG_OPEN_RETRY_EXHAUSTED` so `withLbugDb`'s outer 3x retry skips re-retrying a freshly-exhausted path (eliminates the 3x5=15-attempt / ~6s tail latency). - For recognized test fixtures only (immediate-parent dir matches a known prefix AND resolves under `os.tmpdir()`), one final stale- sidecar sweep removes `.wal`/`.lock` and retries once. Production paths never enter this branch. - `safeClose` on Windows runs a bounded `fs.open` probe to absorb native handle-release lag; logs a warning if the probe exhausts so operators can spot AV interference. - `isDbBusyError` is now defined in `lbug-config.ts` as the single source of truth, re-exported from `lbug-adapter.ts` for compatibility. - New tests cover open-time retry (happy/retry/exhaust/non-busy/tag), stale-sidecar sweep (test-fixture-only, production-rejection, preserves-original-error), `isTestFixturePath` direct unit suite (accept/reject/traversal/nested/trailing-sep), and `waitForWindowsHandleRelease` (openable/ENOENT/no-leak). - The two new test files are added to vitest's existing serialized `lbug-db` project (already `fileParallelism: false`). Closes the chronic Windows CI flake on lbug-touching integration tests while preserving the existing single-writable-Database-per-process LadybugDB contract. No public API surface changed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-08 09:29:39 +01:00
Gergő Magyar	658f56be7a	Merge branch 'main' into feat/group-include-extractor	2026-05-07 22:36:19 +01:00
HuangWenjie	298c0674d5	fix(include-extractor): address PR #1156 Claude review findings #3-#7 Claude Deep Review raised 7 findings on the IncludeExtractor. #1/#2 (BLOCKERs) were fixed earlier. This commit closes the remaining five. #3 HIGH case-sensitive FS -> provider contract-id collision Document the deliberate case-folding trade-off on normalizeIncludePath (matches C/C++ convention on Windows/macOS; collapses Foo.h & foo.h on Linux). Add a unit test pinning the behavior. #4 HIGH suffixResolve short-suffix match silently drops cross-repo include When a local file ends with the same basename as an external include (e.g. local internal/api.h vs. #include "ext/api.h"), suffixResolve returned a bogus local hit and suppressed the cross-repo consumer. Replace the suffixResolve lookup inside include-extractor with a strict isLocalInclude() that only accepts full-path hits via SuffixIndex.get / getInsensitive. Callers of suffixResolve elsewhere are unaffected. Add 3 unit tests covering the regression. #5 MEDIUM regex fallback matched #include inside /* ... */ Strip block comments before running the fallback regex scan. Add a unit test. #6 MEDIUM meta.source was hard-coded to 'tree_sitter' Track the actual extraction path with an extractionSource local and write it into meta.source so downstream audits can distinguish tree-sitter parses from regex fallbacks. Add 2 unit tests. #7 MEDIUM missing end-to-end coverage Add test/integration/group/include-extractor-sync.test.ts with 3 cases exercising extractor -> syncGroup -> CrossLink (mocked contracts, mixed-case/backslash normalization, real temp repos). Tests: 21 unit + 3 integration, all green.	2026-05-07 20:50:05 +08:00
HuangWenjie	8df93ee259	style(group): reformat VALID_CONTRACT_TYPES array to satisfy prettier Adding 'include' pushed the array over prettier's 100-char limit, so prettier prefers multi-line. Apply the reformat to unbreak ci-quality/format job.	2026-05-07 19:49:47 +08:00
HuangWenjie	de6904cef8	chore: drop test/global-setup.ts + test/vitest.d.ts Upstream removed these in commit `3f0c74fe` (ladybugdb 0.16.0 upgrade). Commit `3f5d21c5` accidentally restored them during a rebase dance.	2026-05-07 19:19:30 +08:00
HuangWenjie	3f5d21c530	fix(group): close missing ); in manifest-extractor include branch The 'include' branch in ManifestExtractor.resolveSymbol was missing the closing ); for the executor() call, causing a syntax error that broke ESLint, Prettier, and the full test CI on all platforms. Reported by Claude PR review on #1156.	2026-05-07 19:06:27 +08:00
HuangWenjie	fcc4319ab9	fix: address CodeQL warnings on include-extractor - Remove unused HEADER_GLOB constant in include-extractor.ts - Use fs.mkdtempSync for secure temp dir creation in tests (CodeQL: 'Insecure temporary file')	2026-05-07 17:49:31 +08:00
WENJIE HUANG	c61ceff07b	Merge branch 'main' into feat/group-include-extractor	2026-05-07 16:39:17 +08:00
HuangWenjie	2cc66c982e	feat: add IncludeExtractor for C++ cross-repo include tracking (group)	2026-04-28 17:57:49 +08:00