release: v1.6.6-rc.73

* fix(typescript): reuse suffix index in scope resolver

Build a suffix index once per TypeScript scope-resolution pass and pass it into standard import resolution so package-style imports avoid repeated linear file-list scans.\n\nFixes #1839

* test(typescript): add wiring-level test for scope-resolver suffix index

- Test typescriptScopeResolver.resolveImportTarget directly (the real
  production entry point) with package-style, unresolvable, and relative
  imports
- Use vi.spyOn on buildSuffixIndex to verify the index is built inside
  the makeTsResolveImportTarget closure — fails if index wiring is removed
- Fix existing test to pass real file lists instead of empty arrays
  alongside the prebuilt index, matching production wiring

---------

Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: Test <test@example.com>

.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "gitnexus-marketplace",
+  "owner": {
+    "name": "GitNexus",
+    "email": "nico@gitnexus.dev"
+  },
+  "metadata": {
+    "description": "Code intelligence powered by a knowledge graph — execution flows, blast radius, and semantic search",
+    "homepage": "https://github.com/nicosxt/gitnexus"
+  },
+  "plugins": [
+    {
+      "name": "gitnexus",
+      "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."
+    }
+  ]
+}

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

@@ -0,0 +1,83 @@
+---
+name: gitnexus-cli
+description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+---
+
+# GitNexus CLI Commands
+
+All commands work via `npx` — no global install required.
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+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. |
+
+**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
+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.
+
+### clean — Delete the index
+
+```bash
+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.
+
+| Flag      | Effect                                            |
+| --------- | ------------------------------------------------- |
+| `--force` | Skip confirmation prompt                          |
+| `--all`   | Clean all indexed repos, not just the current one |
+
+### wiki — Generate documentation from the graph
+
+```bash
+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).
+
+| Flag                | Effect                                    |
+| ------------------- | ----------------------------------------- |
+| `--force`           | Force full regeneration                   |
+| `--model <model>`   | LLM model (default: minimax/minimax-m2.5) |
+| `--base-url <url>`  | LLM API base URL                          |
+| `--api-key <key>`   | LLM API key                               |
+| `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--gist`            | Publish wiki as a public GitHub Gist      |
+
+### list — Show all indexed repos
+
+```bash
+npx gitnexus list
+```
+
+Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
+
+## After Indexing
+
+1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
+2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
+
+## Troubleshooting
+
+- **"Not inside a git repository"**: Run from a directory inside a git repo
+- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

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

@@ -0,0 +1,89 @@
+---
+name: gitnexus-debugging
+description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+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. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom              | GitNexus Approach                                          |
+| -------------------- | ---------------------------------------------------------- |
+| 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           |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**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
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```

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

@@ -0,0 +1,78 @@
+---
+name: gitnexus-exploring
+description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+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 `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## Resources
+
+| Resource                                | What you get                                            |
+| --------------------------------------- | ------------------------------------------------------- |
+| `gitnexus://repo/{name}/context`        | Stats, staleness warning (~150 tokens)                  |
+| `gitnexus://repo/{name}/clusters`       | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens)              |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens)              |
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```

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

@@ -0,0 +1,64 @@
+---
+name: gitnexus-guide
+description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+---
+
+# GitNexus Guide
+
+Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema.
+
+## Always Start Here
+
+For any task involving code understanding, debugging, impact analysis, or refactoring:
+
+1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
+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 `npx gitnexus analyze` in the terminal first.
+
+## Skills
+
+| Task                                         | Skill to read       |
+| -------------------------------------------- | ------------------- |
+| Understand architecture / "How does X work?" | `gitnexus-exploring`         |
+| Blast radius / "What breaks if I change X?"  | `gitnexus-impact-analysis`   |
+| Trace bugs / "Why is X failing?"             | `gitnexus-debugging`         |
+| Rename / extract / split / refactor          | `gitnexus-refactoring`       |
+| Tools, resources, schema reference           | `gitnexus-guide` (this file) |
+| Index, status, clean, wiki CLI commands      | `gitnexus-cli`               |
+
+## Tools Reference
+
+| Tool             | What it gives you                                                        |
+| ---------------- | ------------------------------------------------------------------------ |
+| `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         |
+| `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)           |
+| `list_repos`     | Discover indexed repos                                                   |
+
+## Resources Reference
+
+Lightweight reads (~100-500 tokens) for navigation:
+
+| Resource                                       | Content                                   |
+| ---------------------------------------------- | ----------------------------------------- |
+| `gitnexus://repo/{name}/context`               | Stats, staleness check                    |
+| `gitnexus://repo/{name}/clusters`              | All functional areas with cohesion scores |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members                              |
+| `gitnexus://repo/{name}/processes`             | All execution flows                       |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace                        |
+| `gitnexus://repo/{name}/schema`                | Graph schema for Cypher                   |
+
+## Graph Schema
+
+**Nodes:** File, Function, Class, Interface, Method, Community, Process
+**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
+RETURN caller.name, caller.filePath
+```

.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gitnexus-impact-analysis
+description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] 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
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level       | Meaning                  |
+| ----- | ---------------- | ------------------------ |
+| d=1   | **WILL BREAK**   | Direct callers/importers |
+| d=2   | LIKELY AFFECTED  | Indirect dependencies    |
+| d=3   | MAY NEED TESTING | Transitive effects       |
+
+## Risk Assessment
+
+| Affected                       | Risk     |
+| ------------------------------ | -------- |
+| <5 symbols, few processes      | LOW      |
+| 5-15 symbols, 2-5 processes    | MEDIUM   |
+| >15 symbols or many processes  | HIGH     |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```

.claude/skills/gitnexus/gitnexus-pr-review/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: gitnexus-pr-review
+description: "Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \"Review this PR\", \"What does PR #42 change?\", \"Is this PR safe to merge?\""
+---
+
+# PR Review with GitNexus
+
+## When to Use
+
+- "Review this PR"
+- "What does PR #42 change?"
+- "Is this safe to merge?"
+- "What's the blast radius of this PR?"
+- "Are there missing tests for this PR?"
+- Reviewing someone else's code changes before merge
+
+## Workflow
+
+```
+1. gh pr diff <number>                                    → Get the raw diff
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})  → Map diff to affected flows
+3. For each changed symbol:
+   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 `npx gitnexus analyze` in terminal before reviewing.
+
+## Checklist
+
+```
+- [ ] Fetch PR diff (gh pr diff or git diff base...head)
+- [ ] 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?
+- [ ] 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
+```
+
+## Review Dimensions
+
+| Dimension | How GitNexus Helps |
+| --- | --- |
+| **Correctness** | `context` shows callers — are they all compatible with the change? |
+| **Blast radius** | `impact` shows d=1/d=2/d=3 dependents — anything missed? |
+| **Completeness** | `detect_changes` shows all affected flows — are they all handled? |
+| **Test coverage** | `impact({includeTests: true})` shows which tests touch changed code |
+| **Breaking changes** | d=1 upstream items that aren't updated in the PR = potential breakage |
+
+## Risk Assessment
+
+| Signal | Risk |
+| --- | --- |
+| Changes touch <3 symbols, 0-1 processes | LOW |
+| Changes touch 3-10 symbols, 2-5 processes | MEDIUM |
+| Changes touch >10 symbols or many processes | HIGH |
+| Changes touch auth, payments, or data integrity code | CRITICAL |
+| d=1 callers exist outside the PR diff | Potential breakage — flag it |
+
+## Tools
+
+**gitnexus_detect_changes** — map PR diff to affected execution flows:
+
+```
+gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+
+→ Changed: 8 symbols in 4 files
+→ Affected processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Risk: MEDIUM
+```
+
+**gitnexus_impact** — blast radius per changed symbol:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream"})
+
+→ d=1 (WILL BREAK):
+  - processCheckout (src/checkout.ts:42) [CALLS, 100%]
+  - webhookHandler (src/webhooks.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - checkoutRouter (src/routes/checkout.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_impact with tests** — check test coverage:
+
+```
+gitnexus_impact({target: "validatePayment", direction: "upstream", includeTests: true})
+
+→ Tests that cover this symbol:
+  - validatePayment.test.ts [direct]
+  - checkout.integration.test.ts [via processCheckout]
+```
+
+**gitnexus_context** — understand a changed symbol's role:
+
+```
+gitnexus_context({name: "validatePayment"})
+
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates
+→ Processes: CheckoutFlow (step 3/7), RefundFlow (step 1/5)
+```
+
+## Example: "Review PR #42"
+
+```
+1. gh pr diff 42 > /tmp/pr42.diff
+   → 4 files changed: payments.ts, checkout.ts, types.ts, utils.ts
+
+2. gitnexus_detect_changes({scope: "compare", base_ref: "main"})
+   → Changed symbols: validatePayment, PaymentInput, formatAmount
+   → Affected processes: CheckoutFlow, RefundFlow
+   → Risk: MEDIUM
+
+3. gitnexus_impact({target: "validatePayment", direction: "upstream"})
+   → d=1: processCheckout, webhookHandler (WILL BREAK)
+   → webhookHandler is NOT in the PR diff — potential breakage!
+
+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. gitnexus_context({name: "formatAmount"})
+   → Called by 12 functions — but change is backwards-compatible (added optional param)
+
+6. Review summary:
+   - MEDIUM risk — 3 changed symbols affect 2 execution flows
+   - BUG: webhookHandler calls validatePayment but isn't updated for new signature
+   - BUG: createPayment depends on PaymentInput type which changed
+   - OK: formatAmount change is backwards-compatible
+   - Tests: checkout.test.ts covers processCheckout path, but no webhook test
+```
+
+## Review Output Format
+
+Structure your review as:
+
+```markdown
+## PR Review: <title>
+
+**Risk: LOW / MEDIUM / HIGH / CRITICAL**
+
+### Changes Summary
+- <N> symbols changed across <M> files
+- <P> execution flows affected
+
+### Findings
+1. **[severity]** Description of finding
+   - Evidence from GitNexus tools
+   - Affected callers/flows
+
+### Missing Coverage
+- Callers not updated in PR: ...
+- Untested flows: ...
+
+### Recommendation
+APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
+```

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

@@ -0,0 +1,121 @@
+---
+name: gitnexus-refactoring
+description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+---
+
+# Refactoring with GitNexus
+
+## When to Use
+
+- "Rename this function safely"
+- "Extract this into a module"
+- "Split this service"
+- "Move this to a new file"
+- Any task involving renaming, extracting, splitting, or restructuring code
+
+## Workflow
+
+```
+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 `npx gitnexus analyze` in terminal.
+
+## Checklists
+
+### Rename Symbol
+
+```
+- [ ] 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: gitnexus_rename({..., dry_run: false}) — apply edits
+- [ ] gitnexus_detect_changes() — verify only expected files changed
+- [ ] Run tests for affected processes
+```
+
+### Extract Module
+
+```
+- [ ] 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
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+### Split Function/Service
+
+```
+- [ ] gitnexus_context({name: target}) — understand all callees
+- [ ] Group callees by responsibility
+- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
+- [ ] Create new functions/services
+- [ ] Update callers
+- [ ] gitnexus_detect_changes() — verify affected scope
+- [ ] Run tests for affected processes
+```
+
+## Tools
+
+**gitnexus_rename** — automated multi-file rename:
+
+```
+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}]}]
+```
+
+**gitnexus_impact** — map all dependents first:
+
+```
+gitnexus_impact({target: "validateUser", direction: "upstream"})
+→ d=1: loginHandler, apiMiddleware, testUtils
+→ Affected Processes: LoginFlow, TokenRefresh
+```
+
+**gitnexus_detect_changes** — verify your changes after refactoring:
+
+```
+gitnexus_detect_changes({scope: "all"})
+→ Changed: 8 files, 12 symbols
+→ Affected processes: LoginFlow, TokenRefresh
+→ Risk: MEDIUM
+```
+
+**gitnexus_cypher** — custom reference queries:
+
+```cypher
+MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
+RETURN caller.name, caller.filePath ORDER BY caller.filePath
+```
+
+## Risk Rules
+
+| Risk Factor         | Mitigation                                |
+| ------------------- | ----------------------------------------- |
+| Many callers (>5)   | Use gitnexus_rename for automated updates |
+| Cross-area refs     | Use detect_changes after to verify scope  |
+| String/dynamic refs | gitnexus_query to find them               |
+| External/public API | Version and deprecate properly            |
+
+## Example: Rename `validateUser` to `authenticateUser`
+
+```
+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. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
+   → Applied 12 edits across 8 files
+
+4. gitnexus_detect_changes({scope: "all"})
+   → Affected: LoginFlow, TokenRefresh
+   → Risk: MEDIUM — run tests for these flows
+```

.cursor/.gitignore

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

.cursor/index.mdc

@@ -0,0 +1,21 @@
+---
+alwaysApply: true
+---
+
+# GitNexus — Cursor project rules
+
+Last reviewed: 2026-03-24
+
+Canonical agent instructions: **[AGENTS.md](../AGENTS.md)** (GitNexus MCP rules, monorepo commands, Cursor Cloud notes). **[CLAUDE.md](../CLAUDE.md)** adds Claude Code-specific notes and points back to AGENTS.md for GitNexus.
+
+## Non-negotiables (always apply)
+
+- NEVER edit a function/class/method without running `gitnexus_impact` first.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename`.
+- NEVER commit without running `gitnexus_detect_changes()`.
+- NEVER ignore HIGH/CRITICAL risk warnings from impact analysis.
+- NEVER run `npx gitnexus analyze` without `--embeddings` if `.gitnexus/meta.json` shows stored embeddings.
+
+Full rules: **[AGENTS.md](../AGENTS.md)** (`gitnexus:start` block, Cursor Cloud section).
+
+**Rule architecture:** Prefer this file plus optional `.cursor/rules/*.mdc` globs (YAML `globs` in frontmatter). Legacy `.cursorrules` is deprecated; content lives here.

.cursor/rules/100-monorepo.mdc

@@ -0,0 +1,12 @@
+---
+globs:
+  - "gitnexus/**"
+  - "gitnexus-web/**"
+---
+
+# GitNexus build/test quick refs
+
+- CLI (`gitnexus/`): `npm test`; `npm run test:integration`; `npx tsc --noEmit`.
+- Web (`gitnexus-web/`): `npm test`; `npm run dev`; `npx tsc -b --noEmit`; `E2E=1 npx playwright test` (needs servers).
+- `npm install` in `gitnexus/` runs `prepare` (tsc build) and `postinstall` (tree-sitter patches); needs `python3`, `make`, `g++`.
+- LadybugDB locking tests may fail in containerized environments because of `/tmp` file locks (known issue, not a code bug).

.cursor/rules/200-eval.mdc

@@ -0,0 +1,14 @@
+---
+globs:
+  - "eval/**"
+---
+
+# GitNexus eval harness (Python)
+
+- **Run tests**: `cd eval && uv run pytest tests/`
+- **Run with coverage**: `cd eval && uv run coverage run -m pytest tests/ && uv run coverage report`
+- **Lint**: `cd eval && uv run ruff check .`
+- **Run eval**: `cd eval && uv run python run_eval.py --config configs/<config>.yaml`
+- Shared constants live in `eval/constants.py`; tool specs in `eval/tool_registry.py`.
+- Error logging uses `utils/errors.py` — set `GITNEXUS_EVAL_DEBUG=1` for full tracebacks.
+- Property-based tests use Hypothesis (`eval/tests/test_property_based.py`).

.cursorrules

@@ -0,0 +1,5 @@
+# Deprecated for Cursor Agent Mode
+
+Use **`.cursor/index.mdc`** (`alwaysApply: true`) for project rules. See [AGENTS.md](AGENTS.md).
+
+This file is kept only as a breadcrumb for older workflows.

.dockerignore

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

.env.example

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

.git-blame-ignore-revs

@@ -0,0 +1,5 @@
+# Prettier initial formatting (2026-03-28)
+afcc3d1523f99c77ff67c4fd1af12334660113f6
+
+# ESLint unused import removal (2026-03-28)
+1491826bc8da5436d3b1eb092d9274f2c9f028a7

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+.husky/* text eol=lf

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: abhigyanpatwari

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,86 @@
+name: Bug report
+description: Report unexpected behavior or a regression
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Goal:** capture enough context to reproduce and fix the issue quickly.
+        Use **one issue per bug**; split unrelated problems.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Where does the problem show up?
+      options:
+        - gitnexus (CLI / core / indexing / MCP server)
+        - gitnexus-web (browser UI / WASM / workers)
+        - CI / GitHub Actions
+        - Documentation / developer experience
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One sentence — what went wrong?
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What were you trying to do? Any relevant links, PRs, or commits?
+    validations:
+      required: false
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Ordered steps, sample repo or minimal case, commands run.
+      placeholder: |
+        1. …
+        2. …
+        3. …
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Node version, browser (if web), GitNexus version or commit SHA.
+      placeholder: |
+        - OS:
+        - Node:
+        - Browser (if applicable):
+        - Commit / version:
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / screenshots
+      description: Paste errors, stack traces, or attach screenshots (redact secrets).
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,74 @@
+name: Feature request
+description: Propose a new capability or improvement
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Goal:** describe the problem and desired outcome so maintainers can size and prioritize.
+        Prefer **small, shippable** requests; split large ideas into phases.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Primary part of the monorepo this relates to.
+      options:
+        - gitnexus (CLI / core / indexing / MCP server)
+        - gitnexus-web (browser UI / WASM / workers)
+        - CI / release / packaging
+        - Documentation / developer experience
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or opportunity
+      description: What pain point or gap exists today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should happen instead? User-visible behavior, APIs, or UX.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you considered and why this one is preferred.
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Testable conditions for “done” (bullets or checkboxes in prose).
+      placeholder: |
+        - When … then …
+        - Documentation / tests updated where appropriate
+    validations:
+      required: false
+
+  - type: textarea
+    id: constraints
+    attributes:
+      label: Constraints
+      description: Compatibility, performance, security, or “must not change” boundaries.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: willing
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to open a PR for this (may need design discussion first).
+          required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,52 @@
+## Summary
+
+<!-- One or two sentences: what does this PR change? -->
+
+## Motivation / context
+
+<!-- Why is this change needed? Link issues, ADRs, or prior discussion. -->
+
+## Areas touched
+
+<!-- Check all that apply -->
+
+- [ ] `gitnexus/` (CLI / core / MCP server)
+- [ ] `gitnexus-web/` (Vite / React UI)
+- [ ] `.github/` (workflows, actions)
+- [ ] `eval/` or other tooling
+- [ ] Docs / agent config only (`AGENTS.md`, `CLAUDE.md`, `.cursor/`, `llms.txt`, etc.)
+
+## Scope & constraints
+
+**In scope**
+
+- <!-- bullets -->
+
+**Explicitly out of scope / not done here**
+
+- <!-- bullets — prevents reviewers assuming missing work is an oversight -->
+
+## Implementation notes
+
+<!-- Optional: design choices, tradeoffs, follow-ups -->
+
+## Testing & verification
+
+<!-- What you ran; paste commands. Omit sections that do not apply. -->
+
+- [ ] `cd gitnexus && npm test`
+- [ ] `cd gitnexus && npm run test:integration` *(if core/indexing/MCP paths changed)*
+- [ ] `cd gitnexus && npx tsc --noEmit`
+- [ ] `cd gitnexus-web && npm test` *(if web changed)*
+- [ ] `cd gitnexus-web && npx tsc -b --noEmit` *(if web changed)*
+- [ ] Manual / Playwright E2E *(note environment — see `gitnexus-web/e2e/`)*
+
+## Risk & rollout
+
+<!-- Breaking changes, migrations, index refresh (`npx gitnexus analyze`), release notes -->
+
+## Checklist
+
+- [ ] PR body meets repo minimum length (workflow may label short descriptions)
+- [ ] If `AGENTS.md` / overlays changed: headers, scope block, and changelog updated per project conventions
+- [ ] No secrets, tokens, or machine-specific paths committed

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

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

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

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

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

@@ -0,0 +1,33 @@
+name: Setup GitNexus
+description: Setup Node.js 22, install dependencies, and optionally build
+
+inputs:
+  build:
+    description: Whether to run npm run build after install
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with:
+        node-version: 22
+        cache: npm
+        cache-dependency-path: gitnexus/package-lock.json
+
+    - name: Build gitnexus-shared
+      run: npm install && npm run build
+      shell: bash
+      working-directory: gitnexus-shared
+
+    - name: Install dependencies
+      run: npm ci
+      shell: bash
+      working-directory: gitnexus
+
+    - name: Build
+      if: ${{ inputs.build == 'true' }}
+      run: npm run build
+      shell: bash
+      working-directory: gitnexus

.github/dependabot.yml

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

.github/release-drafter.yml

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

.github/release.yml

@@ -0,0 +1,45 @@
+changelog:
+  exclude:
+    labels:
+      - chore
+    authors:
+      - dependabot
+      - dependabot[bot]
+  categories:
+    - title: "\U0001F6A8 Security"
+      labels:
+        - security
+    - title: "\U0001F4A5 Breaking Changes"
+      labels:
+        - breaking
+    - title: "\U0001F680 Features"
+      labels:
+        - enhancement
+    - title: "\U0001F41B Bug Fixes"
+      labels:
+        - bug
+    - title: "\U0001F3CE\uFE0F Performance"
+      labels:
+        - performance
+    - title: "\U0001F9EA Tests"
+      labels:
+        - test
+    - title: "\U0001F504 Refactoring"
+      labels:
+        - refactor
+    - title: "\U0001F477 CI/CD"
+      labels:
+        - ci
+    - title: "\U0001F4E6 Dependencies"
+      labels:
+        - dependencies
+    - title: "\U0001F4DD Other Changes"
+      labels:
+        - '*'
+      exclude:
+        labels:
+          - dependencies
+          - ci
+          - test
+          - refactor
+          - chore

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

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

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

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

.github/scripts/triage/embedding_utils.py

@@ -0,0 +1,257 @@
+"""Pure math utilities for triage sweep embedding analysis.
+
+All functions are stateless and perform no I/O (except model loading by FastEmbed).
+Each function operates on numpy arrays and returns numpy arrays or plain Python types.
+"""
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+from fastembed import TextEmbedding
+from sklearn.decomposition import PCA
+from sklearn.covariance import EllipticEnvelope
+from sklearn.metrics.pairwise import cosine_similarity
+
+# FastEmbed model — BAAI/bge-small-en-v1.5 produces 384-dimensional embeddings.
+# ~46MB quantized ONNX, runs on CPU in ~0.5s per batch of 32.
+EMBEDDING_MODEL: str = "BAAI/bge-small-en-v1.5"
+
+# Embedding dimensionality (determined by model choice).
+EMBEDDING_DIM: int = 384
+
+# Batch size for FastEmbed. 32 balances memory and throughput on
+# a 2-vCPU GitHub Actions runner with ~7GB RAM.
+EMBEDDING_BATCH_SIZE: int = 32
+
+
+def embed_texts(texts: list[str]) -> NDArray[np.float32]:
+    """Embed a list of texts into dense vectors using FastEmbed.
+
+    Returns an array of shape (len(texts), 384) with dtype float32.
+    Empty input returns a (0, 384) array.
+    """
+    if not texts:
+        return np.empty((0, EMBEDDING_DIM), dtype=np.float32)
+
+    model = TextEmbedding(model_name=EMBEDDING_MODEL)
+    vectors = list(model.embed(texts, batch_size=EMBEDDING_BATCH_SIZE))
+    return np.vstack(vectors).astype(np.float32)
+
+
+def normalize_rows(matrix: NDArray[np.float32]) -> NDArray[np.float32]:
+    """L2-normalize each row to unit length.
+
+    Zero-norm rows (e.g. from empty text) remain zero vectors.
+    Uses eps=1e-10 in the denominator to avoid division by zero.
+    """
+    if matrix.shape[0] == 0:
+        return matrix
+
+    norms = np.linalg.norm(matrix, axis=1, keepdims=True)
+    return matrix / (norms + 1e-10)
+
+
+def reduce_dimensions(
+    matrix: NDArray[np.float32],
+    max_components: int,
+) -> NDArray[np.float32]:
+    """Reduce dimensionality via PCA.
+
+    Computes n_components = min(max_components, n-1, d). If n_components < 1,
+    returns the matrix unchanged. Logs explained variance for observability.
+    """
+    n, d = matrix.shape
+    if n <= 1:
+        return matrix
+
+    n_components = min(max_components, n - 1, d)
+    if n_components < 1:
+        return matrix
+
+    pca = PCA(n_components=n_components)
+    reduced = pca.fit_transform(matrix)
+    explained = pca.explained_variance_ratio_.sum()
+    print(f"PCA: {d}d -> {n_components}d, explained variance: {explained:.3f}")
+    return reduced.astype(np.float32)
+
+
+def detect_outliers(
+    matrix: NDArray[np.float32],
+    contamination: float = 0.1,
+    iqr_multiplier: float = 3.0,
+    max_outlier_pct: float = 0.05,
+) -> list[tuple[int, float]]:
+    """Flag items whose Mahalanobis distance exceeds an IQR-based cutoff.
+
+    Uses EllipticEnvelope (robust covariance via MCD) to estimate the
+    multivariate Gaussian, then computes sqrt(squared Mahalanobis distance)
+    for each sample. The cutoff is Q75 + iqr_multiplier * IQR, which
+    adapts to the actual distribution of distances.
+
+    A hard cap ensures no more than max_outlier_pct * n items are flagged;
+    when the cap is hit, only the most extreme items (sorted by distance
+    descending) are kept.
+
+    Returns (index, distance) tuples sorted by index ascending, along with
+    the cutoff value stored as an attribute on the returned list.
+    """
+    n = matrix.shape[0]
+    if n < 2:
+        return []
+
+    envelope = EllipticEnvelope(contamination=contamination, random_state=42)
+    envelope.fit(matrix)
+
+    # .mahalanobis() returns squared Mahalanobis distances
+    distances = np.sqrt(envelope.mahalanobis(matrix))
+
+    # IQR-based cutoff
+    q25, q75 = np.percentile(distances, [25, 75])
+    iqr = q75 - q25
+    cutoff = q75 + iqr_multiplier * iqr
+
+    outlier_mask = distances > cutoff
+    indices = np.where(outlier_mask)[0]
+
+    # Hard cap: keep at most max_outlier_pct * n items
+    max_count = max(1, int(max_outlier_pct * n))
+    if len(indices) > max_count:
+        # Sort by distance descending, take the most extreme
+        sorted_by_dist = sorted(indices, key=lambda i: distances[i], reverse=True)
+        indices = np.array(sorted_by_dist[:max_count])
+
+    # Sort by index ascending for stable output
+    indices = np.sort(indices)
+    result = [(int(idx), float(distances[idx])) for idx in indices]
+
+    # Attach cutoff as metadata so the report can use it
+    result = _OutlierResult(result)  # type: ignore[assignment]
+    result.cutoff = float(cutoff)  # type: ignore[attr-defined]
+    return result  # type: ignore[return-value]
+
+
+class _OutlierResult(list):
+    """A list subclass that carries metadata (cutoff) from outlier detection."""
+    cutoff: float = 0.0
+
+
+def find_duplicate_pairs(
+    matrix: NDArray[np.float32],
+    threshold: float,
+) -> list[tuple[int, int, float]]:
+    """Find pairs of items with cosine similarity above threshold.
+
+    Returns (i, j, similarity) tuples where i < j. The input should be
+    L2-normalized embeddings (full dimensionality, not PCA-reduced) so
+    cosine similarity equals the dot product.
+    """
+    n = matrix.shape[0]
+    if n <= 1:
+        return []
+
+    sim_matrix = cosine_similarity(matrix)
+    # Upper triangle indices (i < j), excluding diagonal
+    rows, cols = np.triu_indices(n, k=1)
+    similarities = sim_matrix[rows, cols]
+
+    mask = similarities > threshold
+    pairs: list[tuple[int, int, float]] = []
+    for idx in np.where(mask)[0]:
+        pairs.append((int(rows[idx]), int(cols[idx]), float(similarities[idx])))
+
+    return pairs
+
+
+# ── Label suggestion via z-score normalized embedding similarity ──────
+
+# Z-score threshold: a label must be this many standard deviations above
+# the column mean to be considered a match.
+LABEL_Z_THRESHOLD: float = 1.5
+
+# Margin gate: the top-1 label must beat the second-best by this many
+# z-score units to be accepted (subsequent labels don't need a margin).
+LABEL_Z_MARGIN: float = 0.5
+
+# Floor for per-column standard deviation to avoid division by near-zero.
+LABEL_Z_STD_FLOOR: float = 0.01
+
+# Minimum raw cosine similarity required even if z-score is high.
+# Prevents suggesting labels that are "relatively best" but still poor.
+MIN_RAW_SIMILARITY: float = 0.3
+
+# Maximum number of labels to suggest per item.
+MAX_LABELS_PER_ITEM: int = 3
+
+
+def suggest_labels(
+    item_embeddings: NDArray[np.float32],
+    label_embeddings: NDArray[np.float32],
+    label_names: list[str],
+    z_threshold: float = LABEL_Z_THRESHOLD,
+    z_margin: float = LABEL_Z_MARGIN,
+    std_floor: float = LABEL_Z_STD_FLOOR,
+    min_raw_sim: float = MIN_RAW_SIMILARITY,
+    max_per_item: int = MAX_LABELS_PER_ITEM,
+) -> list[list[tuple[str, float]]]:
+    """Suggest labels for each item using z-score normalized similarity.
+
+    1. Compute raw cosine similarity matrix (n items x m labels).
+    2. Column-wise z-score: for each label j, normalize across all items.
+    3. For each item, rank labels by z-score descending.
+    4. Accept a label only if z >= z_threshold AND raw_sim >= min_raw_sim.
+    5. Margin gate: the top-1 label must beat #2 by z_margin; subsequent
+       labels don't need a margin.
+    6. Cap at max_per_item.
+
+    Returns a list of length n, where each element is a list of
+    (label_name, raw_similarity) tuples. Empty list if nothing qualifies.
+    """
+    n = item_embeddings.shape[0]
+    m = label_embeddings.shape[0]
+    if n == 0 or m == 0:
+        return [[] for _ in range(n)]
+
+    # (n, m) raw similarity matrix
+    sim_matrix = cosine_similarity(item_embeddings, label_embeddings)
+
+    # Column-wise z-score normalization
+    col_means = sim_matrix.mean(axis=0)  # shape (m,)
+    col_stds = sim_matrix.std(axis=0)    # shape (m,)
+    col_stds = np.maximum(col_stds, std_floor)
+    z_matrix = (sim_matrix - col_means) / col_stds
+
+    suggestions: list[list[tuple[str, float]]] = []
+    for i in range(n):
+        z_row = z_matrix[i]
+        raw_row = sim_matrix[i]
+
+        # Rank labels by z-score descending
+        ranked = np.argsort(z_row)[::-1]
+
+        item_labels: list[tuple[str, float]] = []
+
+        # Margin gate: top-1 z-score must beat #2 by z_margin.
+        # If not, the assignment is ambiguous — skip this item entirely.
+        if len(ranked) > 1:
+            top1_z = float(z_row[ranked[0]])
+            top2_z = float(z_row[ranked[1]])
+            if top1_z - top2_z < z_margin:
+                suggestions.append(item_labels)
+                continue
+
+        for rank_pos, idx in enumerate(ranked):
+            if len(item_labels) >= max_per_item:
+                break
+
+            z_val = float(z_row[idx])
+            raw_val = float(raw_row[idx])
+
+            # Must pass both z-threshold and raw similarity floor
+            if z_val < z_threshold or raw_val < min_raw_sim:
+                continue
+
+            item_labels.append((label_names[idx], raw_val))
+
+        suggestions.append(item_labels)
+
+    return suggestions

.github/scripts/triage/requirements.txt

@@ -0,0 +1,4 @@
+fastembed>=0.5.0
+numpy>=1.26.0
+scikit-learn>=1.4.0
+scipy>=1.10.0

.github/scripts/triage/sweep.py

@@ -0,0 +1,600 @@
+"""Triage sweep: fetch open issues/PRs, detect outliers and duplicates, generate a report.
+
+Entrypoint script for the triage-sweep workflow. Fetches all open items via
+the GitHub REST API, delegates embedding and analysis to embedding_utils,
+generates a markdown report, and optionally creates a report issue.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+import urllib.parse
+from typing import TypedDict
+from datetime import datetime, timezone
+
+from embedding_utils import (
+    embed_texts,
+    normalize_rows,
+    reduce_dimensions,
+    detect_outliers,
+    find_duplicate_pairs,
+    suggest_labels,
+    LABEL_Z_THRESHOLD,
+    LABEL_Z_MARGIN,
+    LABEL_Z_STD_FLOOR,
+    MIN_RAW_SIMILARITY,
+    MAX_LABELS_PER_ITEM,
+)
+
+# ── Thresholds (overridable via workflow_dispatch inputs) ──────────────
+
+# IQR multiplier for outlier cutoff: cutoff = Q75 + IQR_MULTIPLIER * IQR.
+IQR_MULTIPLIER: float = float(os.environ.get("INPUT_IQR_MULTIPLIER", "3.0"))
+
+# Hard cap: at most this fraction of items can be flagged as outliers.
+MAX_OUTLIER_PCT: float = float(os.environ.get("INPUT_MAX_OUTLIER_PCT", "0.05"))
+
+# EllipticEnvelope contamination: expected fraction of outliers in the data.
+# Governs how aggressively the robust covariance downweights extreme points.
+CONTAMINATION: float = float(os.environ.get("INPUT_CONTAMINATION", "0.1"))
+
+# Cosine similarity above which two items are flagged as duplicates.
+# 0.92 catches near-identical issues while tolerating paraphrasing.
+COSINE_THRESHOLD: float = float(os.environ.get("INPUT_COSINE_THRESHOLD", "0.92"))
+
+# Hard cap on items to process. Prevents runaway costs on very large repos.
+MAX_ITEMS: int = int(os.environ.get("INPUT_MAX_ITEMS", "500"))
+
+# When true, print report to stdout/file but do not create a GitHub issue.
+DRY_RUN: bool = os.environ.get("INPUT_DRY_RUN", "false").lower() == "true"
+
+# ── Fixed constants (not user-configurable) ───────────────────────────
+
+# Minimum number of samples required for EllipticEnvelope to fit
+# a Gaussian reliably. Must be >= 3 * PCA_MAX_COMPONENTS so the
+# covariance matrix is estimated from enough data points.
+PCA_MAX_COMPONENTS: int = 20
+MIN_SAMPLES_FOR_OUTLIER_DETECTION: int = 100
+
+# Max character length for embedding input text. bge-small-en-v1.5 has a
+# 512-token context window (~4 chars/token). We keep title + body under
+# this limit so the model sees the full text instead of silently truncating.
+MAX_EMBED_CHARS: int = 2000
+
+# GitHub REST API page size (max allowed is 100).
+API_PAGE_SIZE: int = 100
+
+# Report issue label.
+REPORT_LABEL: str = "triage-report"
+
+# Report file path (written for the summary step to pick up).
+REPORT_FILE: str = "/tmp/triage-report.md"
+
+
+class TriageItem(TypedDict):
+    """One open issue or PR, with only the fields we need."""
+    number: int
+    title: str
+    html_url: str
+    is_pr: bool
+    labels: list[str]
+    created_at: str
+    # title + body concatenated, used as embedding input
+    text: str
+
+
+def github_api_get(path: str) -> list[dict]:
+    """Make a single authenticated GET request to the GitHub REST API.
+
+    Reads GITHUB_TOKEN and GITHUB_REPOSITORY from env. Raises SystemExit
+    with the HTTP status and response body on any non-2xx response.
+    """
+    token = os.environ["GITHUB_TOKEN"]
+    repo = os.environ["GITHUB_REPOSITORY"]
+    url = f"https://api.github.com/repos/{repo}{path}"
+
+    req = urllib.request.Request(url)
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("X-GitHub-Api-Version", "2022-11-28")
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        print(f"::error::GitHub API {e.code}: {body}")
+        sys.exit(1)
+
+
+def fetch_all_open_items() -> list[TriageItem]:
+    """Paginate through all open issues and PRs.
+
+    Returns up to MAX_ITEMS TriageItem dicts. Items with a pull_request
+    key are marked is_pr=True. The text field is title + body concatenated.
+    """
+    items: list[TriageItem] = []
+    page = 1
+
+    while len(items) < MAX_ITEMS:
+        path = (
+            f"/issues?state=open&per_page={API_PAGE_SIZE}"
+            f"&sort=created&direction=desc&page={page}"
+        )
+        data = github_api_get(path)
+
+        if not data:
+            break
+
+        for raw in data:
+            if len(items) >= MAX_ITEMS:
+                break
+
+            body = raw.get("body", "") or ""
+            full_text = f"{raw['title']}\n\n{body}"
+            # Truncate to fit the embedding model's token window.
+            # Title is always preserved; body gets clipped if needed.
+            if len(full_text) > MAX_EMBED_CHARS:
+                full_text = full_text[:MAX_EMBED_CHARS]
+            items.append(TriageItem(
+                number=raw["number"],
+                title=raw["title"],
+                html_url=raw["html_url"],
+                is_pr="pull_request" in raw,
+                labels=[lbl["name"] for lbl in raw.get("labels", [])],
+                created_at=raw["created_at"],
+                text=full_text,
+            ))
+
+        if len(data) < API_PAGE_SIZE:
+            break
+
+        page += 1
+
+    return items
+
+
+class RepoLabel(TypedDict):
+    """A label from the repo with its embedding text."""
+    name: str
+    description: str
+    # "name: description" concatenated for embedding
+    text: str
+
+
+def fetch_repo_labels() -> list[RepoLabel]:
+    """Fetch all labels from the repository, paginating if needed.
+
+    Returns labels with name, description, and a text field suitable
+    for embedding ("name: description"). Labels with no description
+    use just the name.
+    """
+    labels: list[RepoLabel] = []
+    page = 1
+
+    while True:
+        data = github_api_get(f"/labels?per_page={API_PAGE_SIZE}&page={page}")
+        for raw in data:
+            name = raw["name"]
+            desc = raw.get("description", "") or ""
+            text = f"{name}: {desc}" if desc else name
+            labels.append(RepoLabel(name=name, description=desc, text=text))
+
+        if len(data) < API_PAGE_SIZE:
+            break
+        page += 1
+
+    return labels
+
+
+def apply_labels_to_item(item_number: int, labels: list[str]) -> None:
+    """Add labels to a single issue/PR via the GitHub API.
+
+    Skips silently if labels list is empty. Uses POST which adds labels
+    without removing existing ones.
+    """
+    if not labels:
+        return
+
+    token = os.environ["GITHUB_TOKEN"]
+    repo = os.environ["GITHUB_REPOSITORY"]
+    url = f"https://api.github.com/repos/{repo}/issues/{item_number}/labels"
+
+    payload = json.dumps({"labels": labels}).encode("utf-8")
+    req = urllib.request.Request(url, data=payload, method="POST")
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("X-GitHub-Api-Version", "2022-11-28")
+    req.add_header("Content-Type", "application/json")
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            resp.read()
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        # Non-fatal: log warning but don't abort the sweep
+        print(f"::warning::Failed to label #{item_number}: {e.code} {body}")
+
+
+def _item_age(created_at: str) -> str:
+    """Compute a human-readable age string from an ISO 8601 created_at timestamp."""
+    try:
+        created = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+        delta = datetime.now(timezone.utc) - created
+        days = delta.days
+        if days < 1:
+            return "<1d"
+        if days < 30:
+            return f"{days}d"
+        if days < 365:
+            return f"{days // 30}mo"
+        return f"{days // 365}y"
+    except (ValueError, TypeError):
+        return "?"
+
+
+def _suggested_action(a: TriageItem, b: TriageItem) -> str:
+    """Determine a suggested action for a duplicate pair based on types and age."""
+    if a["is_pr"] and b["is_pr"]:
+        return "Review for overlap"
+    if not a["is_pr"] and not b["is_pr"]:
+        # Both issues — close the newer one
+        try:
+            a_dt = datetime.fromisoformat(a["created_at"].replace("Z", "+00:00"))
+            b_dt = datetime.fromisoformat(b["created_at"].replace("Z", "+00:00"))
+            newer = b if b_dt > a_dt else a
+        except (ValueError, TypeError):
+            newer = b
+        return f"Close #{newer['number']} as duplicate"
+    # One issue, one PR
+    return "Link PR to issue"
+
+
+def generate_report(
+    items: list[TriageItem],
+    outlier_results: list[tuple[int, float]],
+    duplicate_pairs: list[tuple[int, int, float]],
+    label_suggestions: list[list[tuple[str, float]]] | None = None,
+) -> str:
+    """Generate a structured markdown triage report."""
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+    repo = os.environ.get("GITHUB_REPOSITORY", "unknown/repo")
+
+    # Compute label suggestion counts early for the health table
+    outlier_set = {idx for idx, _ in outlier_results}
+    suggested_count = 0
+    if label_suggestions is not None:
+        suggested_count = sum(
+            1 for i, s in enumerate(label_suggestions)
+            if s and not items[i]["labels"] and i not in outlier_set
+        )
+
+    # ── Health summary table at the top ──────────────────────────────
+    lines: list[str] = [
+        "## Triage Sweep Report",
+        "",
+        f"**Run:** {now} UTC",
+        f"**Items analyzed:** {len(items)}",
+        f"**Thresholds:** IQR multiplier {IQR_MULTIPLIER}, Cosine > {COSINE_THRESHOLD}",
+        "",
+        "### Health Summary",
+        "",
+        "| Metric | Value |",
+        "|--------|-------|",
+        f"| Items analyzed | {len(items)} |",
+        f"| Outliers flagged | {len(outlier_results)} |",
+        f"| Duplicate pairs | {len(duplicate_pairs)} |",
+        f"| Label suggestions | {suggested_count} |",
+        "",
+    ]
+
+    # ── Outlier section ──────────────────────────────────────────────
+    # Determine cutoff for high-confidence split
+    cutoff = getattr(outlier_results, "cutoff", 0.0)
+    high_conf_cutoff = 2 * cutoff if cutoff > 0 else float("inf")
+
+    high_conf = [(idx, d) for idx, d in outlier_results if d > high_conf_cutoff]
+    borderline = [(idx, d) for idx, d in outlier_results if d <= high_conf_cutoff]
+
+    lines.extend([
+        f"### Potential Outliers / Spam ({len(outlier_results)})",
+        "",
+        "Items with unusually high Mahalanobis distance from the distribution center.",
+        "These may be spam, off-topic, or poorly described.",
+        "",
+    ])
+
+    if high_conf:
+        lines.append(f"**High Confidence** ({len(high_conf)} items, distance > 2x cutoff)")
+        lines.append("")
+        lines.append("| # | Type | Title | Distance | Age |")
+        lines.append("|---|------|-------|----------|-----|")
+        for idx, distance in high_conf:
+            item = items[idx]
+            kind = "PR" if item["is_pr"] else "Issue"
+            age = _item_age(item["created_at"])
+            title = item["title"][:80] + ("..." if len(item["title"]) > 80 else "")
+            lines.append(
+                f"| [#{item['number']}]({item['html_url']}) "
+                f"| {kind} | {title} | {distance:.2f} | {age} |"
+            )
+        lines.append("")
+
+    if borderline:
+        lines.append("<details>")
+        lines.append(f"<summary>Borderline ({len(borderline)} items)</summary>")
+        lines.append("")
+        lines.append("| # | Type | Title | Distance | Age |")
+        lines.append("|---|------|-------|----------|-----|")
+        for idx, distance in borderline:
+            item = items[idx]
+            kind = "PR" if item["is_pr"] else "Issue"
+            age = _item_age(item["created_at"])
+            title = item["title"][:80] + ("..." if len(item["title"]) > 80 else "")
+            lines.append(
+                f"| [#{item['number']}]({item['html_url']}) "
+                f"| {kind} | {title} | {distance:.2f} | {age} |"
+            )
+        lines.append("")
+        lines.append("</details>")
+        lines.append("")
+
+    if not outlier_results:
+        lines.append("None found.")
+
+    # ── Duplicate pairs section ──────────────────────────────────────
+    lines.extend([
+        "",
+        f"### Potential Duplicates ({len(duplicate_pairs)} pairs)",
+        "",
+        "Pairs of items with cosine similarity above the threshold.",
+        "",
+    ])
+
+    if duplicate_pairs:
+        lines.append("| Item A | Item B | Similarity | Suggested Action |")
+        lines.append("|--------|--------|------------|------------------|")
+        for i, j, sim in duplicate_pairs:
+            a = items[i]
+            b = items[j]
+            kind_a = "PR" if a["is_pr"] else "Issue"
+            kind_b = "PR" if b["is_pr"] else "Issue"
+            action = _suggested_action(a, b)
+            lines.append(
+                f"| [#{a['number']}]({a['html_url']}) {kind_a}: {a['title']} "
+                f"| [#{b['number']}]({b['html_url']}) {kind_b}: {b['title']} "
+                f"| {sim:.3f} | {action} |"
+            )
+    else:
+        lines.append("None found.")
+
+    # ── Label suggestions section ────────────────────────────────────
+    if label_suggestions is not None:
+        # High confidence: top-1 label with raw_sim >= 0.5
+        # Low confidence: top-1 label with raw_sim < 0.5
+        high_conf_labels: list[tuple[int, list[tuple[str, float]]]] = []
+        low_conf_labels: list[tuple[int, list[tuple[str, float]]]] = []
+        for i, sugs in enumerate(label_suggestions):
+            if sugs and not items[i]["labels"] and i not in outlier_set:
+                top1 = sugs[:1]
+                if top1[0][1] >= 0.5:
+                    high_conf_labels.append((i, top1))
+                else:
+                    low_conf_labels.append((i, top1))
+
+        total_suggestions = len(high_conf_labels) + len(low_conf_labels)
+        lines.extend([
+            "",
+            f"### Suggested Labels ({total_suggestions} unlabeled items)",
+            "",
+            "Labels suggested by z-score normalized embedding similarity against repo label descriptions.",
+            "Only shown for unlabeled items that were not flagged as outliers.",
+            "",
+        ])
+
+        # Label concentration warning
+        if total_suggestions > 0:
+            label_counts: dict[str, int] = {}
+            for _, sugs in high_conf_labels + low_conf_labels:
+                for name, _ in sugs:
+                    label_counts[name] = label_counts.get(name, 0) + 1
+            for name, count in label_counts.items():
+                if count > total_suggestions * 0.5:
+                    lines.append(
+                        f"> **Warning:** Label `{name}` accounts for "
+                        f"{count}/{total_suggestions} suggestions "
+                        f"({count * 100 // total_suggestions}%). "
+                        f"Consider reviewing label descriptions for specificity."
+                    )
+                    lines.append("")
+
+        if high_conf_labels:
+            lines.append("| # | Type | Title | Suggested Label |")
+            lines.append("|---|------|-------|--------------------|")
+            for idx, sugs in high_conf_labels:
+                item = items[idx]
+                kind = "PR" if item["is_pr"] else "Issue"
+                label_strs = [f"`{name}` ({score:.2f})" for name, score in sugs]
+                lines.append(
+                    f"| [#{item['number']}]({item['html_url']}) "
+                    f"| {kind} | {item['title']} | {', '.join(label_strs)} |"
+                )
+
+        if low_conf_labels:
+            lines.append("")
+            lines.append("<details>")
+            lines.append(f"<summary>Low-confidence suggestions ({len(low_conf_labels)} items)</summary>")
+            lines.append("")
+            lines.append("| # | Type | Title | Suggested Label |")
+            lines.append("|---|------|-------|--------------------|")
+            for idx, sugs in low_conf_labels:
+                item = items[idx]
+                kind = "PR" if item["is_pr"] else "Issue"
+                label_strs = [f"`{name}` ({score:.2f})" for name, score in sugs]
+                lines.append(
+                    f"| [#{item['number']}]({item['html_url']}) "
+                    f"| {kind} | {item['title']} | {', '.join(label_strs)} |"
+                )
+            lines.append("")
+            lines.append("</details>")
+
+        if not high_conf_labels and not low_conf_labels:
+            lines.append("No unlabeled items need suggestions.")
+
+    lines.extend([
+        "",
+        "### Summary",
+        "",
+        f"- {len(outlier_results)} outliers flagged for review",
+        f"- {len(duplicate_pairs)} duplicate pairs found",
+        f"- {len(items)} items analyzed in total",
+    ])
+
+    if label_suggestions is not None:
+        lines.append(f"- {suggested_count} items suggested for labeling")
+
+    lines.extend([
+        "",
+        "---",
+        f"*Generated by [triage-sweep](https://github.com/{repo}/actions) — no LLM was used.*",
+    ])
+
+    return "\n".join(lines)
+
+
+def create_report_issue(report_body: str) -> None:
+    """Create a GitHub issue with the triage report.
+
+    Posts to the issues API with the triage-report label.
+    Raises SystemExit on non-201 response.
+    """
+    token = os.environ["GITHUB_TOKEN"]
+    repo = os.environ["GITHUB_REPOSITORY"]
+    url = f"https://api.github.com/repos/{repo}/issues"
+
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    payload = json.dumps({
+        "title": f"Triage Sweep Report — {today}",
+        "body": report_body,
+        "labels": [REPORT_LABEL],
+    }).encode("utf-8")
+
+    req = urllib.request.Request(url, data=payload, method="POST")
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("X-GitHub-Api-Version", "2022-11-28")
+    req.add_header("Content-Type", "application/json")
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            resp_body = resp.read().decode("utf-8")
+            if resp.status != 201:
+                print(f"::error::Failed to create issue: {resp.status} {resp_body}")
+                sys.exit(1)
+            result = json.loads(resp_body)
+            print(f"Created issue: {result.get('html_url', 'unknown')}")
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        print(f"::error::Failed to create issue: {e.code} {body}")
+        sys.exit(1)
+
+
+def write_report(report: str) -> None:
+    """Write the report to the file system for the summary step."""
+    with open(REPORT_FILE, "w", encoding="utf-8") as f:
+        f.write(report)
+
+
+def main() -> None:
+    """Orchestrate the full triage sweep."""
+    # 1. Validate environment
+    for var in ("GITHUB_TOKEN", "GITHUB_REPOSITORY"):
+        if not os.environ.get(var):
+            print(f"::error::Missing required environment variable: {var}")
+            sys.exit(1)
+
+    # 2. Fetch all open issues + PRs
+    items = fetch_all_open_items()
+    print(f"Fetched {len(items)} open items")
+
+    if len(items) == 0:
+        report = "## Triage Sweep Report\n\nNo open issues or PRs found."
+        write_report(report)
+        print("No items to analyze.")
+        return
+
+    # 3. Extract texts for embedding
+    texts: list[str] = [item["text"] for item in items]
+
+    # 4. Embed all texts (returns numpy float32 array of shape [n, 384])
+    embeddings = embed_texts(texts)
+
+    # 5. L2-normalize
+    embeddings = normalize_rows(embeddings)
+
+    # 6. Outlier detection (Mahalanobis via EllipticEnvelope)
+    outlier_results: list[tuple[int, float]] = []
+    if len(items) >= MIN_SAMPLES_FOR_OUTLIER_DETECTION:
+        reduced = reduce_dimensions(embeddings, PCA_MAX_COMPONENTS)
+        outlier_results = detect_outliers(
+            reduced,
+            contamination=CONTAMINATION,
+            iqr_multiplier=IQR_MULTIPLIER,
+            max_outlier_pct=MAX_OUTLIER_PCT,
+        )
+    else:
+        print(
+            f"Skipping outlier detection: {len(items)} items < "
+            f"{MIN_SAMPLES_FOR_OUTLIER_DETECTION} minimum"
+        )
+
+    # 7. Duplicate detection (pairwise cosine similarity)
+    duplicate_pairs = find_duplicate_pairs(embeddings, COSINE_THRESHOLD)
+
+    # 8. Label suggestion via embedding similarity
+    label_suggestions: list[list[tuple[str, float]]] | None = None
+    repo_labels = fetch_repo_labels()
+    if repo_labels:
+        label_texts = [lbl["text"] for lbl in repo_labels]
+        label_names = [lbl["name"] for lbl in repo_labels]
+        label_embeddings = embed_texts(label_texts)
+        label_embeddings = normalize_rows(label_embeddings)
+        label_suggestions = suggest_labels(embeddings, label_embeddings, label_names)
+        print(f"Computed label suggestions against {len(repo_labels)} repo labels")
+
+        # NOTE: Auto-labeling is disabled. The report shows suggestions for
+        # human review. To re-enable, uncomment the block below.
+        #
+        # # Apply top label to unlabeled items (unless dry run)
+        # # Skip outliers — flagged items shouldn't get categorized
+        # outlier_set = {idx for idx, _ in outlier_results}
+        # if not DRY_RUN:
+        #     applied_count = 0
+        #     for i, sugs in enumerate(label_suggestions):
+        #         if sugs and not items[i]["labels"] and i not in outlier_set:
+        #             # Apply only the top-1 label (highest confidence)
+        #             apply_labels_to_item(items[i]["number"], [sugs[0][0]])
+        #             applied_count += 1
+        #     print(f"Applied labels to {applied_count} unlabeled items")
+    else:
+        print("No repo labels found — skipping label suggestions")
+
+    # 9. Generate report
+    report = generate_report(items, outlier_results, duplicate_pairs, label_suggestions)
+
+    # 10. Write report to file (for summary step)
+    write_report(report)
+
+    # 11. Create report issue (unless dry run)
+    if DRY_RUN:
+        print("Dry run — skipping issue creation and label application.")
+        print(report)
+    else:
+        create_report_issue(report)
+        print("Report issue created.")
+
+
+if __name__ == "__main__":
+    main()

.github/scripts/triage/test_embedding_utils.py

@@ -0,0 +1,468 @@
+"""Tests for embedding_utils.py — all embedding model calls are mocked."""
+from __future__ import annotations
+
+import sys
+from unittest.mock import patch, MagicMock
+import numpy as np
+import pytest
+
+# Mock fastembed before importing the module under test (persistent)
+if "fastembed" not in sys.modules:
+    sys.modules["fastembed"] = MagicMock()
+
+from embedding_utils import (
+    embed_texts,
+    normalize_rows,
+    reduce_dimensions,
+    detect_outliers,
+    find_duplicate_pairs,
+    suggest_labels,
+    EMBEDDING_DIM,
+    EMBEDDING_MODEL,
+    EMBEDDING_BATCH_SIZE,
+    LABEL_Z_THRESHOLD,
+    LABEL_Z_MARGIN,
+    LABEL_Z_STD_FLOOR,
+    MIN_RAW_SIMILARITY,
+    MAX_LABELS_PER_ITEM,
+)
+
+
+class TestEmbedTexts:
+    """Tests for the embed_texts function."""
+
+    def test_empty_list_returns_empty_array(self):
+        result = embed_texts([])
+        assert result.shape == (0, EMBEDDING_DIM)
+        assert result.dtype == np.float32
+
+    @patch("embedding_utils.TextEmbedding")
+    def test_single_text(self, mock_cls):
+        mock_model = MagicMock()
+        mock_cls.return_value = mock_model
+        vec = np.random.randn(EMBEDDING_DIM).astype(np.float32)
+        mock_model.embed.return_value = iter([vec])
+
+        result = embed_texts(["hello world"])
+
+        mock_cls.assert_called_once_with(model_name=EMBEDDING_MODEL)
+        mock_model.embed.assert_called_once_with(
+            ["hello world"], batch_size=EMBEDDING_BATCH_SIZE
+        )
+        assert result.shape == (1, EMBEDDING_DIM)
+        assert result.dtype == np.float32
+        np.testing.assert_array_almost_equal(result[0], vec)
+
+    @patch("embedding_utils.TextEmbedding")
+    def test_multiple_texts(self, mock_cls):
+        mock_model = MagicMock()
+        mock_cls.return_value = mock_model
+        vecs = [
+            np.random.randn(EMBEDDING_DIM).astype(np.float32)
+            for _ in range(5)
+        ]
+        mock_model.embed.return_value = iter(vecs)
+
+        result = embed_texts(["a", "b", "c", "d", "e"])
+        assert result.shape == (5, EMBEDDING_DIM)
+        assert result.dtype == np.float32
+
+
+class TestNormalizeRows:
+    """Tests for L2 row normalization."""
+
+    def test_empty_matrix(self):
+        m = np.empty((0, 10), dtype=np.float32)
+        result = normalize_rows(m)
+        assert result.shape == (0, 10)
+
+    def test_single_row(self):
+        m = np.array([[3.0, 4.0]], dtype=np.float32)
+        result = normalize_rows(m)
+        # Norm should be ~1.0
+        norm = np.linalg.norm(result[0])
+        assert abs(norm - 1.0) < 1e-5
+
+    def test_multiple_rows(self):
+        rng = np.random.default_rng(42)
+        m = rng.standard_normal((10, 50)).astype(np.float32)
+        result = normalize_rows(m)
+        norms = np.linalg.norm(result, axis=1)
+        np.testing.assert_allclose(norms, 1.0, atol=1e-5)
+
+    def test_zero_row_stays_near_zero(self):
+        m = np.array([[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]], dtype=np.float32)
+        result = normalize_rows(m)
+        # Zero row divided by eps -> very small values
+        assert np.linalg.norm(result[0]) < 1e-3
+        # Non-zero row should be unit norm
+        assert abs(np.linalg.norm(result[1]) - 1.0) < 1e-5
+
+    def test_preserves_direction(self):
+        m = np.array([[2.0, 0.0], [0.0, 3.0]], dtype=np.float32)
+        result = normalize_rows(m)
+        np.testing.assert_allclose(result[0], [1.0, 0.0], atol=1e-5)
+        np.testing.assert_allclose(result[1], [0.0, 1.0], atol=1e-5)
+
+
+class TestReduceDimensions:
+    """Tests for PCA dimensionality reduction."""
+
+    def test_single_sample_returns_unchanged(self):
+        m = np.random.randn(1, 50).astype(np.float32)
+        result = reduce_dimensions(m, 10)
+        np.testing.assert_array_equal(result, m)
+
+    def test_reduces_dimensions(self):
+        rng = np.random.default_rng(42)
+        m = rng.standard_normal((100, 50)).astype(np.float32)
+        result = reduce_dimensions(m, 10)
+        assert result.shape == (100, 10)
+        assert result.dtype == np.float32
+
+    def test_caps_at_n_minus_1(self):
+        rng = np.random.default_rng(42)
+        # 5 samples, 20 features -> max components = 4 (n-1)
+        m = rng.standard_normal((5, 20)).astype(np.float32)
+        result = reduce_dimensions(m, 50)
+        assert result.shape == (5, 4)
+
+    def test_caps_at_d(self):
+        rng = np.random.default_rng(42)
+        # 100 samples, 3 features -> max components = 3
+        m = rng.standard_normal((100, 3)).astype(np.float32)
+        result = reduce_dimensions(m, 50)
+        assert result.shape == (100, 3)
+
+    def test_max_components_respected(self):
+        rng = np.random.default_rng(42)
+        m = rng.standard_normal((50, 30)).astype(np.float32)
+        result = reduce_dimensions(m, 5)
+        assert result.shape[1] == 5
+
+
+class TestDetectOutliers:
+    """Tests for IQR-based outlier detection."""
+
+    def test_single_sample_returns_empty(self):
+        m = np.random.randn(1, 5).astype(np.float32)
+        result = detect_outliers(m)
+        assert result == []
+
+    def test_empty_returns_empty(self):
+        # n < 2 case
+        m = np.empty((0, 5), dtype=np.float32)
+        result = detect_outliers(m)
+        assert result == []
+
+    def test_finds_outliers_in_synthetic_data(self):
+        rng = np.random.default_rng(42)
+        # Create a tight cluster with one obvious outlier
+        cluster = rng.standard_normal((50, 3)).astype(np.float32) * 0.1
+        outlier = np.array([[100.0, 100.0, 100.0]], dtype=np.float32)
+        m = np.vstack([cluster, outlier])
+        result = detect_outliers(m)
+        # The outlier (index 50) should be detected
+        outlier_indices = [idx for idx, _ in result]
+        assert 50 in outlier_indices
+
+    def test_returns_list_of_index_distance_tuples(self):
+        rng = np.random.default_rng(42)
+        # Tight cluster + outlier to guarantee at least one result
+        cluster = rng.standard_normal((20, 3)).astype(np.float32) * 0.1
+        far_point = np.array([[50.0, 50.0, 50.0]], dtype=np.float32)
+        m = np.vstack([cluster, far_point])
+        result = detect_outliers(m)
+        assert isinstance(result, list)
+        for item in result:
+            assert isinstance(item, tuple)
+            assert len(item) == 2
+            idx, dist = item
+            assert isinstance(idx, int)
+            assert isinstance(dist, float)
+            assert dist > 0
+
+    def test_iqr_cutoff_behavior(self):
+        """Lower IQR multiplier should flag more items than higher multiplier."""
+        rng = np.random.default_rng(42)
+        m = rng.standard_normal((100, 3)).astype(np.float32)
+        low = detect_outliers(m, iqr_multiplier=1.0, max_outlier_pct=0.5)
+        high = detect_outliers(m, iqr_multiplier=5.0, max_outlier_pct=0.5)
+        assert len(low) >= len(high)
+
+    def test_dimension_aware_no_mass_flagging(self):
+        """High-dimensional clean Gaussian data should not flag everything."""
+        rng = np.random.default_rng(42)
+        # 500 samples, 10 dims — well-conditioned for robust covariance
+        m = rng.standard_normal((500, 10)).astype(np.float32)
+        result = detect_outliers(m)
+        # With IQR-based cutoff on clean Gaussian data,
+        # only a small fraction should be flagged (well under 50%)
+        assert len(result) < 250
+
+    def test_contamination_parameter(self):
+        rng = np.random.default_rng(42)
+        m = rng.standard_normal((50, 3)).astype(np.float32)
+        # Should not raise with different contamination values
+        result = detect_outliers(m, contamination=0.05)
+        assert isinstance(result, list)
+
+    def test_max_outlier_pct_hard_cap(self):
+        """The hard cap should limit outlier count to max_outlier_pct * n."""
+        rng = np.random.default_rng(42)
+        # Create data with many potential outliers (bimodal)
+        cluster = rng.standard_normal((80, 3)).astype(np.float32) * 0.1
+        outliers = rng.standard_normal((20, 3)).astype(np.float32) * 50.0
+        m = np.vstack([cluster, outliers])
+        # Very low IQR multiplier to flag a lot, but cap at 5%
+        result = detect_outliers(m, iqr_multiplier=0.5, max_outlier_pct=0.05)
+        max_allowed = max(1, int(0.05 * 100))  # 5
+        assert len(result) <= max_allowed
+
+    def test_hard_cap_keeps_most_extreme(self):
+        """When capped, the most extreme items (highest distance) should be kept."""
+        rng = np.random.default_rng(42)
+        cluster = rng.standard_normal((90, 3)).astype(np.float32) * 0.1
+        # Create outliers with increasing extremity
+        outliers = np.array([
+            [10.0, 10.0, 10.0],
+            [20.0, 20.0, 20.0],
+            [50.0, 50.0, 50.0],
+        ], dtype=np.float32)
+        m = np.vstack([cluster, outliers])
+        # Cap at ~1 item (0.01 * 93 = 0, but min is 1)
+        result = detect_outliers(m, iqr_multiplier=0.5, max_outlier_pct=0.02)
+        if len(result) > 0:
+            # The most extreme (index 92, distance for [50,50,50]) should be kept
+            indices = [idx for idx, _ in result]
+            assert 92 in indices
+
+    def test_cutoff_attribute(self):
+        """Returned result should carry a cutoff attribute."""
+        rng = np.random.default_rng(42)
+        m = rng.standard_normal((50, 3)).astype(np.float32)
+        result = detect_outliers(m)
+        assert hasattr(result, "cutoff")
+        assert isinstance(result.cutoff, float)
+        assert result.cutoff > 0
+
+
+class TestFindDuplicatePairs:
+    """Tests for cosine similarity duplicate detection."""
+
+    def test_single_item_returns_empty(self):
+        m = np.random.randn(1, 10).astype(np.float32)
+        result = find_duplicate_pairs(m, 0.9)
+        assert result == []
+
+    def test_empty_returns_empty(self):
+        m = np.empty((0, 10), dtype=np.float32)
+        result = find_duplicate_pairs(m, 0.9)
+        assert result == []
+
+    def test_identical_vectors_detected(self):
+        vec = np.random.randn(10).astype(np.float32)
+        vec = vec / np.linalg.norm(vec)
+        m = np.vstack([vec, vec, np.random.randn(10).astype(np.float32)])
+        result = find_duplicate_pairs(m, 0.99)
+        # Items 0 and 1 are identical, should be found
+        assert any(i == 0 and j == 1 for i, j, _ in result)
+
+    def test_orthogonal_vectors_not_detected(self):
+        m = np.eye(5, dtype=np.float32)
+        result = find_duplicate_pairs(m, 0.5)
+        assert result == []
+
+    def test_returns_correct_format(self):
+        vec = np.random.randn(10).astype(np.float32)
+        vec = vec / np.linalg.norm(vec)
+        m = np.vstack([vec, vec])
+        result = find_duplicate_pairs(m, 0.5)
+        assert len(result) >= 1
+        for item in result:
+            assert len(item) == 3
+            i, j, sim = item
+            assert isinstance(i, int)
+            assert isinstance(j, int)
+            assert isinstance(sim, float)
+            assert i < j
+
+    def test_i_less_than_j(self):
+        rng = np.random.default_rng(42)
+        # Create some similar vectors
+        base = rng.standard_normal(10).astype(np.float32)
+        m = np.vstack([base + rng.standard_normal(10) * 0.01 for _ in range(5)])
+        result = find_duplicate_pairs(m, 0.5)
+        for i, j, _ in result:
+            assert i < j
+
+    def test_high_threshold_fewer_pairs(self):
+        rng = np.random.default_rng(42)
+        m = rng.standard_normal((10, 20)).astype(np.float32)
+        # Normalize for meaningful cosine similarities
+        norms = np.linalg.norm(m, axis=1, keepdims=True)
+        m = m / norms
+        low = find_duplicate_pairs(m, 0.3)
+        high = find_duplicate_pairs(m, 0.9)
+        assert len(low) >= len(high)
+
+
+class TestSuggestLabels:
+    """Tests for z-score normalized label suggestion."""
+
+    def test_empty_items_returns_empty_lists(self):
+        items = np.empty((0, 10), dtype=np.float32)
+        labels = np.random.randn(3, 10).astype(np.float32)
+        result = suggest_labels(items, labels, ["a", "b", "c"])
+        assert result == []
+
+    def test_empty_labels_returns_empty_per_item(self):
+        items = np.random.randn(5, 10).astype(np.float32)
+        labels = np.empty((0, 10), dtype=np.float32)
+        result = suggest_labels(items, labels, [])
+        assert len(result) == 5
+        assert all(s == [] for s in result)
+
+    def test_identical_embedding_gets_that_label(self):
+        """If an item embedding strongly matches one label, z-score should highlight it."""
+        # Create multiple items so z-score normalization is meaningful
+        rng = np.random.default_rng(42)
+        # 10 random items + 1 item that matches label "bug" exactly
+        random_items = rng.standard_normal((10, 3)).astype(np.float32)
+        bug_vec = np.array([[1.0, 0.0, 0.0]], dtype=np.float32)
+        items = np.vstack([random_items, bug_vec])
+        labels = np.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]], dtype=np.float32)
+        result = suggest_labels(
+            items, labels, ["bug", "feature", "docs"],
+            z_threshold=0.5, z_margin=0.0, min_raw_sim=0.1,
+        )
+        # The last item (matching bug_vec) should get "bug" as top suggestion
+        last_item_sugs = result[-1]
+        if last_item_sugs:
+            assert last_item_sugs[0][0] == "bug"
+
+    def test_z_score_suppresses_dominant_label(self):
+        """When all items are similar to one label, z-scores should be low
+        (none stands out) and that label should not be blindly suggested."""
+        # All items identical — z-score for every item on every label is 0
+        items = np.ones((10, 3), dtype=np.float32)
+        labels = np.array([[1.0, 1.0, 1.0], [0.0, 1.0, 0.0]], dtype=np.float32)
+        result = suggest_labels(
+            items, labels, ["catch-all", "specific"],
+            z_threshold=1.5, min_raw_sim=0.3,
+        )
+        # With identical items, std=0 -> z-scores are all 0 -> nothing passes z_threshold
+        for sugs in result:
+            assert sugs == []
+
+    def test_margin_gate_blocks_top1(self):
+        """Top-1 label must beat #2 by z_margin to be accepted as position 0."""
+        rng = np.random.default_rng(99)
+        # 20 items, each slightly different, 2 labels
+        items = rng.standard_normal((20, 5)).astype(np.float32)
+        # Two labels that are nearly identical -> margin gate should block top-1
+        labels = np.array([[1.0, 0.5, 0.0, 0.0, 0.0],
+                           [1.0, 0.5, 0.01, 0.0, 0.0]], dtype=np.float32)
+        result = suggest_labels(
+            items, labels, ["label-a", "label-b"],
+            z_threshold=0.0, z_margin=10.0, min_raw_sim=0.0, max_per_item=1,
+        )
+        # With a huge margin requirement and max_per_item=1, nothing should pass
+        # because the only candidate (top-1) is blocked by margin gate,
+        # and max_per_item=1 prevents falling through to position 2
+        for sugs in result:
+            assert sugs == []
+
+    def test_margin_gate_passes_when_clear_winner(self):
+        """When top-1 clearly beats #2, it should pass the margin gate."""
+        # Create items where one strongly matches label 0 vs label 1
+        items = np.array([
+            [1.0, 0.0, 0.0, 0.0, 0.0],   # strongly matches label-a
+            [0.0, 0.0, 0.0, 0.0, 1.0],   # matches neither well
+        ] * 5, dtype=np.float32)  # 10 items for stable z-scores
+        labels = np.array([
+            [1.0, 0.0, 0.0, 0.0, 0.0],   # label-a
+            [0.0, 1.0, 0.0, 0.0, 0.0],   # label-b (orthogonal)
+        ], dtype=np.float32)
+        result = suggest_labels(
+            items, labels, ["label-a", "label-b"],
+            z_threshold=0.5, z_margin=0.3, min_raw_sim=0.1,
+        )
+        # Items matching label-a should get it suggested (clear z-score advantage)
+        got_label_a = sum(1 for sugs in result if sugs and sugs[0][0] == "label-a")
+        assert got_label_a > 0
+
+    def test_min_raw_similarity_filter(self):
+        """Even with high z-score, low raw similarity should be filtered out."""
+        # Items are orthogonal to all labels -> raw similarity near 0
+        items = np.array([[1.0, 0.0, 0.0]], dtype=np.float32)
+        labels = np.array([[0.0, 0.0, 1.0]], dtype=np.float32)
+        result = suggest_labels(
+            items, labels, ["irrelevant"],
+            z_threshold=0.0, z_margin=0.0, min_raw_sim=0.9,
+        )
+        # Raw similarity is ~0, which is below min_raw_sim=0.9
+        assert result[0] == []
+
+    def test_max_per_item_respected(self):
+        """Even if many labels qualify, max_per_item caps the results."""
+        rng = np.random.default_rng(42)
+        # Create items with some variance so z-scores differentiate
+        items = rng.standard_normal((20, 10)).astype(np.float32)
+        base = items[0]
+        # All labels very similar to item 0
+        labels = np.array([base + rng.standard_normal(10) * 0.01 for _ in range(10)])
+        names = [f"label-{i}" for i in range(10)]
+        result = suggest_labels(
+            items, labels, names,
+            z_threshold=0.0, z_margin=0.0, min_raw_sim=0.0, max_per_item=2,
+        )
+        for sugs in result:
+            assert len(sugs) <= 2
+
+    def test_returns_raw_similarity_not_z_score(self):
+        """Returned scores should be raw cosine similarity, not z-scores."""
+        rng = np.random.default_rng(42)
+        items = rng.standard_normal((15, 5)).astype(np.float32)
+        labels = rng.standard_normal((3, 5)).astype(np.float32)
+        names = ["bug", "feature", "docs"]
+        result = suggest_labels(
+            items, labels, names,
+            z_threshold=0.0, z_margin=0.0, min_raw_sim=-1.0,
+        )
+        # Raw cosine similarity should be in [-1, 1] range
+        for sugs in result:
+            for name, score in sugs:
+                assert -1.0 <= score <= 1.0 + 1e-5
+                assert isinstance(name, str)
+                assert isinstance(score, float)
+
+    def test_returns_correct_format(self):
+        rng = np.random.default_rng(42)
+        items = rng.standard_normal((3, 10)).astype(np.float32)
+        labels = rng.standard_normal((5, 10)).astype(np.float32)
+        names = ["bug", "feature", "docs", "ci", "test"]
+        result = suggest_labels(
+            items, labels, names,
+            z_threshold=0.0, z_margin=0.0, min_raw_sim=-1.0,
+        )
+        assert len(result) == 3
+        for sugs in result:
+            for name, score in sugs:
+                assert isinstance(name, str)
+                assert isinstance(score, float)
+                assert name in names
+
+    def test_text_truncation_in_labels(self):
+        """Label names should be returned as-is even when very long."""
+        rng = np.random.default_rng(42)
+        items = rng.standard_normal((10, 5)).astype(np.float32)
+        long_name = "a" * 200
+        labels = rng.standard_normal((1, 5)).astype(np.float32)
+        result = suggest_labels(
+            items, labels, [long_name],
+            z_threshold=0.0, z_margin=0.0, min_raw_sim=-1.0,
+        )
+        for sugs in result:
+            if sugs:
+                assert sugs[0][0] == long_name

.github/scripts/triage/test_sweep.py

@@ -0,0 +1,873 @@
+"""Tests for sweep.py — all external calls (API, embedding) are mocked."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from io import BytesIO
+from unittest.mock import patch, MagicMock, mock_open
+from urllib.error import HTTPError
+
+import numpy as np
+import pytest
+
+# Mock fastembed before importing sweep (which imports embedding_utils)
+sys.modules["fastembed"] = MagicMock()
+
+# Set required env vars before importing sweep (module-level constants read env)
+os.environ.setdefault("GITHUB_TOKEN", "test-token")
+os.environ.setdefault("GITHUB_REPOSITORY", "owner/repo")
+
+from sweep import (
+    github_api_get,
+    fetch_all_open_items,
+    fetch_repo_labels,
+    apply_labels_to_item,
+    generate_report,
+    create_report_issue,
+    write_report,
+    main,
+    TriageItem,
+    RepoLabel,
+    REPORT_FILE,
+    REPORT_LABEL,
+    API_PAGE_SIZE,
+    MIN_SAMPLES_FOR_OUTLIER_DETECTION,
+    PCA_MAX_COMPONENTS,
+    MAX_EMBED_CHARS,
+    IQR_MULTIPLIER,
+    MAX_OUTLIER_PCT,
+    _item_age,
+    _suggested_action,
+)
+
+
+def _make_api_issue(number: int, title: str = "Test issue", is_pr: bool = False,
+                    body: str = "Issue body", labels: list[str] | None = None,
+                    created_at: str = "2026-03-21T00:00:00Z") -> dict:
+    """Helper to build a mock GitHub API issue response object."""
+    result: dict = {
+        "number": number,
+        "title": title,
+        "html_url": f"https://github.com/owner/repo/issues/{number}",
+        "body": body,
+        "created_at": created_at,
+        "labels": [{"name": lbl} for lbl in (labels or [])],
+    }
+    if is_pr:
+        result["pull_request"] = {"url": "..."}
+    return result
+
+
+class TestGithubApiGet:
+    """Tests for the github_api_get function."""
+
+    @patch("sweep.urllib.request.urlopen")
+    def test_successful_request(self, mock_urlopen):
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = json.dumps([{"id": 1}]).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        result = github_api_get("/issues?state=open")
+        assert result == [{"id": 1}]
+
+    @patch("sweep.urllib.request.urlopen")
+    def test_http_error_exits(self, mock_urlopen):
+        error = HTTPError(
+            url="https://api.github.com/repos/owner/repo/issues",
+            code=403,
+            msg="Forbidden",
+            hdrs=None,  # type: ignore[arg-type]
+            fp=BytesIO(b'{"message": "rate limited"}'),
+        )
+        mock_urlopen.side_effect = error
+
+        with pytest.raises(SystemExit) as exc_info:
+            github_api_get("/issues")
+        assert exc_info.value.code == 1
+
+
+class TestConstants:
+    """Tests for module-level constants."""
+
+    def test_min_samples_is_at_least_3x_pca_max(self):
+        """MIN_SAMPLES must be >= 3 * PCA_MAX_COMPONENTS for reliable covariance."""
+        assert MIN_SAMPLES_FOR_OUTLIER_DETECTION >= 3 * PCA_MAX_COMPONENTS
+
+    def test_min_samples_is_100(self):
+        assert MIN_SAMPLES_FOR_OUTLIER_DETECTION == 100
+
+    def test_pca_max_components_is_20(self):
+        assert PCA_MAX_COMPONENTS == 20
+
+    def test_iqr_multiplier_default(self):
+        assert IQR_MULTIPLIER == 3.0
+
+    def test_max_outlier_pct_default(self):
+        assert MAX_OUTLIER_PCT == 0.05
+
+
+class TestFetchAllOpenItems:
+    """Tests for fetch_all_open_items."""
+
+    @patch("sweep.github_api_get")
+    def test_empty_repo(self, mock_get):
+        mock_get.return_value = []
+        items = fetch_all_open_items()
+        assert items == []
+
+    @patch("sweep.github_api_get")
+    def test_single_page(self, mock_get):
+        mock_get.return_value = [
+            _make_api_issue(1, "Bug report"),
+            _make_api_issue(2, "Feature request", is_pr=True),
+        ]
+        items = fetch_all_open_items()
+        assert len(items) == 2
+        assert items[0]["number"] == 1
+        assert items[0]["is_pr"] is False
+        assert items[1]["is_pr"] is True
+
+    @patch("sweep.github_api_get")
+    def test_text_field_constructed(self, mock_get):
+        mock_get.return_value = [
+            _make_api_issue(1, "My Title", body="My Body"),
+        ]
+        items = fetch_all_open_items()
+        assert items[0]["text"] == "My Title\n\nMy Body"
+
+    @patch("sweep.github_api_get")
+    def test_long_body_truncated(self, mock_get):
+        """Bodies exceeding MAX_EMBED_CHARS are truncated to fit the token window."""
+        long_body = "x" * (MAX_EMBED_CHARS + 500)
+        mock_get.return_value = [
+            _make_api_issue(1, "Title", body=long_body),
+        ]
+        items = fetch_all_open_items()
+        assert len(items[0]["text"]) == MAX_EMBED_CHARS
+
+    @patch("sweep.github_api_get")
+    def test_short_body_not_truncated(self, mock_get):
+        """Bodies under the limit are left intact."""
+        mock_get.return_value = [
+            _make_api_issue(1, "Title", body="Short body"),
+        ]
+        items = fetch_all_open_items()
+        assert items[0]["text"] == "Title\n\nShort body"
+
+    @patch("sweep.github_api_get")
+    def test_null_body_handled(self, mock_get):
+        issue = _make_api_issue(1, "No body")
+        issue["body"] = None
+        mock_get.return_value = [issue]
+        items = fetch_all_open_items()
+        assert items[0]["text"] == "No body\n\n"
+
+    @patch("sweep.github_api_get")
+    def test_labels_extracted(self, mock_get):
+        mock_get.return_value = [
+            _make_api_issue(1, "Labeled", labels=["bug", "high-priority"]),
+        ]
+        items = fetch_all_open_items()
+        assert items[0]["labels"] == ["bug", "high-priority"]
+
+    @patch("sweep.MAX_ITEMS", 3)
+    @patch("sweep.github_api_get")
+    def test_max_items_cap(self, mock_get):
+        mock_get.return_value = [_make_api_issue(i) for i in range(100)]
+        items = fetch_all_open_items()
+        assert len(items) == 3
+
+    @patch("sweep.API_PAGE_SIZE", 2)
+    @patch("sweep.github_api_get")
+    def test_pagination(self, mock_get):
+        # First page: 2 items (full page), second page: 1 item (partial -> stop)
+        mock_get.side_effect = [
+            [_make_api_issue(1), _make_api_issue(2)],
+            [_make_api_issue(3)],
+        ]
+        items = fetch_all_open_items()
+        assert len(items) == 3
+        assert mock_get.call_count == 2
+
+
+class TestItemAge:
+    """Tests for _item_age helper."""
+
+    def test_recent_item(self):
+        from datetime import datetime, timezone, timedelta
+        recent = (datetime.now(timezone.utc) - timedelta(hours=12)).isoformat()
+        assert _item_age(recent) == "<1d"
+
+    def test_days_old(self):
+        from datetime import datetime, timezone, timedelta
+        old = (datetime.now(timezone.utc) - timedelta(days=15)).isoformat()
+        assert _item_age(old) == "15d"
+
+    def test_months_old(self):
+        from datetime import datetime, timezone, timedelta
+        old = (datetime.now(timezone.utc) - timedelta(days=90)).isoformat()
+        assert _item_age(old) == "3mo"
+
+    def test_years_old(self):
+        from datetime import datetime, timezone, timedelta
+        old = (datetime.now(timezone.utc) - timedelta(days=400)).isoformat()
+        assert _item_age(old) == "1y"
+
+    def test_invalid_date(self):
+        assert _item_age("not-a-date") == "?"
+
+
+class TestSuggestedAction:
+    """Tests for _suggested_action helper."""
+
+    def test_both_issues_close_newer(self):
+        a = TriageItem(
+            number=1, title="A", html_url="u", is_pr=False, labels=[],
+            created_at="2026-01-01T00:00:00Z", text="t",
+        )
+        b = TriageItem(
+            number=2, title="B", html_url="u", is_pr=False, labels=[],
+            created_at="2026-02-01T00:00:00Z", text="t",
+        )
+        result = _suggested_action(a, b)
+        assert "Close #2 as duplicate" in result
+
+    def test_both_prs_review(self):
+        a = TriageItem(
+            number=1, title="A", html_url="u", is_pr=True, labels=[],
+            created_at="2026-01-01T00:00:00Z", text="t",
+        )
+        b = TriageItem(
+            number=2, title="B", html_url="u", is_pr=True, labels=[],
+            created_at="2026-01-01T00:00:00Z", text="t",
+        )
+        assert _suggested_action(a, b) == "Review for overlap"
+
+    def test_issue_pr_link(self):
+        a = TriageItem(
+            number=1, title="A", html_url="u", is_pr=False, labels=[],
+            created_at="2026-01-01T00:00:00Z", text="t",
+        )
+        b = TriageItem(
+            number=2, title="B", html_url="u", is_pr=True, labels=[],
+            created_at="2026-01-01T00:00:00Z", text="t",
+        )
+        assert _suggested_action(a, b) == "Link PR to issue"
+
+
+class TestGenerateReport:
+    """Tests for the markdown report generator."""
+
+    def test_no_findings(self):
+        items = [
+            TriageItem(
+                number=1, title="Test", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="Test",
+            ),
+        ]
+        report = generate_report(items, [], [])
+        assert "## Triage Sweep Report" in report
+        assert "Items analyzed:** 1" in report
+        assert "None found." in report
+        assert "0 outliers flagged" in report
+        assert "0 duplicate pairs found" in report
+
+    def test_health_summary_table(self):
+        items = [
+            TriageItem(
+                number=1, title="Test", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="Test",
+            ),
+        ]
+        report = generate_report(items, [], [])
+        assert "### Health Summary" in report
+        assert "| Metric | Value |" in report
+        assert "| Items analyzed | 1 |" in report
+
+    def test_iqr_multiplier_in_thresholds(self):
+        """Report should show IQR multiplier, not percentile."""
+        items = [
+            TriageItem(
+                number=1, title="Test", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="Test",
+            ),
+        ]
+        report = generate_report(items, [], [])
+        assert "IQR multiplier" in report
+        assert "percentile" not in report.lower().split("thresholds")[0]  # not in thresholds line
+
+    def test_with_outliers_shows_distance_and_age(self):
+        items = [
+            TriageItem(
+                number=10, title="Spam Issue", html_url="https://example.com/10",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="spam",
+            ),
+            TriageItem(
+                number=20, title="Good Issue", html_url="https://example.com/20",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="good",
+            ),
+        ]
+        report = generate_report(items, [(0, 12.34)], [])
+        assert "#10" in report
+        assert "Spam Issue" in report
+        assert "12.34" in report
+        assert "1 outliers flagged" in report
+        # Age column should be present
+        assert "| Age |" in report
+
+    def test_outlier_borderline_in_details(self):
+        """Borderline outliers should be in a <details> section."""
+        from embedding_utils import _OutlierResult
+        items = [
+            TriageItem(
+                number=10, title="Borderline", html_url="https://example.com/10",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="spam",
+            ),
+        ]
+        # Create outlier results with cutoff=10.0, distance=12.0 (< 2*cutoff=20)
+        outlier_results = _OutlierResult([(0, 12.0)])
+        outlier_results.cutoff = 10.0
+        report = generate_report(items, outlier_results, [])
+        assert "<details>" in report
+        assert "Borderline" in report
+
+    def test_outlier_high_confidence(self):
+        """Items with distance > 2x cutoff should be in high confidence section."""
+        from embedding_utils import _OutlierResult
+        items = [
+            TriageItem(
+                number=10, title="Definite Spam", html_url="https://example.com/10",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="spam",
+            ),
+        ]
+        outlier_results = _OutlierResult([(0, 25.0)])
+        outlier_results.cutoff = 10.0
+        report = generate_report(items, outlier_results, [])
+        assert "High Confidence" in report
+
+    def test_with_duplicates_suggested_action(self):
+        items = [
+            TriageItem(
+                number=1, title="First", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="a",
+            ),
+            TriageItem(
+                number=2, title="Second", html_url="https://example.com/2",
+                is_pr=True, labels=[], created_at="2026-02-01T00:00:00Z", text="b",
+            ),
+        ]
+        report = generate_report(items, [], [(0, 1, 0.954)])
+        assert "#1" in report
+        assert "#2" in report
+        assert "0.954" in report
+        assert "1 duplicate pairs found" in report
+        assert "Suggested Action" in report
+        assert "Link PR to issue" in report
+
+    def test_duplicate_both_issues_close_newer(self):
+        items = [
+            TriageItem(
+                number=1, title="First", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="a",
+            ),
+            TriageItem(
+                number=2, title="Second", html_url="https://example.com/2",
+                is_pr=False, labels=[], created_at="2026-02-01T00:00:00Z", text="b",
+            ),
+        ]
+        report = generate_report(items, [], [(0, 1, 0.95)])
+        assert "Close #2 as duplicate" in report
+
+    def test_duplicate_both_prs_review(self):
+        items = [
+            TriageItem(
+                number=1, title="PR A", html_url="https://example.com/1",
+                is_pr=True, labels=[], created_at="2026-01-01T00:00:00Z", text="a",
+            ),
+            TriageItem(
+                number=2, title="PR B", html_url="https://example.com/2",
+                is_pr=True, labels=[], created_at="2026-01-01T00:00:00Z", text="b",
+            ),
+        ]
+        report = generate_report(items, [], [(0, 1, 0.95)])
+        assert "Review for overlap" in report
+
+    def test_pr_type_label(self):
+        items = [
+            TriageItem(
+                number=5, title="PR Title", html_url="https://example.com/5",
+                is_pr=True, labels=[], created_at="2026-01-01T00:00:00Z", text="pr",
+            ),
+        ]
+        report = generate_report(items, [(0, 8.5)], [])
+        assert "| PR |" in report
+
+    def test_footer_present(self):
+        items = [
+            TriageItem(
+                number=1, title="T", html_url="u",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="t",
+            ),
+        ]
+        report = generate_report(items, [], [])
+        assert "no LLM was used" in report
+
+
+class TestCreateReportIssue:
+    """Tests for creating the report GitHub issue."""
+
+    @patch("sweep.urllib.request.urlopen")
+    def test_successful_creation(self, mock_urlopen):
+        mock_resp = MagicMock()
+        mock_resp.status = 201
+        mock_resp.read.return_value = json.dumps({
+            "html_url": "https://github.com/owner/repo/issues/99",
+        }).encode()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        # Should not raise
+        create_report_issue("# Test Report")
+
+    @patch("sweep.urllib.request.urlopen")
+    def test_http_error_exits(self, mock_urlopen):
+        error = HTTPError(
+            url="https://api.github.com/repos/owner/repo/issues",
+            code=422,
+            msg="Unprocessable",
+            hdrs=None,  # type: ignore[arg-type]
+            fp=BytesIO(b'{"message": "validation failed"}'),
+        )
+        mock_urlopen.side_effect = error
+
+        with pytest.raises(SystemExit) as exc_info:
+            create_report_issue("# Test Report")
+        assert exc_info.value.code == 1
+
+
+class TestWriteReport:
+    """Tests for the write_report helper."""
+
+    @patch("builtins.open", mock_open())
+    def test_writes_to_file(self):
+        write_report("# Report Content")
+        from builtins import open as builtin_open  # noqa
+        # Verify open was called with the right path
+        from unittest.mock import call
+        open_mock = open  # The patched version
+        open_mock.assert_called_once_with(REPORT_FILE, "w", encoding="utf-8")  # type: ignore[attr-defined]
+        open_mock().write.assert_called_once_with("# Report Content")  # type: ignore[attr-defined]
+
+
+class TestFetchRepoLabels:
+    """Tests for fetch_repo_labels."""
+
+    @patch("sweep.github_api_get")
+    def test_fetches_and_constructs_labels(self, mock_get):
+        mock_get.return_value = [
+            {"name": "bug", "description": "Something isn't working"},
+            {"name": "enhancement", "description": "New feature or request"},
+            {"name": "docs", "description": ""},
+        ]
+        labels = fetch_repo_labels()
+        assert len(labels) == 3
+        assert labels[0]["name"] == "bug"
+        assert labels[0]["text"] == "bug: Something isn't working"
+        assert labels[2]["text"] == "docs"  # no description, just name
+
+    @patch("sweep.github_api_get")
+    def test_empty_repo_labels(self, mock_get):
+        mock_get.return_value = []
+        labels = fetch_repo_labels()
+        assert labels == []
+
+    @patch("sweep.github_api_get")
+    def test_null_description_handled(self, mock_get):
+        mock_get.return_value = [
+            {"name": "wontfix", "description": None},
+        ]
+        labels = fetch_repo_labels()
+        assert labels[0]["text"] == "wontfix"
+
+    @patch("sweep.API_PAGE_SIZE", 2)
+    @patch("sweep.github_api_get")
+    def test_label_pagination(self, mock_get):
+        """Repos with more labels than one page should fetch all pages."""
+        mock_get.side_effect = [
+            # First page: full (2 items = API_PAGE_SIZE)
+            [
+                {"name": "bug", "description": "Broken"},
+                {"name": "feature", "description": "New"},
+            ],
+            # Second page: partial (1 item < API_PAGE_SIZE) -> stop
+            [
+                {"name": "docs", "description": "Documentation"},
+            ],
+        ]
+        labels = fetch_repo_labels()
+        assert len(labels) == 3
+        assert mock_get.call_count == 2
+        assert labels[0]["name"] == "bug"
+        assert labels[2]["name"] == "docs"
+
+
+class TestApplyLabelsToItem:
+    """Tests for apply_labels_to_item."""
+
+    def test_empty_labels_skips(self):
+        # Should not make any API call
+        apply_labels_to_item(1, [])
+
+    @patch("sweep.urllib.request.urlopen")
+    def test_successful_label_application(self, mock_urlopen):
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = b'[{"name": "bug"}]'
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_urlopen.return_value = mock_resp
+
+        # Should not raise
+        apply_labels_to_item(42, ["bug", "enhancement"])
+
+    @patch("sweep.urllib.request.urlopen")
+    def test_http_error_is_non_fatal(self, mock_urlopen):
+        error = HTTPError(
+            url="https://api.github.com/repos/owner/repo/issues/1/labels",
+            code=404,
+            msg="Not Found",
+            hdrs=None,  # type: ignore[arg-type]
+            fp=BytesIO(b'{"message": "not found"}'),
+        )
+        mock_urlopen.side_effect = error
+
+        # Should NOT raise — labeling failures are warnings, not fatal
+        apply_labels_to_item(1, ["bug"])
+
+
+class TestGenerateReportWithLabels:
+    """Tests for label suggestions in the report."""
+
+    def test_report_includes_label_section_high_confidence(self):
+        """High-confidence label (raw_sim >= 0.5) should appear in main table."""
+        items = [
+            TriageItem(
+                number=1, title="Fix crash", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="crash",
+            ),
+        ]
+        suggestions = [[("bug", 0.85)]]
+        report = generate_report(items, [], [], label_suggestions=suggestions)
+        assert "Suggested Labels" in report
+        assert "`bug` (0.85)" in report
+        assert "1 items suggested for labeling" in report
+
+    def test_report_low_confidence_in_details(self):
+        """Low-confidence label (raw_sim < 0.5) should be in <details> section."""
+        items = [
+            TriageItem(
+                number=1, title="Something", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="something",
+            ),
+        ]
+        suggestions = [[("maybe-bug", 0.35)]]
+        report = generate_report(items, [], [], label_suggestions=suggestions)
+        assert "Low-confidence suggestions" in report
+        assert "<details>" in report
+        assert "`maybe-bug` (0.35)" in report
+
+    def test_report_skips_already_labeled_items(self):
+        items = [
+            TriageItem(
+                number=1, title="Already labeled", html_url="https://example.com/1",
+                is_pr=False, labels=["bug"], created_at="2026-01-01T00:00:00Z", text="bug",
+            ),
+        ]
+        suggestions = [[("bug", 0.95)]]
+        report = generate_report(items, [], [], label_suggestions=suggestions)
+        assert "0 items suggested for labeling" in report
+        assert "No unlabeled items" in report
+
+    def test_report_excludes_outliers_from_suggestions(self):
+        items = [
+            TriageItem(
+                number=1, title="Spam garbage", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="spam",
+            ),
+            TriageItem(
+                number=2, title="Real bug", html_url="https://example.com/2",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="bug",
+            ),
+        ]
+        suggestions = [[("bug", 0.85)], [("bug", 0.90)]]
+        # Item 0 is an outlier (with distance) — should be excluded from label suggestions
+        report = generate_report(items, [(0, 15.2)], [], label_suggestions=suggestions)
+        assert "1 unlabeled items" in report  # only item 2
+        assert "#2" in report
+        # Item 0 (outlier) should NOT be in the suggestions table
+        assert "Spam garbage" not in report.split("Suggested Labels")[1]
+
+    def test_report_without_label_suggestions(self):
+        items = [
+            TriageItem(
+                number=1, title="T", html_url="u",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="t",
+            ),
+        ]
+        report = generate_report(items, [], [], label_suggestions=None)
+        assert "Suggested Labels" not in report
+
+    def test_label_concentration_warning(self):
+        """When >50% of suggestions point to the same label, a warning should appear."""
+        items = [
+            TriageItem(
+                number=i, title=f"Item {i}", html_url=f"https://example.com/{i}",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text=f"text {i}",
+            )
+            for i in range(4)
+        ]
+        # 3 out of 4 items get "bug" label -> 75% concentration
+        suggestions = [
+            [("bug", 0.85)],
+            [("bug", 0.80)],
+            [("bug", 0.75)],
+            [("enhancement", 0.90)],
+        ]
+        report = generate_report(items, [], [], label_suggestions=suggestions)
+        assert "Warning" in report
+        assert "`bug`" in report
+        assert "3/4" in report
+
+
+class TestMain:
+    """Tests for the main orchestration function."""
+
+    @patch.dict(os.environ, {"GITHUB_TOKEN": "", "GITHUB_REPOSITORY": "owner/repo"})
+    def test_missing_token_exits(self):
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+        assert exc_info.value.code == 1
+
+    @patch.dict(os.environ, {"GITHUB_TOKEN": "tok", "GITHUB_REPOSITORY": ""})
+    def test_missing_repo_exits(self):
+        with pytest.raises(SystemExit) as exc_info:
+            main()
+        assert exc_info.value.code == 1
+
+    @patch("sweep.write_report")
+    @patch("sweep.fetch_all_open_items", return_value=[])
+    def test_no_items(self, mock_fetch, mock_write):
+        main()
+        mock_write.assert_called_once()
+        report = mock_write.call_args[0][0]
+        assert "No open issues or PRs found" in report
+
+    @patch("sweep.create_report_issue")
+    @patch("sweep.write_report")
+    @patch("sweep.suggest_labels", return_value=[])
+    @patch("sweep.find_duplicate_pairs", return_value=[])
+    @patch("sweep.detect_outliers", return_value=[])
+    @patch("sweep.reduce_dimensions")
+    @patch("sweep.normalize_rows")
+    @patch("sweep.embed_texts")
+    @patch("sweep.fetch_repo_labels")
+    @patch("sweep.fetch_all_open_items")
+    def test_full_flow_with_enough_items(
+        self, mock_fetch, mock_labels, mock_embed, mock_norm, mock_reduce,
+        mock_outliers, mock_dupes, mock_suggest, mock_write, mock_create,
+    ):
+        """Test the full flow with >= MIN_SAMPLES items (outlier detection runs)."""
+        n = MIN_SAMPLES_FOR_OUTLIER_DETECTION
+        items = [
+            TriageItem(
+                number=i, title=f"Item {i}", html_url=f"https://example.com/{i}",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text=f"text {i}",
+            )
+            for i in range(n)
+        ]
+        mock_fetch.return_value = items
+        mock_labels.return_value = [
+            RepoLabel(name="bug", description="Something broken", text="bug: Something broken"),
+        ]
+
+        embeddings = np.random.randn(n, 384).astype(np.float32)
+        mock_embed.return_value = embeddings
+        mock_norm.return_value = embeddings
+        mock_reduce.return_value = np.random.randn(n, 10).astype(np.float32)
+
+        main()
+
+        mock_fetch.assert_called_once()
+        mock_labels.assert_called_once()
+        # embed_texts called twice: once for items, once for labels
+        assert mock_embed.call_count == 2
+        mock_norm.assert_called()
+        mock_reduce.assert_called_once()
+        mock_outliers.assert_called_once()
+        mock_dupes.assert_called_once()
+        mock_suggest.assert_called_once()
+        mock_write.assert_called_once()
+        mock_create.assert_called_once()
+
+    @patch("sweep.create_report_issue")
+    @patch("sweep.write_report")
+    @patch("sweep.suggest_labels", return_value=[])
+    @patch("sweep.find_duplicate_pairs", return_value=[])
+    @patch("sweep.detect_outliers")
+    @patch("sweep.reduce_dimensions")
+    @patch("sweep.normalize_rows")
+    @patch("sweep.embed_texts")
+    @patch("sweep.fetch_repo_labels", return_value=[])
+    @patch("sweep.fetch_all_open_items")
+    def test_skips_outlier_detection_for_few_items(
+        self, mock_fetch, mock_labels, mock_embed, mock_norm, mock_reduce,
+        mock_outliers, mock_dupes, mock_suggest, mock_write, mock_create,
+    ):
+        """With < MIN_SAMPLES items, outlier detection should be skipped."""
+        n = MIN_SAMPLES_FOR_OUTLIER_DETECTION - 1
+        items = [
+            TriageItem(
+                number=i, title=f"Item {i}", html_url=f"https://example.com/{i}",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text=f"text {i}",
+            )
+            for i in range(n)
+        ]
+        mock_fetch.return_value = items
+
+        embeddings = np.random.randn(n, 384).astype(np.float32)
+        mock_embed.return_value = embeddings
+        mock_norm.return_value = embeddings
+
+        main()
+
+        # Outlier detection should not have been called
+        mock_reduce.assert_not_called()
+        mock_outliers.assert_not_called()
+        # But duplicates should still be checked
+        mock_dupes.assert_called_once()
+
+    @patch.dict(os.environ, {"INPUT_DRY_RUN": "true"})
+    @patch("sweep.DRY_RUN", True)
+    @patch("sweep.write_report")
+    @patch("sweep.create_report_issue")
+    @patch("sweep.apply_labels_to_item")
+    @patch("sweep.suggest_labels", return_value=[[("bug", 0.85)]])
+    @patch("sweep.find_duplicate_pairs", return_value=[])
+    @patch("sweep.normalize_rows")
+    @patch("sweep.embed_texts")
+    @patch("sweep.fetch_repo_labels")
+    @patch("sweep.fetch_all_open_items")
+    def test_dry_run_skips_issue_creation_and_labeling(
+        self, mock_fetch, mock_labels, mock_embed, mock_norm,
+        mock_dupes, mock_suggest, mock_apply, mock_create, mock_write,
+    ):
+        items = [
+            TriageItem(
+                number=1, title="Item", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="text",
+            )
+        ]
+        mock_fetch.return_value = items
+        mock_labels.return_value = [
+            RepoLabel(name="bug", description="Broken", text="bug: Broken"),
+        ]
+        embeddings = np.random.randn(1, 384).astype(np.float32)
+        mock_embed.return_value = embeddings
+        mock_norm.return_value = embeddings
+
+        main()
+
+        mock_create.assert_not_called()
+        mock_apply.assert_not_called()
+        mock_write.assert_called_once()
+
+    @patch("sweep.create_report_issue")
+    @patch("sweep.write_report")
+    @patch("sweep.apply_labels_to_item")
+    @patch("sweep.suggest_labels")
+    @patch("sweep.find_duplicate_pairs", return_value=[])
+    @patch("sweep.normalize_rows")
+    @patch("sweep.embed_texts")
+    @patch("sweep.fetch_repo_labels")
+    @patch("sweep.fetch_all_open_items")
+    def test_labels_not_auto_applied(
+        self, mock_fetch, mock_labels, mock_embed, mock_norm,
+        mock_dupes, mock_suggest, mock_apply, mock_write, mock_create,
+    ):
+        """Auto-labeling is disabled; labels should appear in report only."""
+        items = [
+            TriageItem(
+                number=1, title="Crash bug", html_url="https://example.com/1",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text="crash",
+            ),
+            TriageItem(
+                number=2, title="Already labeled", html_url="https://example.com/2",
+                is_pr=False, labels=["enhancement"], created_at="2026-01-01T00:00:00Z", text="feat",
+            ),
+        ]
+        mock_fetch.return_value = items
+        mock_labels.return_value = [
+            RepoLabel(name="bug", description="Broken", text="bug: Broken"),
+        ]
+        mock_suggest.return_value = [
+            [("bug", 0.90)],
+            [("bug", 0.45)],
+        ]
+
+        embeddings = np.random.randn(2, 384).astype(np.float32)
+        mock_embed.return_value = embeddings
+        mock_norm.return_value = embeddings
+
+        main()
+
+        # Auto-labeling is disabled — apply_labels_to_item should never be called
+        mock_apply.assert_not_called()
+
+    @patch("sweep.create_report_issue")
+    @patch("sweep.write_report")
+    @patch("sweep.apply_labels_to_item")
+    @patch("sweep.suggest_labels")
+    @patch("sweep.find_duplicate_pairs", return_value=[])
+    @patch("sweep.detect_outliers")
+    @patch("sweep.reduce_dimensions")
+    @patch("sweep.normalize_rows")
+    @patch("sweep.embed_texts")
+    @patch("sweep.fetch_repo_labels")
+    @patch("sweep.fetch_all_open_items")
+    def test_outliers_excluded_from_report_suggestions(
+        self, mock_fetch, mock_labels, mock_embed, mock_norm, mock_reduce,
+        mock_outliers, mock_dupes, mock_suggest, mock_apply, mock_write, mock_create,
+    ):
+        """Items flagged as outliers should not appear in report label suggestions."""
+        n = MIN_SAMPLES_FOR_OUTLIER_DETECTION
+        items = [
+            TriageItem(
+                number=i, title=f"Item {i}", html_url=f"https://example.com/{i}",
+                is_pr=False, labels=[], created_at="2026-01-01T00:00:00Z", text=f"text {i}",
+            )
+            for i in range(n)
+        ]
+        mock_fetch.return_value = items
+        mock_labels.return_value = [
+            RepoLabel(name="bug", description="Broken", text="bug: Broken"),
+        ]
+        mock_outliers.return_value = [(0, 12.5), (5, 15.3)]
+        mock_suggest.return_value = [[("bug", 0.85)] for _ in range(n)]
+
+        embeddings = np.random.randn(n, 384).astype(np.float32)
+        mock_embed.return_value = embeddings
+        mock_norm.return_value = embeddings
+        mock_reduce.return_value = np.random.randn(n, 10).astype(np.float32)
+
+        main()
+
+        # Auto-labeling is disabled
+        mock_apply.assert_not_called()
+        # Report should still be generated (outliers excluded from suggestions in report)
+        mock_write.assert_called_once()
+        report = mock_write.call_args[0][0]
+        # Outlier items 0 and 5 should not appear in the label suggestions section
+        assert "Item 0" not in report.split("Suggested Labels")[1] if "Suggested Labels" in report else True

.github/workflows/ci-e2e.yml

@@ -0,0 +1,94 @@
+name: E2E Tests
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check-changes:
+    name: Check web module changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      web_changed: ${{ steps.filter.outputs.web }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v3
+        id: filter
+        with:
+          filters: |
+            web:
+              - 'gitnexus-web/**'
+
+  e2e:
+    name: e2e (chromium)
+    needs: check-changes
+    if: needs.check-changes.result == 'success' && needs.check-changes.outputs.web_changed == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Configure e2e GitNexus home
+        run: echo "GITNEXUS_HOME=${RUNNER_TEMP}/gitnexus-home" >> "$GITHUB_ENV"
+
+      - uses: ./.github/actions/setup-gitnexus-web
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+        working-directory: gitnexus-web
+
+      - name: Install backend dependencies
+        run: npm ci
+        working-directory: gitnexus
+
+      - name: Build backend
+        run: npm run build
+        working-directory: gitnexus
+
+      - name: Analyze repository (index for backend)
+        run: |
+          E2E_REPO="${RUNNER_TEMP}/gitnexus-e2e-repo"
+          rm -rf "${E2E_REPO}"
+          mkdir -p "${E2E_REPO}"
+          cp -R gitnexus/test/fixtures/mini-repo/src "${E2E_REPO}/src"
+          printf '%s\n' '{"name":"e2e-mini-repo","version":"0.0.0","private":true}' > "${E2E_REPO}/package.json"
+          node gitnexus/dist/cli/index.js analyze "${E2E_REPO}" --skip-git --skip-agents-md --name e2e-mini-repo
+          if [ ! -d "${E2E_REPO}/.gitnexus" ]; then
+            echo "::error::No fixture .gitnexus index created"
+            exit 1
+          fi
+
+      - name: Start backend server
+        run: node dist/cli/index.js serve &
+        working-directory: gitnexus
+
+      - name: Wait for backend readiness
+        run: npx wait-on http://localhost:4747/api/repos --timeout 30000
+        working-directory: gitnexus-web
+
+      - name: Start Vite dev server
+        run: npm run dev &
+        working-directory: gitnexus-web
+
+      - name: Wait for Vite dev server
+        run: npx wait-on http://localhost:5173 --timeout 30000
+        working-directory: gitnexus-web
+
+      - name: Run E2E tests
+        run: npx playwright test
+        working-directory: gitnexus-web
+        env:
+          E2E: '1'
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-results
+          path: |
+            gitnexus-web/test-results/
+            gitnexus-web/playwright-report/
+          retention-days: 5

.github/workflows/ci-quality.yml

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

.github/workflows/ci-report.yml

@@ -0,0 +1,444 @@
+name: CI Report
+
+# Triggered after the CI workflow completes.  Because workflow_run
+# always runs code from the *default branch*, it receives a read/write
+# GITHUB_TOKEN — even when the triggering PR comes from a fork.
+
+on:
+  workflow_run:
+    workflows: ['CI']
+    types: [completed]
+
+permissions:
+  actions: read # needed to list/download workflow run artifacts
+  contents: read # needed for sparse checkout of vitest.config.ts
+  pull-requests: write # needed to post sticky PR comment
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Serialize sticky-comment writes per PR so two rapid CI completions don't race.
+# Internal PRs surface in `pull_requests[0].number`. Fork PRs leave that array empty,
+# so we fall back to `<head-repo-full-name>/<head-branch>`, which is stable across
+# reruns and subsequent pushes for the same fork PR (unlike `workflow_run.id` which
+# is unique per run and therefore does not serialize anything).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.pull_requests[0].number || format('{0}/{1}', github.event.workflow_run.head_repository.full_name, github.event.workflow_run.head_branch) }}
+  cancel-in-progress: false
+
+jobs:
+  pr-report:
+    name: PR Report
+    # Only run for pull-request CI runs
+    if: >-
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion != 'cancelled'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # ── Download artifacts from the CI run ────────────────────────
+      - name: Download artifacts
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const runId = context.payload.workflow_run.id;
+
+            const allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: runId,
+            });
+
+            async function downloadArtifact(name, dest) {
+              const match = allArtifacts.data.artifacts.find(a => a.name === name);
+              if (!match) {
+                core.warning(`Artifact "${name}" not found`);
+                return false;
+              }
+              const zip = await github.rest.actions.downloadArtifact({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                artifact_id: match.id,
+                archive_format: 'zip',
+              });
+              fs.mkdirSync(dest, { recursive: true });
+              fs.writeFileSync(path.join(dest, `${name}.zip`), Buffer.from(zip.data));
+              return true;
+            }
+
+            const temp = process.env.RUNNER_TEMP;
+            await downloadArtifact('pr-meta', path.join(temp, 'dl'));
+            await downloadArtifact('test-reports', path.join(temp, 'dl'));
+
+      - name: Extract artifacts
+        shell: bash
+        run: |
+          cd "$RUNNER_TEMP/dl"
+          # Extract each artifact into its own directory to avoid filename collisions
+          for z in *.zip; do
+            [ -f "$z" ] || continue
+            name="${z%.zip}"
+            mkdir -p "$RUNNER_TEMP/artifacts/$name"
+            unzip -o "$z" -d "$RUNNER_TEMP/artifacts/$name"
+          done
+
+      - name: Read PR metadata
+        id: meta
+        shell: bash
+        run: |
+          DIR="$RUNNER_TEMP/artifacts/pr-meta"
+          if [ ! -f "$DIR/pr_number" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "::warning::pr_number artifact missing — skipping report"
+            exit 0
+          fi
+
+          # 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")
+          if ! [[ "$PR_NUM" =~ ^[0-9]+$ ]]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "::error::Invalid PR number in artifact: '$PR_NUM'"
+            exit 0
+          fi
+
+          # 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")
+            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"
+
+      - name: Checkout (for vitest config)
+        if: steps.meta.outputs.skip != 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          sparse-checkout: gitnexus/vitest.config.ts
+          sparse-checkout-cone-mode: false
+
+      # ── Fetch base branch coverage for delta reporting ───────────
+      - name: Fetch base branch coverage
+        if: steps.meta.outputs.skip != 'true'
+        id: base-coverage
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            // Find recent successful CI runs on main (check several in case
+            // the most recent artifact has expired).
+            const runs = await github.rest.actions.listWorkflowRuns({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'ci.yml',
+              branch: 'main',
+              status: 'success',
+              per_page: 5,
+            });
+
+            if (runs.data.workflow_runs.length === 0) {
+              core.setOutput('found', 'false');
+              core.info('No successful main branch CI runs found');
+              return;
+            }
+
+            // Try each run until we find a downloadable test-reports artifact
+            for (const run of runs.data.workflow_runs) {
+              const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                run_id: run.id,
+              });
+
+              const testReports = artifacts.data.artifacts.find(a => a.name === 'test-reports');
+              if (!testReports) {
+                core.info(`Run ${run.id}: no test-reports artifact, trying next`);
+                continue;
+              }
+
+              try {
+                const zip = await github.rest.actions.downloadArtifact({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  artifact_id: testReports.id,
+                  archive_format: 'zip',
+                });
+
+                const dest = path.join(process.env.RUNNER_TEMP, 'base-coverage');
+                fs.mkdirSync(dest, { recursive: true });
+                fs.writeFileSync(path.join(dest, 'base.zip'), Buffer.from(zip.data));
+                core.setOutput('found', 'true');
+                core.setOutput('dir', dest);
+                return;
+              } catch (err) {
+                // 410 Gone means the artifact expired; try the next run
+                if (err.status === 410 || err.response?.status === 410) {
+                  core.info(`Run ${run.id}: artifact expired, trying next`);
+                  continue;
+                }
+                throw err;
+              }
+            }
+
+            // All attempts exhausted — no usable base coverage
+            core.setOutput('found', 'false');
+            core.info('No downloadable test-reports artifact found on main (all expired or missing)');
+
+      - name: Extract base coverage
+        if: steps.meta.outputs.skip != 'true' && steps.base-coverage.outputs.found == 'true'
+        shell: bash
+        run: |
+          cd "${{ steps.base-coverage.outputs.dir }}"
+          mkdir -p base
+          unzip -o base.zip -d base
+
+      - name: Build report
+        if: steps.meta.outputs.skip != 'true'
+        id: report
+        shell: bash
+        env:
+          QUALITY: ${{ steps.meta.outputs.quality }}
+          TESTS: ${{ steps.meta.outputs.tests }}
+          E2E: ${{ steps.meta.outputs.e2e }}
+          BASE_FOUND: ${{ steps.base-coverage.outputs.found }}
+          BASE_DIR: ${{ steps.base-coverage.outputs.dir }}
+          RUN_URL: ${{ github.event.workflow_run.html_url }}
+        run: |
+          DIR="$RUNNER_TEMP/artifacts"
+
+          # ── Helper: read coverage summary into prefixed vars ──
+          read_cov() {
+            local prefix=$1 file=$2
+            if [ -n "$file" ] && [ -f "$file" ]; then
+              local val
+              val=$(jq -r '.total.statements.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_STMTS" '%s' "$val"
+              val=$(jq -r '.total.branches.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_BRANCH" '%s' "$val"
+              val=$(jq -r '.total.functions.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_FUNCS" '%s' "$val"
+              val=$(jq -r '.total.lines.pct // "N/A"' "$file" 2>/dev/null) || val="N/A"
+              printf -v "${prefix}_LINES" '%s' "$val"
+              val=$(jq -r '"\(.total.statements.covered)/\(.total.statements.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_STMTS_COV" '%s' "$val"
+              val=$(jq -r '"\(.total.branches.covered)/\(.total.branches.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_BRANCH_COV" '%s' "$val"
+              val=$(jq -r '"\(.total.functions.covered)/\(.total.functions.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_FUNCS_COV" '%s' "$val"
+              val=$(jq -r '"\(.total.lines.covered)/\(.total.lines.total)"' "$file" 2>/dev/null) || val=""
+              printf -v "${prefix}_LINES_COV" '%s' "$val"
+              return 0
+            else
+              printf -v "${prefix}_STMTS" '%s' "N/A"
+              printf -v "${prefix}_BRANCH" '%s' "N/A"
+              printf -v "${prefix}_FUNCS" '%s' "N/A"
+              printf -v "${prefix}_LINES" '%s' "N/A"
+              printf -v "${prefix}_STMTS_COV" '%s' ""
+              printf -v "${prefix}_BRANCH_COV" '%s' ""
+              printf -v "${prefix}_FUNCS_COV" '%s' ""
+              printf -v "${prefix}_LINES_COV" '%s' ""
+              return 0
+            fi
+          }
+
+          # ── Read coverage reports ──
+          UNIT_SUMMARY=$(find "$DIR/test-reports" -name "coverage-summary.json" -type f 2>/dev/null | head -1)
+
+          read_cov "U" "$UNIT_SUMMARY"
+
+          # ── Read base branch coverage (main) ──
+          BASE_SUMMARY=""
+          if [ "$BASE_FOUND" = "true" ] && [ -n "$BASE_DIR" ]; then
+            BASE_SUMMARY=$(find "$BASE_DIR/base" -name "coverage-summary.json" -type f 2>/dev/null | head -1)
+          fi
+          read_cov "B" "$BASE_SUMMARY"
+
+          # ── Locate test results ──
+          RESULTS_FILE=$(find "$DIR/test-reports" -name "test-results.json" -type f 2>/dev/null | head -1)
+          WEB_RESULTS_FILE=$(find "$DIR/test-reports" -name "web-test-results.json" -type f 2>/dev/null | head -1)
+
+          sum_results() {
+            local file=$1
+            if [ -n "$file" ] && [ -f "$file" ]; then
+              jq -r '"\(.numTotalTests) \(.numPassedTests) \(.numFailedTests) \(.numPendingTests) \(.numTotalTestSuites) \(((.testResults | map(.endTime) | max) - (.startTime)) / 1000 | floor)"' "$file" 2>/dev/null || echo "0 0 0 0 0 0"
+            else
+              echo "0 0 0 0 0 0"
+            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")"
+
+          TOTAL=$((CLI_T + WEB_T))
+          PASSED=$((CLI_P + WEB_P))
+          FAILED=$((CLI_F + WEB_F))
+          SKIPPED=$((CLI_S + WEB_S))
+          DURATION=$((CLI_D > WEB_D ? CLI_D : WEB_D))
+
+          # ── Status helpers ──
+          status_icon() {
+            case "$1" in
+              success) echo "✅" ;;
+              failure) echo "❌" ;;
+              cancelled) echo "⏭️" ;;
+              *) echo "❓" ;;
+            esac
+          }
+
+          # Validate a value looks like a number (integer or decimal, optional
+          # leading minus).  Returns 1 for anything else — guards against awk
+          # injection when artifact values come from untrusted fork code.
+          is_numeric() { [[ "$1" =~ ^-?[0-9]+(\.[0-9]+)?$ ]]; }
+
+          cov_delta() {
+            local pct=$1 base=$2
+            if [ "$pct" = "N/A" ] || [ "$base" = "N/A" ]; then echo "—"; return; fi
+            if ! is_numeric "$pct" || ! is_numeric "$base"; then echo "—"; return; fi
+            local diff
+            diff=$(awk -v p="$pct" -v b="$base" 'BEGIN { printf "%.1f", p - b }')
+            if [ "$(awk -v p="$pct" -v b="$base" 'BEGIN { print (p > b) ? 1 : 0 }')" = "1" ]; then
+              echo "📈 +${diff}"
+            elif [ "$(awk -v p="$pct" -v b="$base" 'BEGIN { print (p < b) ? 1 : 0 }')" = "1" ]; then
+              echo "📉 ${diff}"
+            else
+              echo "＝ ${diff}"
+            fi
+          }
+
+          cov_bar() {
+            local pct=$1 base=$2
+            if [ "$pct" = "N/A" ] || ! is_numeric "$pct"; then echo "—"; return; fi
+            local filled
+            filled=$(awk -v p="$pct" 'BEGIN { printf "%d", p / 5 }')
+            (( filled < 0 )) && filled=0
+            (( filled > 20 )) && filled=20
+            local empty=$((20 - filled))
+            local bar=""
+            for ((i=0; i<filled; i++)); do bar+="█"; done
+            for ((i=0; i<empty; i++)); do bar+="░"; done
+            # Green if >= base (or base unavailable), red if dropped
+            if [ "$base" = "N/A" ] || ! is_numeric "$base" || [ "$(awk -v p="$pct" -v b="$base" 'BEGIN { print (p >= b) ? 1 : 0 }')" = "1" ]; then
+              echo "🟢 ${bar}"
+            else
+              echo "🔴 ${bar}"
+            fi
+          }
+
+          # ── Overall status ──
+          if [[ "$QUALITY" == "success" && "$TESTS" == "success" && ("$E2E" == "success" || "$E2E" == "skipped") ]]; then
+            OVERALL="✅ **All checks passed**"
+          else
+            OVERALL="❌ **Some checks failed**"
+          fi
+
+          # ── Build markdown ──
+          {
+            echo "body<<GITNEXUS_CI_REPORT_EOF_7f3a"
+            echo "## CI Report"
+            echo ""
+            echo "${OVERALL}"
+            echo ""
+            echo "### Pipeline Status"
+            echo ""
+            echo "| Stage | Status | Details |"
+            echo "|-------|--------|---------|"
+            echo "| $(status_icon "$QUALITY") Typecheck | \`${QUALITY}\` | tsc --noEmit |"
+            echo "| $(status_icon "$TESTS") Tests | \`${TESTS}\` | unit tests, 3 platforms |"
+            echo "| $(status_icon "$E2E") E2E | \`${E2E}\` | gitnexus-web changes only |"
+            echo ""
+
+            if [ "$TOTAL" -gt 0 ] 2>/dev/null; then
+              echo "### Test Results"
+              echo ""
+              echo "| Tests | Passed | Failed | Skipped | Duration |"
+              echo "|-------|--------|--------|---------|----------|"
+              echo "| ${TOTAL} | ${PASSED} | ${FAILED} | ${SKIPPED} | ${DURATION}s |"
+              echo ""
+
+              if [ "$FAILED" = "0" ]; then
+                echo "✅ All **${PASSED}** tests passed"
+              else
+                echo "❌ **${FAILED}** failed / **${PASSED}** passed"
+              fi
+              if [ "$SKIPPED" != "0" ]; then
+                echo ""
+                echo "<details>"
+                echo "<summary>${SKIPPED} test(s) skipped — expand for details</summary>"
+                echo ""
+                for rf in "$RESULTS_FILE" "$WEB_RESULTS_FILE"; do
+                  if [ -n "$rf" ] && [ -f "$rf" ]; then
+                    jq -r '
+                      .testResults[]
+                      | .assertionResults[]?
+                      | select(.status == "pending" or .status == "skipped")
+                      | "- \(.ancestorTitles | join(" > ")) > \(.title)"
+                    ' "$rf" 2>/dev/null || true
+                  fi
+                done
+                echo ""
+                echo "</details>"
+              fi
+              echo ""
+            fi
+
+            # ── Coverage table helper ──
+            cov_table() {
+              local label=$1 s=$2 b=$3 f=$4 l=$5 sc=$6 bc=$7 fc=$8 lc=$9
+              shift 9
+              local bs=$1 bb=$2 bf=$3 bl=$4
+              echo "#### ${label}"
+              echo ""
+              echo "| Metric | Coverage | Covered | Base | Delta | Status |"
+              echo "|--------|----------|---------|------|-------|--------|"
+              echo "| Statements | **${s}%** | ${sc} | ${bs}% | $(cov_delta "$s" "$bs") | $(cov_bar "$s" "$bs") |"
+              echo "| Branches | **${b}%** | ${bc} | ${bb}% | $(cov_delta "$b" "$bb") | $(cov_bar "$b" "$bb") |"
+              echo "| Functions | **${f}%** | ${fc} | ${bf}% | $(cov_delta "$f" "$bf") | $(cov_bar "$f" "$bf") |"
+              echo "| Lines | **${l}%** | ${lc} | ${bl}% | $(cov_delta "$l" "$bl") | $(cov_bar "$l" "$bl") |"
+              echo ""
+            }
+
+            if [ "$U_STMTS" != "N/A" ]; then
+              echo "### Code Coverage"
+              echo ""
+              cov_table "Tests" \
+                "$U_STMTS" "$U_BRANCH" "$U_FUNCS" "$U_LINES" \
+                "$U_STMTS_COV" "$U_BRANCH_COV" "$U_FUNCS_COV" "$U_LINES_COV" \
+                "$B_STMTS" "$B_BRANCH" "$B_FUNCS" "$B_LINES"
+            else
+              echo "### Code Coverage"
+              echo ""
+              echo "⚠️ Coverage data unavailable - check the [unit test job](${RUN_URL}) for details."
+              echo ""
+            fi
+
+            echo "---"
+            echo "<sub>📋 [View full run](${RUN_URL}) · Generated by CI</sub>"
+            echo "GITNEXUS_CI_REPORT_EOF_7f3a"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Comment on PR
+        if: steps.meta.outputs.skip != 'true'
+        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
+        with:
+          header: ci-report
+          number: ${{ steps.meta.outputs.pr_number }}
+          message: ${{ steps.report.outputs.body }}

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

@@ -0,0 +1,87 @@
+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.
+#
+# ── Consolidation (chore/vitest-speed-strategy) ────────────────────────
+# Previously each language was a separate GitHub Actions matrix job,
+# meaning N languages × 1 checkout+install+build per shard. The build
+# cost dwarfed the test cost (~5 min setup for ~15 sec test execution).
+#
+# Now a single job runs `scripts/run-parity.ts` which loops through all
+# migrated languages sequentially (2 vitest invocations per language:
+# legacy + registry-primary). All failures are collected and reported
+# at the end (equivalent to the old fail-fast: false behavior).
+#
+# Adding a new language to MIGRATED_LANGUAGES still requires no workflow
+# edit — the script auto-discovers the set at runtime.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  discover:
+    name: Discover migrated languages
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      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
+          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 "has-any=$HAS_ANY" >> "$GITHUB_OUTPUT"
+          echo "Discovered $COUNT migrated language(s): $LANGS"
+          echo "Parity will run: $HAS_ANY"
+
+  parity:
+    name: scope-resolution parity
+    needs: discover
+    if: needs.discover.outputs.has-any == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Run parity for all migrated languages
+        shell: bash
+        working-directory: gitnexus
+        run: npx tsx scripts/run-parity.ts

.github/workflows/ci-tests.yml

@@ -0,0 +1,183 @@
+name: Tests
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: ubuntu / coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Run all tests with coverage
+        run: >-
+          npx vitest run
+          --reporter=default
+          --reporter=json
+          --outputFile=test-results.json
+          --coverage
+          --coverage.reporter=json-summary
+          --coverage.reporter=json
+          --coverage.reporter=text
+          --coverage.thresholdAutoUpdate=false
+          --coverage.reportOnFailure=true
+        working-directory: gitnexus
+
+      # gitnexus-shared already built by setup-gitnexus action above
+      - name: Install gitnexus-web dependencies
+        run: npm ci
+        working-directory: gitnexus-web
+
+      - name: Run gitnexus-web unit tests
+        run: >-
+          npx vitest run
+          --reporter=default
+          --reporter=json
+          --outputFile=web-test-results.json
+        working-directory: gitnexus-web
+
+      - name: Run docker-server integration tests
+        run: node --test docker-server.test.mjs
+
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: test-reports
+          path: |
+            gitnexus/coverage/coverage-summary.json
+            gitnexus/coverage/coverage-final.json
+            gitnexus/test-results.json
+            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)
+    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:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+      - name: Run platform-sensitive tests
+        run: npx tsx scripts/run-cross-platform.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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        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

.github/workflows/ci.yml

@@ -0,0 +1,142 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
+  workflow_call:
+
+permissions:
+  contents: read
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Hardcoded `CI-` prefix (not `${{ github.workflow }}`) because this workflow is
+# invoked as a reusable workflow from publish.yml. 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.
+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' }}
+
+# ── Reusable workflow orchestration ─────────────────────────────────
+# Each concern lives in its own workflow file for maintainability:
+#   ci-quality.yml       — typecheck (tsc --noEmit)
+#   ci-tests.yml         — unit + integration tests with coverage + cross-platform
+#   ci-e2e.yml           — E2E tests (only when gitnexus-web/ changes)
+#   ci-scope-parity.yml  — RFC #909 Ring 3 parity gate: legacy DAG + registry-primary
+#                          both pass, per migrated language in the JSON registry
+#
+# Shared setup is DRY via .github/actions/setup-gitnexus composite action.
+
+jobs:
+  quality:
+    uses: ./.github/workflows/ci-quality.yml
+    permissions:
+      contents: read
+
+  tests:
+    uses: ./.github/workflows/ci-tests.yml
+    permissions:
+      contents: read
+
+  e2e:
+    uses: ./.github/workflows/ci-e2e.yml
+    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
+  # artifact because workflow_run context doesn't reliably carry PR
+  # info for fork PRs.
+  save-pr-meta:
+    name: Save PR Metadata
+    if: always() && github.event_name == 'pull_request'
+    needs: [quality, tests, e2e, scope-parity]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Write metadata
+        shell: bash
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+          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
+          # names.  workflow_run always executes from the default branch, so
+          # the main-branch reader won't find the underscore variants until
+          # this PR is merged.  Write both until then.
+          cp pr-meta/pr_number       pr-meta/pr-number
+          cp pr-meta/quality_result  pr-meta/quality-result
+          cp pr-meta/tests_result    pr-meta/tests-result
+          cp pr-meta/e2e_result      pr-meta/e2e-result
+
+      - name: Upload PR metadata
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: pr-meta
+          path: pr-meta/
+          retention-days: 1
+
+  # ── Unified CI gate ──────────────────────────────────────────────
+  # Single required check for branch protection.
+  ci-status:
+    name: CI Gate
+    needs: [quality, tests, e2e, scope-parity]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check all jobs passed
+        shell: bash
+        env:
+          QUALITY: ${{ needs.quality.result }}
+          TESTS: ${{ needs.tests.result }}
+          E2E: ${{ needs.e2e.result }}
+          SCOPE_PARITY: ${{ needs.scope-parity.result }}
+        run: |
+          echo "Quality:        $QUALITY"
+          echo "Tests:          $TESTS"
+          echo "E2E:            $E2E"
+          echo "Scope parity:   $SCOPE_PARITY"
+          if [[ "$QUALITY" != "success" ]] ||
+             [[ "$TESTS" != "success" ]]; then
+            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

.github/workflows/claude.yml

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

.github/workflows/codeql.yml

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

.github/workflows/dependency-review.yml

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

.github/workflows/docker.yml

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

.github/workflows/gitleaks.yml

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

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

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

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

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

.github/workflows/pr-autofix.yml

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

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

@@ -0,0 +1,95 @@
+name: PR Description Check
+
+on:
+  pull_request:
+    types: [opened, edited, reopened]
+    branches: [main]
+
+permissions:
+  pull-requests: write
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  check-description:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check PR description quality
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const MIN_BODY_LENGTH = 50;
+            const LABEL = 'needs-description';
+
+            const pr = context.payload.pull_request;
+            const body = (pr.body || '').trim();
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const number = pr.number;
+
+            const hasLabel = pr.labels.some(l => l.name === LABEL);
+
+            if (body.length < MIN_BODY_LENGTH) {
+              // Add label if not already present
+              if (!hasLabel) {
+                await github.rest.issues.addLabels({
+                  owner, repo, issue_number: number,
+                  labels: [LABEL],
+                });
+              }
+
+              // Post or update a comment
+              const marker = '<!-- pr-desc-check -->';
+              const message = [
+                marker,
+                `### PR description is too short`,
+                '',
+                `This PR's description is **${body.length}** characters, ` +
+                `but the minimum is **${MIN_BODY_LENGTH}**.`,
+                '',
+                'Please update the PR description to explain:',
+                '- **What** this PR changes',
+                '- **Why** the change is needed',
+                '',
+                'Use the PR template as a guide. This check will re-run when you edit the description.',
+              ].join('\n');
+
+              // Find existing bot comment to update (avoid spam)
+              const comments = await github.rest.issues.listComments({
+                owner, repo, issue_number: number,
+              });
+              const existing = comments.data.find(c =>
+                c.body && c.body.includes(marker)
+              );
+
+              if (existing) {
+                await github.rest.issues.updateComment({
+                  owner, repo, comment_id: existing.id,
+                  body: message,
+                });
+              } else {
+                await github.rest.issues.createComment({
+                  owner, repo, issue_number: number,
+                  body: message,
+                });
+              }
+
+              core.setFailed(
+                `PR description is ${body.length} chars (minimum: ${MIN_BODY_LENGTH})`
+              );
+            } else {
+              // Description is acceptable — remove the label if present
+              if (hasLabel) {
+                await github.rest.issues.removeLabel({
+                  owner, repo, issue_number: number,
+                  name: LABEL,
+                }).catch(() => {});
+                // .catch: label may have been removed manually
+              }
+
+              core.info(`PR description OK (${body.length} chars)`);
+            }

.github/workflows/pr-labeler.yml

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

.github/workflows/publish.yml

@@ -0,0 +1,898 @@
+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.
+# ─────────────────────────────────────────────────────────────────────────────
+
+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.
+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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        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-scope-parity, 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
+
+  # ── 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') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        # 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/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.
+          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
+
+      # ── Stable-only: verify the tag and package.json agree ───────────────
+      - name: Verify version consistency (stable)
+        if: needs.route.outputs.mode == 'stable'
+        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"
+            exit 1
+          fi
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version (v$TAG_VERSION) does not match package.json version ($PKG_VERSION)"
+            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
+        run: npm run build
+        working-directory: gitnexus
+
+      - name: Dry-run publish
+        # Cheap verification that the tarball assembles before the real publish.
+        shell: bash
+        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
+        working-directory: gitnexus
+        env:
+          NPM_TAG: ${{ needs.route.outputs.mode == 'rc' && 'rc' || 'latest' }}
+        run: npm publish --access public --tag "$NPM_TAG"
+
+      # ── Stable-only: pull CHANGELOG body if present ──────────────────────
+      - name: Extract release notes from CHANGELOG (stable)
+        id: changelog
+        if: needs.route.outputs.mode == 'stable'
+        shell: bash
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          NOTES=$(awk "/^## \\[$VERSION\\]/{found=1; next} /^## \\[/{if(found) exit} found" gitnexus/CHANGELOG.md)
+          if [ -z "$NOTES" ]; then
+            echo "::warning::No CHANGELOG entry found for v$VERSION, falling back to auto-generated notes"
+            echo "fallback=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "$NOTES" > /tmp/release-notes.md
+            echo "fallback=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - 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 }}

.github/workflows/scorecard.yml

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

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

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

.github/workflows/triage-sweep.yml

@@ -0,0 +1,105 @@
+name: Triage Sweep
+
+on:
+  workflow_dispatch:
+    inputs:
+      iqr_multiplier:
+        description: >-
+          IQR multiplier for outlier cutoff.
+          cutoff = Q75 + multiplier * IQR.
+          Higher = fewer outliers flagged.
+        type: number
+        default: 3.0
+      max_outlier_pct:
+        description: >-
+          Maximum fraction of items that can be flagged as outliers (0-1).
+          Hard cap to prevent over-flagging.
+        type: number
+        default: 0.05
+      contamination:
+        description: >-
+          Expected fraction of outliers in the data (0-0.5).
+          Controls how aggressively EllipticEnvelope downweights extremes.
+        type: number
+        default: 0.1
+      cosine_threshold:
+        description: >-
+          Cosine similarity threshold for duplicate detection.
+          Pairs with similarity above this are flagged as potential duplicates.
+          Higher = only very similar pairs flagged.
+        type: number
+        default: 0.92
+      max_items:
+        description: >-
+          Maximum number of open issues + PRs to process.
+          Hard cap to prevent runaway costs on very large repos.
+        type: number
+        default: 500
+      dry_run:
+        description: >-
+          Check this to only log results to the workflow summary.
+          Uncheck to create a GitHub issue with the report and apply labels.
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Single global slot — newest manual dispatch supersedes any in-flight run.
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  sweep:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          sparse-checkout: .github/scripts/triage
+          sparse-checkout-cone-mode: false
+          fetch-depth: 1
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: .github/scripts/triage/requirements.txt
+
+      - name: Install dependencies
+        run: pip install -r .github/scripts/triage/requirements.txt
+
+      - name: Cache FastEmbed model weights
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        with:
+          path: ${{ github.workspace }}/.fastembed_cache
+          key: fastembed-bge-small-en-v1.5
+
+      - name: Run triage sweep
+        id: sweep
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          FASTEMBED_CACHE_PATH: ${{ github.workspace }}/.fastembed_cache
+          INPUT_IQR_MULTIPLIER: ${{ inputs.iqr_multiplier }}
+          INPUT_MAX_OUTLIER_PCT: ${{ inputs.max_outlier_pct }}
+          INPUT_CONTAMINATION: ${{ inputs.contamination }}
+          INPUT_COSINE_THRESHOLD: ${{ inputs.cosine_threshold }}
+          INPUT_MAX_ITEMS: ${{ inputs.max_items }}
+          INPUT_DRY_RUN: ${{ inputs.dry_run }}
+        run: python .github/scripts/triage/sweep.py
+
+      - name: Post summary
+        if: always()
+        run: |
+          if [ -f /tmp/triage-report.md ]; then
+            cat /tmp/triage-report.md >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "No report generated." >> "$GITHUB_STEP_SUMMARY"
+          fi

.github/workflows/trivy.yml

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

.github/workflows/workflow-lint.yml

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

.github/zizmor.yml

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

.gitignore

@@ -17,10 +17,13 @@ dist/
 .DS_Store
 Thumbs.db
 
+.claude/settings.local.json
+
 # Environment variables
 .env
 .env.local
 .env.*.local
+docker/.env
 
 # Logs
 *.log
@@ -31,6 +34,8 @@ coverage/
 
 # Misc
 *.local
+HANDOFF.md
+HANDOFF*.md
 
 .vercel
 
@@ -39,3 +44,67 @@ coverage/
 
 
 
+.env*.local
+.gitnexus
+.claude/settings.local.json
+
+# Claude Code worktrees
+.claude/worktrees/
+
+# Claude code skills
+.claude/skills/generated/
+
+# Assets (screenshots, images)
+assets/
+
+# Generated files (should not be indexed)
+repomix-output*
+
+# Playwright artifacts
+gitnexus-web/playwright-report/
+gitnexus-web/test-results/
+
+# Python test artifacts
+eval/.coverage
+eval/.hypothesis/
+
+# Local docs
+docs/
+
+gitnexus/test/fixtures/mini-repo/*.md
+gitnexus/test/fixtures/mini-repo/.claude
+gitnexus/test/fixtures/mini-repo/.gitignore
+
+# Ignore csharp generated obj and bin folders
+gitnexus/test/fixtures/lang-resolution/**/obj
+gitnexus/test/fixtures/lang-resolution/**/bin
+GitNexus.sln
+# Git worktrees
+.worktrees/
+
+# Vendored tree-sitter grammar build artifacts (created at install time,
+# never committed). See docs/plans/2026-04-15-002-fix-tree-sitter-proto-vendor-deps-plan.md
+gitnexus/vendor/**/build/
+gitnexus/vendor/**/node_modules/
+
+/github/scripts/triage/__pycache__/
+
+.claude-flow/
+
+.claude/agents/
+.claude/commands/
+.claude/helpers
+.claude/skills/
+!.claude/skills/gitnexus/
+
+.history/
+
+.swarm/
+
+local_docs/
+
+# Local agent scratch / review prompts (never commit)
+.tmp/
+.agents/
+.context/
+gitnexus/web/

.history/gitnexus/vitest.config_20260317171253.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globalSetup: ['test/global-setup.ts'],
+    include: ['test/**/*.test.ts'],
+    testTimeout: 30000,
+    hookTimeout: 120000,
+    pool: 'forks',
+    globals: true,
+    setupFiles: ['test/setup.ts'],
+    teardownTimeout: 3000,
+    dangerouslyIgnoreUnhandledErrors: true, // LadybugDB N-API destructor segfaults on fork exit — not a test failure
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+      exclude: [
+        'src/cli/index.ts',          // CLI entry point (commander wiring)
+        'src/server/**',              // HTTP server (requires network)
+        'src/core/wiki/**',           // Wiki generation (requires LLM)
+      ],
+      // Auto-ratchet: vitest bumps thresholds when coverage exceeds them.
+      // CI will fail if a PR drops below these floors.
+      thresholds: {
+        statements: 26,
+        branches: 23,
+        functions: 28,
+        lines: 27,
+        autoUpdate: true,
+      },
+    },
+  },
+});

.husky/pre-commit

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Pre-commit hook: format staged files + typecheck.
+# Tests run in CI (ci-tests.yml), not here.
+# Skip with: git commit --no-verify
+
+ROOT="$(git rev-parse --show-toplevel)"
+
+# 1. Format staged files with prettier via lint-staged
+echo "pre-commit: formatting staged files..."
+"$ROOT/node_modules/.bin/lint-staged" || exit 1
+
+# 2. Typecheck changed packages
+WEB_CHANGED=$(git diff --cached --name-only -- 'gitnexus-web/' | head -1)
+CLI_CHANGED=$(git diff --cached --name-only -- 'gitnexus/' | head -1)
+
+if [ -n "$WEB_CHANGED" ]; then
+  echo "pre-commit: typechecking gitnexus-web (tsc -b)..."
+  cd "$ROOT/gitnexus-web" && ./node_modules/.bin/tsc -b --noEmit || exit 1
+fi
+
+if [ -n "$CLI_CHANGED" ]; then
+  echo "pre-commit: typechecking gitnexus..."
+  cd "$ROOT/gitnexus" && ./node_modules/.bin/tsc --noEmit || exit 1
+fi
+
+echo "pre-commit: all checks passed"

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

.prettierignore

@@ -0,0 +1,17 @@
+dist/
+coverage/
+gitnexus/vendor/
+gitnexus/test/fixtures/
+gitnexus-web/test/fixtures/
+gitnexus-web/playwright-report/
+gitnexus-web/test-results/
+*.d.ts
+*.snap
+*.wasm
+*.md
+.gitnexus/
+.vercel/
+.claude-flow/
+.swarm/
+assets/
+repomix-output*

.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-tailwindcss"],
+  "tailwindStylesheet": "./gitnexus-web/src/index.css"
+}

.sisyphus/drafts/gitnexus-brainstorming.md

@@ -0,0 +1,18 @@
+# Draft: Gitnexus Brainstorming - Clustering & Process Maps
+
+## Initial Context
+- Project: **GitnexusV2**
+- Structure: 
+    - `gitnexus/` (Likely the core application)
+    - `gitnexus-mcp/` (Likely a Model Context Protocol server)
+- Goal: Make it accurate and usable for smaller/dumber models.
+- Current Focus: Implementing **Clustering** and **Process Maps**.
+
+## Findings
+- **Clustering**: Found `gitnexus/src/core/ingestion/cluster-enricher.ts`.
+- **Process Maps**: No files matched `*process*map*` yet. Searching content next.
+
+## Open Questions
+- How is "process map" defined in this context? (Graph, mermaid diagram, flowchart?)
+- What is the input for clustering? (Code chunks, files, commits?)
+- What is the intended output for "smaller models"? (Simplified context, summaries?)

.sisyphus/drafts/noodlbox-comparison.md

@@ -0,0 +1,34 @@
+# Draft: Gitnexus vs Noodlbox Strategy
+
+## Objectives
+- Understand GitnexusV2 current state and goals.
+- Analyze Noodlbox capabilities from provided URL.
+- Compare features, architecture, and value proposition.
+- Provide strategic views and recommendations.
+
+## Research Findings
+- [GitnexusV2]: Zero-server, browser-native (WASM), KuzuDB based. Graph + Vector hybrid search.
+- [Noodlbox]: CLI-first, heavy install. Has "Session Hooks" and "Search Hooks" via plugins/CLI.
+
+## Comparison Points
+- **Core Philosophy**: Both bet on "Knowledge Graph + MCP" as the future. Noodlbox validates Gitnexus's direction.
+- **Architecture**:
+  - *Noodlbox*: CLI/Binary based. Likely local server management.
+  - *Gitnexus*: Zero-server, Browser-native (WASM). Lower friction, higher privacy.
+- **Features**:
+  - *Communities/Processes*: Both have them. Noodlbox uses them for "context injection". Gitnexus uses them for "visual exploration + query".
+  - *Impact Analysis*: Noodlbox has polished workflows (e.g., `detect_impact staged`). Gitnexus has the engine (`blastRadius`) but maybe not the specific workflow wrappers yet.
+- **UX/Integration**:
+  - *Noodlbox*: "Hooks" (Session/Search) are a killer feature. Proactively injecting context into the agent's session.
+  - *Gitnexus*: Powerful tools, but relies on agent *pulling* data?
+
+## Strategic Views
+1. **Validation**: The market direction is confirmed. You are building the right thing.
+2. **differentiation**: Lean into "Zero-Setup / Browser-Native". Noodlbox requires `noodl init` and CLI handling. Gitnexus could just *be*.
+3. **Opportunity**: Steal the "Session/Search Hooks" pattern. Make the agent smarter *automatically* without the user asking "check impact".
+4. **Workflow Polish**: Noodlbox's `/detect_impact staged` is a great specific use case. Gitnexus should wrap `blastRadius` into similar concrete workflows.
+
+## Technical Feasibility (Interception)
+- **Cursor**: Use `.cursorrules` to "shadow" default tools. Instruct agent to ALWAYS use `gitnexus_search` instead of `grep`.
+- **Claude Code**: Likely uses a private plugin API for `PreToolUse`. We can't match this exactly without an official plugin, but we can approximate it with strong prompt instructions in `AGENTS.md`.
+- **MCP Shadowing**: Define tools with names that conflict (e.g., `grep`)? No, unsafe. Better to use "Virtual Hooks" via system prompt instructions.

.windsurfrules

@@ -0,0 +1,5 @@
+# AI Agent Rules
+
+Follow .gitnexus/RULES.md for all project context and coding guidelines.
+
+This project uses GitNexus MCP for code intelligence. See .gitnexus/RULES.md for available tools and best practices.

AGENTS.md

@@ -0,0 +1,167 @@
+<!-- version: 1.7.0 -->
+<!-- Last updated: 2026-04-23 -->
+
+Last reviewed: 2026-04-23
+
+**Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
+
+## Scope
+
+| Boundary | Rule |
+|----------|------|
+| **Reads** | `gitnexus/`, `gitnexus-web/`, `eval/`, plugin packages, `.github/`, `.gitnexus/`, docs. |
+| **Writes** | Only paths required for the change; keep diffs minimal. Update lockfiles when deps change. |
+| **Executes** | `npm`, `npx`, `node` under `gitnexus/` and `gitnexus-web/`; `uv run` for Python under `eval/`; documented CI/dev workflows. |
+| **Off-limits** | Real `.env` / secrets, production credentials, unrelated repos, destructive git ops without confirmation. |
+
+## Model Configuration
+
+- **Primary:** Use a named model (e.g. Claude Sonnet 4.x). Avoid `Auto` or unversioned `latest` when reproducibility matters.
+- **Notes:** The GitNexus CLI indexer does not call an LLM.
+
+## Execution Sequence (complex tasks)
+
+For multi-step work, state up front:
+1. Which rules in this file and **[GUARDRAILS.md](GUARDRAILS.md)** apply (and any relevant Signs).
+2. Current **Scope** boundaries.
+3. Which **validation commands** you will run (`cd gitnexus && npm test`, `npx tsc --noEmit`).
+
+On long threads, *"Remember: apply all AGENTS.md rules"* re-weights these instructions against context dilution.
+
+## Claude Code hooks
+
+**PreToolUse** hooks can block tools (e.g. `git_commit`) until checks pass. Adapt to this repo: `cd gitnexus && npm test` before commit.
+
+## Context budget
+
+Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.md](CONTRIBUTING.md)**. If always-on rules grow, split into **`.cursor/rules/*.mdc`** (globs). **Cursor:** project-wide rules in `.cursor/index.mdc`. **Claude Code:** load `STANDARDS.md` only when needed.
+
+## Reference docs
+
+- **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**
+- **Call-resolution DAG (legacy path):** See ARCHITECTURE.md § Call-Resolution DAG. Typed 6-stage DAG inside the `parse` phase; language-specific behavior behind `inferImplicitReceiver` / `selectDispatch` hooks on `LanguageProvider`. Shared code in `gitnexus/src/core/ingestion/` must not name languages. Types: `gitnexus/src/core/ingestion/call-types.ts`.
+- **Scope-resolution pipeline (RFC #909 Ring 3):** See ARCHITECTURE.md § Scope-Resolution Pipeline. Replaces the legacy DAG for languages in `MIGRATED_LANGUAGES` (see `registry-primary-flag.ts`). A language plugs in by implementing `ScopeResolver` (`scope-resolution/contract/scope-resolver.ts`) and registering it in `SCOPE_RESOLVERS`. CI parity gate runs BOTH paths per migrated language on every PR.
+- **Cursor:** `.cursor/index.mdc` (always-on); `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` deprecated.
+- **GitNexus:** skills in `.claude/skills/gitnexus/`; MCP rules in `gitnexus:start` block below.
+
+## 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. |
+| 2026-04-16 | 1.4.0 | Fixed: web UI description, pre-commit behavior, MCP tools (7->16), added gitnexus-shared, removed stale vite-plugin-wasm gotcha. |
+| 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. |
+| 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication. |
+| 2026-03-23 | 1.1.0 | Updated agent instructions, references, Cursor layout. |
+| 2026-03-22 | 1.0.0 | Initial structured header and changelog. |
+
+---
+
+<!-- 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.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## 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 -->
+
+## Repo reference
+
+### Packages
+
+| Package | Path | Purpose |
+|---------|------|---------|
+| **CLI/Core** | `gitnexus/` | TypeScript CLI, indexing pipeline, MCP server. Published to npm. |
+| **Web UI** | `gitnexus-web/` | React/Vite thin client. All queries via `gitnexus serve` HTTP API. |
+| **Shared** | `gitnexus-shared/` | Shared TypeScript types and constants. |
+| Claude Plugin | `gitnexus-claude-plugin/` | Static config for Claude marketplace. |
+| Cursor Integration | `gitnexus-cursor-integration/` | Static config for Cursor editor. |
+| Eval | `eval/` | Python evaluation harness (Docker + LLM API keys). |
+
+### Running services
+
+```bash
+cd gitnexus && npm run dev                 # CLI: tsx watch mode
+cd gitnexus-web && npm run dev             # Web UI: Vite on port 5173
+npx gitnexus serve                         # HTTP API on port 4747 (from any indexed repo)
+```
+
+### Testing
+
+**CLI / Core (`gitnexus/`)**
+- `npm test` — full vitest suite (~2000 tests)
+- `npm run test:unit` — unit tests only
+- `npm run test:integration` — integration (~1850 tests). LadybugDB file-locking tests may fail in containers (known env issue).
+- `npx tsc --noEmit` — typecheck
+
+**Web UI (`gitnexus-web/`)**
+- `npm test` — vitest (~200 tests)
+- `npm run test:e2e` — Playwright (7 spec files; requires `gitnexus serve` + `npm run dev`)
+- `npx tsc -b --noEmit` — typecheck
+
+**Pre-commit hook** (`.husky/pre-commit`): formatting (prettier via lint-staged) + typecheck for staged packages. Tests do **not** run in pre-commit — CI only.
+
+### Gotchas
+
+- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (patches tree-sitter-swift, builds tree-sitter-proto). Native bindings need `python3`, `make`, `g++`.
+- `tree-sitter-kotlin` and `tree-sitter-swift` are optional — install warnings expected.
+- ESLint configured via `eslint.config.mjs` (TS, React Hooks, unused-imports). No `npm run lint` script; use `npx eslint .`. Prettier runs via lint-staged. CI checks both in `ci-quality.yml`.

ARCHITECTURE.md

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

CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+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
+
+- **TypeScript/JavaScript MethodExtractor config** — shared extraction config covering abstract methods, visibility modifiers, async/override keywords, decorators, rest/optional/destructured parameters, and return types (#588) — @compound-ai
+
+### Fixed
+
+- **Azure OpenAI compatibility** — use `max_completion_tokens` instead of deprecated `max_tokens` (newer models reject `max_tokens`); skip `temperature` for Azure provider (some models reject non-default values) (#618)
+- **Simplified Azure interactive setup** — 3 prompts (endpoint, deployment, key) instead of 7 (#618)
+- **Wiki HTML viewer script injection** — escape `</script>` in embedded JSON so LLM-generated markdown no longer breaks the viewer (#618)
+- Ensure import rewrites survive npm publish lifecycle
+
+## [1.4.0] - 2026-03-13
+
+### Added
+
+- **Language-aware symbol resolution engine** with 3-tier resolver: exact FQN → scope-walk → guarded fuzzy fallback that refuses ambiguous matches (#238) — @magyargergo
+- **Method Resolution Order (MRO)** with 5 language-specific strategies: C++ leftmost-base, C#/Java class-over-interface, Python C3 linearization, Rust qualified syntax, default BFS (#238) — @magyargergo
+- **Constructor & struct literal resolution** across all languages — `new Foo()`, `User{...}`, C# primary constructors, target-typed new (#238) — @magyargergo
+- **Receiver-constrained resolution** using per-file TypeEnv — disambiguates `user.save()` vs `repo.save()` via `ownerId` matching (#238) — @magyargergo
+- **Heritage & ownership edges** — HAS_METHOD, OVERRIDES, Go struct embedding, Swift extension heritage, method signatures (`parameterCount`, `returnType`) (#238) — @magyargergo
+- **Language-specific resolver directory** (`resolvers/`) — extracted JVM, Go, C#, PHP, Rust resolvers from monolithic import-processor (#238) — @magyargergo
+- **Type extractor directory** (`type-extractors/`) — per-language type binding extraction with `Record<SupportedLanguages, Handler>` + `satisfies` dispatch (#238) — @magyargergo
+- **Export detection dispatch table** — compile-time exhaustive `Record` + `satisfies` pattern replacing switch/if chains (#238) — @magyargergo
+- **Language config module** (`language-config.ts`) — centralized tsconfig, go.mod, composer.json, .csproj, Swift package config loaders (#238) — @magyargergo
+- **Optional skill generation** via `npx gitnexus analyze --skills` — generates AI agent skills from KuzuDB knowledge graph (#171) — @zander-raycraft
+- **First-class C# support** — sibling-based modifier scanning, record/delegate/property/field/event declaration types (#163, #170, #178 via #237) — @Alice523, @benny-yamagata, @jnMetaCode
+- **C/C++ support fixes** — `.h` → C++ mapping, static-linkage export detection, qualified/parenthesized declarators, 48 entry point patterns (#163, #227 via #237) — @Alice523, @bitgineer
+- **Rust support fixes** — sibling-based `visibility_modifier` scanning for `pub` detection (#227 via #237) — @bitgineer
+- **Adaptive tree-sitter buffer sizing** — `Math.min(Math.max(contentLength * 2, 512KB), 32MB)` (#216 via #237) — @JasonOA888
+- **Call expression matching** in tree-sitter queries (#234 via #237) — @ex-nihilo-jg
+- **DeepSeek model configurations** (#217) — @JasonOA888
+- 282+ new unit tests, 178 integration resolver tests across 9 languages, 53 test files, 1146 total tests passing
+
+### Fixed
+
+- Skip unavailable native Swift parsers in sequential ingestion (#188) — @Gujiassh
+- Heritage heuristic language-gated — no longer applies class/interface rules to wrong languages (#238) — @magyargergo
+- C# `base_list` distinguishes EXTENDS vs IMPLEMENTS via symbol table + `I[A-Z]` heuristic (#238) — @magyargergo
+- Go `qualified_type` (`models.User`) correctly unwrapped in TypeEnv (#238) — @magyargergo
+- Global tier no longer blocks resolution when kind/arity filtering can narrow to 1 candidate (#238) — @magyargergo
+
+### Changed
+
+- `import-processor.ts` reduced from 1412 → 711 lines (50% reduction) via resolver and config extraction (#238) — @magyargergo
+- `type-env.ts` reduced from 635 → ~125 lines via type-extractor extraction (#238) — @magyargergo
+- CI/CD workflows hardened with security fixes and fork PR support (#222, #225) — @magyargergo
+
+## [1.3.11] - 2026-03-08
+
+### Security
+
+- Fix FTS Cypher injection by escaping backslashes in search queries (#209) — @magyargergo
+
+### Added
+
+- Auto-reindex hook that runs `gitnexus analyze` after commits and merges, with automatic embeddings preservation (#205) — @L1nusB
+- 968 integration tests (up from ~840) covering unhappy paths across search, enrichment, CLI, pipeline, worker pool, and KuzuDB (#209) — @magyargergo
+- Coverage auto-ratcheting so thresholds bump automatically on CI (#209) — @magyargergo
+- Rich CI PR report with coverage bars, test counts, and threshold tracking (#209) — @magyargergo
+- Modular CI workflow architecture with separate unit-test, integration-test, and orchestrator jobs (#209) — @magyargergo
+
+### Fixed
+
+- KuzuDB native addon crashes on Linux/macOS by running integration tests in isolated vitest processes with `--pool=forks` (#209) — @magyargergo
+- Worker pool `MODULE_NOT_FOUND` crash when script path is invalid (#209) — @magyargergo
+
+### Changed
+
+- Added macOS to the cross-platform CI test matrix (#208) — @magyargergo
+
+## [1.3.10] - 2026-03-07
+
+### Security
+
+- **MCP transport buffer cap**: Added 10 MB `MAX_BUFFER_SIZE` limit to prevent out-of-memory attacks via oversized `Content-Length` headers or unbounded newline-delimited input
+- **Content-Length validation**: Reject `Content-Length` values exceeding the buffer cap before allocating memory
+- **Stack overflow prevention**: Replaced recursive `readNewlineMessage` with iterative loop to prevent stack overflow from consecutive empty lines
+- **Ambiguous prefix hardening**: Tightened `looksLikeContentLength` to require 14+ bytes before matching, preventing false framing detection on short input
+- **Closed transport guard**: `send()` now rejects with a clear error when called after `close()`, with proper write-error propagation
+
+### Added
+
+- **Dual-framing MCP transport** (`CompatibleStdioServerTransport`): Auto-detects Content-Length (Codex/OpenCode) and newline-delimited JSON (Cursor/Claude Code) framing on the first message, responds in the same format (#207)
+- **Lazy CLI module loading**: All CLI subcommands now use `createLazyAction()` to defer heavy imports (tree-sitter, ONNX, KuzuDB) until invocation, significantly improving `gitnexus mcp` startup time (#207)
+- **Type-safe lazy actions**: `createLazyAction` uses constrained generics to validate export names against module types at compile time
+- **Regression test suite**: 13 unit tests covering transport framing, security hardening, buffer limits, and lazy action loading
+
+### Fixed
+
+- **CALLS edge sourceId alignment**: `findEnclosingFunctionId` now generates IDs with `:startLine` suffix matching node creation format, fixing process detector finding 0 entry points (#194)
+- **LRU cache zero maxSize crash**: Guard `createASTCache` against `maxSize=0` when repos have no parseable files (#144)
+
+### Changed
+
+- Transport constructor accepts `NodeJS.ReadableStream` / `NodeJS.WritableStream` (widened from concrete `ReadStream`/`WriteStream`)
+- `processReadBuffer` simplified to break on first error instead of stale-buffer retry loop
+
+## [1.3.9] - 2026-03-06
+
+### Fixed
+
+- Aligned CALLS edge sourceId with node ID format in parse worker (#194)
+
+## [1.3.8] - 2026-03-05
+
+### Fixed
+
+- Force-exit after analyze to prevent KuzuDB native cleanup hang (#192)

CLAUDE.md

@@ -0,0 +1,118 @@
+<!-- version: 1.3.0 -->
+<!--
+  Metadata: version, last reviewed, scope, model policy, reference docs, changelog.
+  Last updated: 2026-03-22
+-->
+
+Last reviewed: 2026-04-13
+
+**Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
+
+Follow **AGENTS.md** for the canonical rules; this file adds Claude Code–specific deltas. Cursor-specific notes live only in `AGENTS.md`.
+
+## Scope
+
+See the **Scope** table in [AGENTS.md](AGENTS.md) for read/write/execute/off-limits boundaries. Cursor-specific workflow notes also live only in AGENTS.md.
+
+## Model Configuration
+
+- **Primary:** Pin per **Claude Code** / Anthropic org policy (explicit model id). Do not rely on an unversioned `latest` alias for governed workflows.
+- **Fallback:** As configured in Claude Code (organization default or user override).
+- **Notes:** The GitNexus CLI analyzer does not call an LLM.
+
+## Execution Sequence (complex tasks)
+
+Same discipline as [AGENTS.md](AGENTS.md): before large multi-step work, state which **AGENTS.md** / **GUARDRAILS.md** rules apply, current **Scope**, and planned validation commands (`npm test`, `tsc`, etc.). When pausing, summarize progress in the chat or a **local** scratch file (do not add `HANDOFF.md` to the repo), then `/clear` and resume with that summary.
+
+## Claude Code hooks
+
+Prefer **PreToolUse** hooks for hard gates (e.g. tests before `git_commit`). Adapt hook commands to `gitnexus/` npm scripts.
+
+## Context budget
+
+If always-on instructions grow, load deep conventions via conditional reads (e.g. *“When writing new code, read STANDARDS.md”*) instead of pasting long blocks here. In Cursor, prefer `.cursor/index.mdc` plus optional `.cursor/rules/*.mdc` globs (see [AGENTS.md](AGENTS.md) § Context budget).
+
+## Reference Documentation
+
+- **This repository:** [AGENTS.md](AGENTS.md) (Cursor + monorepo notes), [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md), [GUARDRAILS.md](GUARDRAILS.md).
+- **Call-resolution DAG:** See ARCHITECTURE.md § Call-Resolution DAG. Shared pipeline code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` hooks instead (see AGENTS.md).
+- **GitNexus:** `.claude/skills/gitnexus/`; MCP and indexed-repo rules live only in [AGENTS.md](AGENTS.md) (`gitnexus:start` … `gitnexus:end`). See **GitNexus rules** below.
+
+## Changelog
+
+| Date | Version | Change |
+|------|---------|--------|
+| 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. |
+| 2026-03-24 | 1.2.0 | Removed duplicated gitnexus:start block and scope table; replaced with pointers to AGENTS.md. |
+| 2026-03-23 | 1.1.0 | Updated agent instructions to match AGENTS.md. |
+| 2026-03-22 | 1.0.0 | Added structured header and changelog. |
+
+---
+
+## 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.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## 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 -->

CONTRIBUTING.md

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

DoD.md

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

Dockerfile.cli

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

Dockerfile.web

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

GUARDRAILS.md

@@ -0,0 +1,91 @@
+# Guardrails — GitNexus
+
+Rules for **human contributors** and **AI agents**. Complements `AGENTS.md` (workflows) and `CONTRIBUTING.md` (PR process).
+
+## Scope (least privilege)
+
+- **Read:** Source, tests, docs, public config as needed.
+- **Write:** Only files required for the fix or feature; no unrelated formatting or refactors.
+- **Execute:** Tests, typecheck, documented CLI commands. No destructive commands on user data without approval.
+- **Off-limits:** Other people's machines, production deployments you don't own, credentials you lack permission to use.
+
+Maintainer may widen scope per task.
+
+---
+
+## Non-negotiables
+
+1. **Never commit secrets** — API keys, tokens, real `.env` values, private URLs, session cookies. Use `.env.example` with placeholders.
+2. **Never rename with find-and-replace** in GitNexus-indexed projects — use `rename` MCP tool with `dry_run: true` first, review `graph` vs `text_search` edits. No separate `gitnexus rename` CLI exists.
+3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
+4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
+5. **Preserve embeddings** — plain `npx gitnexus analyze` now preserves any embeddings recorded in `.gitnexus/meta.json` (the previous behavior wiped them). Use `--embeddings` to also generate vectors for new/changed nodes; use `--drop-embeddings` only when an explicit wipe is intended (e.g., model swap).
+
+---
+
+## Signs (recurring failure patterns)
+
+Format: **Trigger → Instruction → Reason**. Append new Signs when the same mistake repeats.
+
+### Stale graph after edits
+
+- **Trigger:** MCP warns index is behind `HEAD`, or search doesn't match latest commit.
+- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used). Runs incrementally by default — the pipeline parses every file every run (cross-file resolution requires it), but tree-sitter dispatch is skipped for unchanged file chunks via the content-addressed cache, and only changed-file rows (plus their importers, transitively) are rewritten in LadybugDB.
+- **Why:** Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.
+
+### 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.
+- **Do:** Re-run `npx gitnexus analyze --embeddings` to regenerate. Check the analyze log for a `Warning: could not load cached embeddings` line — if present, the cache restore failed (corrupt DB / schema mismatch) and the rebuild had nothing to preserve. If you intentionally passed `--drop-embeddings`, this is expected.
+- **Why:** Plain `analyze` preserves prior vectors by re-inserting them after the rebuild; the only ways to end up at zero are an explicit `--drop-embeddings`, a cache-load failure (now logged), or a model/dimension change that invalidates the cache.
+
+### MCP lists no repos
+
+- **Trigger:** MCP stderr says no indexed repos.
+- **Do:** `npx gitnexus analyze` in the target repo; verify `npx gitnexus list` shows it.
+- **Why:** MCP discovers repos via `~/.gitnexus/registry.json`, populated by analyze.
+
+### Wrong repo in multi-repo setups
+
+- **Trigger:** Query/impact results belong to another project.
+- **Do:** Call `list_repos`, then pass `repo` on subsequent tools.
+- **Why:** Default target is ambiguous when multiple repos are registered.
+
+### LadybugDB lock / "database busy"
+
+- **Trigger:** Errors opening `.gitnexus/lbug` while MCP and analyze both run.
+- **Do:** Stop overlapping processes (one writer at a time). Retry analyze or restart MCP.
+- **Why:** Embedded DB expects single-process ownership.
+
+---
+
+## Publishing & supply chain
+
+- **npm:** Do not publish from unreviewed automation. Bump version intentionally; tag releases to match `package.json`.
+- **Dependencies:** Minimal, auditable `package.json` changes; run tests and CI after lockfile updates.
+- **License:** PolyForm Noncommercial 1.0.0 — do not relicense without maintainer approval.
+
+---
+
+## Escalation
+
+Stop and ask a **human maintainer** when:
+
+- Impact analysis shows HIGH/CRITICAL risk and the task still requires the change.
+- You need to alter CI, release, or security-sensitive config.
+- Requirements conflict (e.g. "speed up analyze" vs "must keep all embeddings on huge repo").
+- You are unsure whether data loss is acceptable (`clean`, forced migrations, schema changes).
+
+---
+
+## Related docs
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow
+- [RUNBOOK.md](RUNBOOK.md) — commands for recovery
+- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations

LICENSE

@@ -0,0 +1,73 @@
+PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Abhigyan Patwari (https://github.com/abhigyanpatwari/GitNexus)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

MIGRATION.md

@@ -0,0 +1,71 @@
+# Migration Guide
+
+## `impact` tool may now return `{ status: 'ambiguous' }` (PR #888, issue #470)
+
+Before this change the `impact` MCP tool silently picked the first match
+when the `target` name hit multiple symbols (Class → Interface → Function
+→ Method → Constructor priority UNION). This often produced analysis for
+the wrong symbol with no signal back to the caller.
+
+After this change, when the resolver finds more than one viable match
+and the caller supplied none of `target_uid` / `file_path` / `kind`,
+`impact` returns a disambiguation response shaped like:
+
+```json
+{
+  "status": "ambiguous",
+  "message": "Found N symbols matching '<target>'. Use target_uid, file_path, or kind to disambiguate.",
+  "target": { "name": "<target>" },
+  "direction": "upstream",
+  "impactedCount": 0,
+  "risk": "UNKNOWN",
+  "candidates": [
+    { "uid": "...", "name": "...", "kind": "Function", "filePath": "...", "line": 42, "score": 0.76 }
+  ]
+}
+```
+
+### Do I need to migrate?
+
+**Probably not, but check for assumptions.** Callers that unconditionally
+read `result.byDepth` / `result.summary` / `result.affected_processes`
+without first checking `result.status` will now see `undefined` in the
+ambiguous case. The fix is to branch on `result.status === 'ambiguous'`
+first and follow up with `target_uid` (preferred) or `file_path` / `kind`.
+
+The `context` tool's ambiguous response is a strict superset of the
+existing shape — every candidate gains a `score` field, no existing field
+has changed. No migration required for `context` callers.
+
+### What happens on re-index?
+
+Nothing — this is an MCP-surface change only. The graph schema, indexer,
+and stored data are untouched.
+
+---
+
+## OVERRIDES → METHOD_OVERRIDES (PR #642)
+
+The `OVERRIDES` relationship type has been renamed to `METHOD_OVERRIDES` for
+consistency with the new `METHOD_IMPLEMENTS` edge type.
+
+### Do I need to migrate?
+
+**No.** Backward compatibility is handled automatically at runtime:
+
+- `local-backend.ts` dual-reads both `OVERRIDES` and `METHOD_OVERRIDES` in all
+  impact-analysis and context queries. Existing stored graphs with `OVERRIDES`
+  edges continue to return correct results without any manual intervention.
+- The `REL_TYPES` array in `schema-constants.ts` includes both names so Cypher
+  queries that reference either will work.
+
+### What happens on re-index?
+
+Running `npx gitnexus analyze` on a repository produces `METHOD_OVERRIDES`
+edges going forward. The old `OVERRIDES` edges are replaced as part of the
+normal full re-index.
+
+### When will the legacy alias be removed?
+
+The `OVERRIDES` compat alias will remain until a future major version. Removal
+will be announced in this file and in the changelog before it happens.

RUNBOOK.md

@@ -0,0 +1,163 @@
+# Runbook — GitNexus
+
+Short, copy-paste operations for **local development**, **MCP**, and **CI**. Commands assume a Unix shell; on Windows use Git Bash or equivalent paths.
+
+## Prerequisites
+
+- **Node.js** ≥ 20 (`gitnexus-web/package.json` `engines`).  
+- **Git** (analyze requires a git repository).  
+- From repo root, install and build the CLI package:
+
+```bash
+cd gitnexus
+npm install
+npm run build
+```
+
+Use `npx gitnexus …` from any path after global/published install, or `node dist/cli/index.js …` when developing from `gitnexus/` with a local build.
+
+---
+
+## Index out of date / “stale” tools
+
+**Symptom:** MCP or resources warn the index is behind `HEAD`, or results don’t reflect recent commits.
+
+**Fix (from the target repo root):**
+
+```bash
+npx gitnexus analyze
+```
+
+**Force full rebuild** (same commit but suspect corruption or changed ignore rules):
+
+```bash
+npx gitnexus analyze --force
+```
+
+**Check status:**
+
+```bash
+npx gitnexus status
+```
+
+**List what MCP knows about:**
+
+```bash
+npx gitnexus list
+```
+
+---
+
+## Embeddings
+
+**First time with vectors** (slower, more disk/RAM):
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+**Important:** If you already had embeddings, **always** pass `--embeddings` on later analyzes, or they can be dropped. See `stats.embeddings` in `.gitnexus/meta.json` (0 means none).
+
+**Large repos:** Analyze may skip or limit embedding work when node counts are very high; watch CLI output.
+
+---
+
+## MCP: no repos / empty tools
+
+**Symptom:** `GitNexus: No indexed repos yet` on stderr when starting MCP.
+
+**Fix:** In each project you want indexed:
+
+```bash
+cd /path/to/repo
+npx gitnexus analyze
+```
+
+Restart the editor MCP session if needed. The server **refreshes the registry lazily**; new analyzes are picked up without necessarily reinstalling MCP.
+
+**Symptom:** Wrong repo when multiple are indexed — pass `repo` on tools or use `list_repos` first.
+
+---
+
+## Clean slate (corrupt or huge `.gitnexus`)
+
+**Current repo only** (prompts for confirmation):
+
+```bash
+npx gitnexus clean
+```
+
+**Skip confirmation:**
+
+```bash
+npx gitnexus clean --force
+```
+
+**All registered repos:**
+
+```bash
+npx gitnexus clean --all --force
+```
+
+Then re-run `npx gitnexus analyze` (and `--embeddings` if you need vectors).
+
+---
+
+## Local bridge for the web UI
+
+```bash
+cd gitnexus
+npx gitnexus serve
+# default http://127.0.0.1:4747 — see serve --help for port/host
+```
+
+Use when the browser UI should talk to **local** indexed repos instead of WASM-only mode.
+
+---
+
+## CLI equivalents of MCP tools
+
+Useful for debugging without an editor:
+
+```bash
+cd gitnexus
+npx gitnexus query "authentication flow" --repo MyRepo
+npx gitnexus context SomeSymbol --repo MyRepo
+npx gitnexus impact SomeSymbol --direction upstream --repo MyRepo
+npx gitnexus cypher "MATCH (n) RETURN count(n) LIMIT 1" --repo MyRepo
+```
+
+---
+
+## CI failures (contributors)
+
+Orchestrator: `.github/workflows/ci.yml`.
+
+| Job | Typical local repro |
+|-----|---------------------|
+| **quality** | `cd gitnexus && npx tsc --noEmit` |
+| **unit-tests** | `cd gitnexus && npx vitest run test/unit` |
+| **integration** | `cd gitnexus && npx vitest run test/integration` (see workflow matrix for groups) |
+| **e2e** | Triggered when `gitnexus-web/` changes; `cd gitnexus-web && E2E=1 npx playwright test` (requires `gitnexus serve` + `npm run dev`) |
+
+**Note:** Pushes that touch only certain markdown paths may be skipped by `paths-ignore` in CI — see workflow file for exact patterns.
+
+---
+
+## Memory / analyze crashes
+
+Analyze re-execs Node with a **large old-space heap** when needed (`analyze.ts`). If you still OOM on huge repos, close other processes, avoid `--embeddings` for a first pass, or analyze a smaller path if supported by your workflow.
+
+---
+
+## LadybugDB / lock errors
+
+Only one process should open a repo’s `.gitnexus/lbug` store at a time. If MCP and a second `analyze` run conflict, stop one process, then retry `analyze` or restart MCP.
+
+---
+
+## Where to dig deeper
+
+- Architecture overview: [ARCHITECTURE.md](ARCHITECTURE.md)  
+- Agent safety rules: [GUARDRAILS.md](GUARDRAILS.md)  
+- Tests: [TESTING.md](TESTING.md)

SECURITY.md

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

TESTING.md

@@ -0,0 +1,143 @@
+# Testing — GitNexus
+
+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   |
+
+## Test lanes
+
+### `gitnexus/` commands
+
+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
+
+```bash
+cd gitnexus && npx tsc --noEmit && npm test
+cd ../gitnexus-web && npx tsc -b --noEmit && npm test
+```
+
+## Pre-commit hook
+
+A husky pre-commit hook (`.husky/pre-commit`) runs automatically on every `git commit`:
+
+1. **Formatting** — `lint-staged` runs prettier on staged files
+2. **`gitnexus-web/` files staged** → `tsc -b --noEmit`
+3. **`gitnexus/` files staged** → `tsc --noEmit`
+
+Tests do **not** run in the pre-commit hook — they run in CI (`ci-tests.yml`) only.
+
+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/`.
+- **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 parity
+
+Migrated languages (listed in `MIGRATED_LANGUAGES` in `src/core/ingestion/registry-primary-flag.ts`) are tested in both legacy and registry-primary modes on every PR.
+
+For each migrated language, CI runs the resolver test file twice:
+1. `REGISTRY_PRIMARY_<LANG>=0` — legacy DAG path
+2. `REGISTRY_PRIMARY_<LANG>=1` — registry-primary path
+
+Both must pass. Known legacy gaps are listed in `LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES` in `test/integration/resolvers/helpers.ts` and are automatically skipped in legacy mode.
+
+Adding a language to `MIGRATED_LANGUAGES` automatically enrolls it in parity — no workflow or config edit needed. The test file must exist at `test/integration/resolvers/<slug>.test.ts`.
+
+Run parity locally: `cd gitnexus && npm run test:parity`
+
+Run for a single language: `cd gitnexus && npx tsx scripts/run-parity.ts --language python`
+
+## 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.
+
+## Regression testing
+
+Re-run the full relevant suite when:
+
+- Prompt or agent-behavior documentation changes (if tests encode behavior)
+- Model or embedding-related code paths change
+- Graph schema, query contracts, or MCP tool shapes change
+- Dependencies with parsing or runtime impact upgrade
+
+## 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.

api/proxy.ts

@@ -1,104 +0,0 @@
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-
-/**
- * CORS Proxy for isomorphic-git
- * 
- * isomorphic-git calls: /api/proxy?url=https://github.com/...
- */
-export default async function handler(req: VercelRequest, res: VercelResponse) {
-  // Handle CORS preflight
-  if (req.method === 'OPTIONS') {
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Git-Protocol, Accept');
-    res.status(200).end();
-    return;
-  }
-
-  // Get URL from query parameter
-  const { url } = req.query;
-  
-  if (!url || typeof url !== 'string') {
-    res.status(400).json({ error: 'Missing url query parameter' });
-    return;
-  }
-
-  // Only allow GitHub URLs for security
-  const allowedHosts = ['github.com', 'raw.githubusercontent.com'];
-  let parsedUrl: URL;
-  
-  try {
-    parsedUrl = new URL(url);
-  } catch {
-    res.status(400).json({ error: 'Invalid URL' });
-    return;
-  }
-  
-  if (!allowedHosts.some(host => parsedUrl.hostname.endsWith(host))) {
-    res.status(403).json({ error: 'Only GitHub URLs are allowed' });
-    return;
-  }
-
-  try {
-    const headers: Record<string, string> = {
-      'User-Agent': 'git/isomorphic-git',
-    };
-    
-    // Forward relevant headers
-    if (req.headers.authorization) {
-      headers['Authorization'] = req.headers.authorization as string;
-    }
-    if (req.headers['content-type']) {
-      headers['Content-Type'] = req.headers['content-type'] as string;
-    }
-    if (req.headers['git-protocol']) {
-      headers['Git-Protocol'] = req.headers['git-protocol'] as string;
-    }
-    if (req.headers.accept) {
-      headers['Accept'] = req.headers.accept as string;
-    }
-
-    // Get request body for POST requests
-    let body: Buffer | undefined;
-    if (req.method === 'POST') {
-      const chunks: Buffer[] = [];
-      for await (const chunk of req) {
-        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
-      }
-      body = Buffer.concat(chunks);
-    }
-
-    const response = await fetch(url, {
-      method: req.method || 'GET',
-      headers,
-      body: body ? new Uint8Array(body) : undefined,
-    });
-
-    // Set CORS headers
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Expose-Headers', '*');
-
-    // Forward response headers (except ones that cause issues)
-    const skipHeaders = [
-      'content-encoding', 
-      'transfer-encoding', 
-      'connection',
-      'www-authenticate', // IMPORTANT: Strip this to prevent browser's native auth popup!
-    ];
-    
-    response.headers.forEach((value, key) => {
-      if (!skipHeaders.includes(key.toLowerCase())) {
-        res.setHeader(key, value);
-      }
-    });
-
-    res.status(response.status);
-    const buffer = await response.arrayBuffer();
-    res.send(Buffer.from(buffer));
-    
-  } catch (error) {
-    console.error('Proxy error:', error);
-    res.status(500).json({ error: 'Proxy request failed', details: String(error) });
-  }
-}
-

compound-engineering.local.md

@@ -0,0 +1,57 @@
+---
+review_agents: [kieran-typescript-reviewer, pattern-recognition-specialist, architecture-strategist, data-integrity-guardian, security-sentinel, performance-oracle, code-simplicity-reviewer]
+plan_review_agents: [kieran-typescript-reviewer, architecture-strategist, code-simplicity-reviewer]
+voltagent_agents: [voltagent-lang:typescript-pro, voltagent-qa-sec:security-auditor, voltagent-data-ai:database-optimizer]
+---
+
+# Review Context
+
+## Project Overview
+GitNexus is a code intelligence tool that builds a knowledge graph from source code using tree-sitter AST parsing across 12 languages and KuzuDB for graph storage. Two packages: `gitnexus/` (CLI/MCP, TypeScript) and `gitnexus-web/` (browser).
+
+## Cross-Language Pattern Consistency (pattern-recognition-specialist)
+- 12 language-specific type extractors in `gitnexus/src/core/ingestion/type-extractors/` must follow identical patterns for: async unwrapping, constructor binding, namespace handling, nullable type stripping, for-loop element typing.
+- Past bugs: C#/Rust missing `await_expression` unwrapping that TypeScript handled correctly; PHP backslash namespace splitting inconsistent with other languages' `::` / `.` splitting.
+- When reviewing type extractor changes, verify the same pattern exists in ALL applicable language files — asymmetry is the #1 source of bugs.
+
+## Data Integrity (data-integrity-guardian)
+- KuzuDB graph operations: schema in `gitnexus/src/core/kuzu/schema.ts`, adapter in `kuzu-adapter.ts`.
+- The ingestion pipeline writes symbols and relationships to the graph — changes to node/relation schemas or the ingestion pipeline can corrupt the index.
+- Known issue: KuzuDB `close()` hangs on Linux due to C++ destructor — use `detachKuzu()` pattern.
+- `lbug-adapter.ts` fallback path needs quote/newline escaping for Cypher injection prevention.
+
+## Security (security-sentinel)
+- Cypher query construction in `lbug-adapter.ts` and `kuzu-adapter.ts` — watch for injection via unescaped user-provided symbol names.
+- CLI accepts `--repo` parameter and file paths — validate against path traversal.
+- MCP server exposes tools to external AI agents — all tool inputs are untrusted.
+
+## Performance (performance-oracle)
+- Tree-sitter buffer size is adaptive (512KB–32MB) via `getTreeSitterBufferSize()` in `constants.ts`.
+- The ingestion pipeline processes entire repositories — O(n) per file with potential O(n²) in cross-file resolution.
+- KuzuDB batch inserts vs individual inserts matter for large repos.
+
+## Architecture (architecture-strategist)
+- Ingestion pipeline phases: structure → parsing → imports → calls → heritage → processes → type resolution.
+- Shared modules: `export-detection.ts`, `constants.ts`, `utils.ts` — changes here have wide blast radius.
+- `gitnexus-web` package drifts behind CLI — flag if a change should be mirrored.
+
+## Voltagent Supplementary Agents
+
+Invoke these via the Agent tool alongside `/ce:review` for deeper specialist analysis. These cover gaps that compound-engineering agents don't:
+
+### voltagent-lang:typescript-pro
+**When:** Changes touch type-resolution logic, generics, conditional types, or complex type-level programming in `type-env.ts`, `type-extractors/*.ts`, or `types.ts`.
+**Why:** The type resolution system uses advanced TypeScript patterns (discriminated unions, mapped types, recursive generics) that benefit from deep TS type-system review beyond what kieran-typescript-reviewer covers.
+
+### voltagent-qa-sec:security-auditor
+**When:** Changes touch MCP tool handlers, Cypher query construction, CLI argument parsing, or any code that processes external input.
+**Why:** GitNexus is an MCP server — all tool inputs come from untrusted AI agents. Systematic OWASP-level audit catches injection vectors that spot-checking misses. Past finding: `lbug-adapter.ts` fallback path had unescaped newlines in Cypher queries.
+
+### voltagent-data-ai:database-optimizer
+**When:** Changes touch `kuzu-adapter.ts`, `schema.ts`, `lbug-adapter.ts`, or any Cypher query construction/execution.
+**Why:** No CE agent specializes in graph database optimization. KuzuDB batch insert patterns, index usage, and query planning directly affect analysis speed on large repos.
+
+## Review Tooling
+- Use `gitnexus_impact()` before approving changes to any symbol — check d=1 (WILL BREAK) callers.
+- Use `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` to map PR diffs to affected execution flows.
+- Use claude-mem to surface past architectural decisions relevant to the code under review.

deploy/kubernetes/cluster-image-policy.yaml

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

docker-compose.yaml

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

docker-server.mjs

@@ -0,0 +1,175 @@
+import { open } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, isAbsolute, normalize, relative, resolve, sep } 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',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+// Static asset server for the gitnexus-web Docker image.
+//
+// TOCTOU prevention: every filesystem interaction uses open() to get a
+// file handle; subsequent reads use handle.readFile()/createReadStream().
+//
+// 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.
+//
+// Path-injection containment: each open() is preceded by a
+// path.relative() barrier that CodeQL recognizes as a sanitizer.
+
+const spaFallback = resolve(root, 'index.html');
+
+const server = createServer(async (req, res) => {
+  const urlPath = req.url?.split('?')[0] || '/';
+
+  let decoded;
+  try {
+    decoded = decodeURIComponent(urlPath);
+  } catch {
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
+  }
+  if (decoded.includes('\0')) {
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
+  }
+
+  const cleanPath = normalize(decoded.replace(/^\/+/, ''));
+  const requestedPath = resolve(root, cleanPath);
+
+  const rel = relative(root, requestedPath);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
+  }
+
+  let handle;
+  try {
+    let servePath = requestedPath;
+
+    // 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);
+    } 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);
+    }
+  } catch (error) {
+    console.error(error);
+    res.writeHead(500);
+    res.end('Internal server error');
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+});
+
+server.listen(port, host, () => {
+  console.log(`gitnexus-web listening on http://${host}:${port}`);
+});

docker-server.test.mjs

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

eslint-rules/require-safe-parse.mjs

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

eslint.config.mjs

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

eval/.env.example

@@ -0,0 +1,23 @@
+# ─── GitNexus SWE-bench Eval — API Keys ───
+# Copy this file to .env and fill in the keys you have.
+# You only need keys for the models you plan to test.
+
+# OpenRouter (covers Claude, MiniMax, GLM, and 200+ other models)
+# Get yours at: https://openrouter.ai/keys
+OPENROUTER_API_KEY=
+
+# Anthropic (direct — optional if using OpenRouter)
+# Get yours at: https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# ZhipuAI / GLM (direct — optional if using OpenRouter)
+# Get yours at: https://open.bigmodel.cn/
+ZHIPUAI_API_KEY=
+
+# MiniMax (direct — optional if using OpenRouter)
+MINIMAX_API_KEY=
+
+# ─── Optional ───
+
+# Cost tracking: set to "ignore_errors" if litellm can't find pricing for a model
+# MSWEA_COST_TRACKING=ignore_errors

eval/.gitignore

@@ -0,0 +1,16 @@
+# Evaluation results (large, should not be committed)
+results/
+*.traj.json
+preds.json
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Environment
+.env
+.venv/

eval/README.md

@@ -0,0 +1,269 @@
+# GitNexus SWE-bench Evaluation Harness
+
+Evaluate whether GitNexus code intelligence improves AI agent performance on real software engineering tasks. Runs SWE-bench instances across multiple models and compares baseline (no graph) vs GitNexus-enhanced configurations.
+
+## What This Tests
+
+**Hypothesis**: Giving AI agents structural code intelligence (call graphs, execution flows, blast radius analysis) improves their ability to resolve real GitHub issues — measured by resolve rate, cost, and efficiency.
+
+**Evaluation modes:**
+
+| Mode | What the agent gets |
+|------|-------------------|
+| `baseline` | Standard bash tools (grep, find, cat, sed) — control group |
+| `native` | Baseline + explicit GitNexus tools via eval-server (~100ms) |
+| `native_augment` | Native tools + grep results automatically enriched with graph context (**recommended**) |
+
+> **Recommended**: Use `native_augment` mode. It mirrors the Claude Code model — the agent gets both explicit GitNexus tools (fast bash commands) AND automatic enrichment of grep results with callers, callees, and execution flows. The agent decides when to use explicit tools vs rely on enriched search output.
+
+**Models supported:**
+
+- Claude 3.5 Haiku, Claude Sonnet 4, Claude Opus 4
+- MiniMax M1 2.5
+- GLM 4.7, GLM 5
+- Any model supported by litellm (add a YAML config)
+
+## Prerequisites
+
+- Python 3.11+
+- Docker (for SWE-bench containers)
+- Node.js 18+ (for GitNexus)
+- API keys for your chosen models
+
+## Setup
+
+```bash
+cd eval
+
+# Install dependencies
+pip install -e .
+
+# Set up API keys — copy the template and fill in your keys
+cp .env.example .env
+# Then edit .env and paste your key(s)
+```
+
+All models are routed through **OpenRouter** by default, so a single `OPENROUTER_API_KEY` is all you need. To use provider APIs directly (Anthropic, ZhipuAI, etc.), edit the model YAML in `configs/models/` and set the corresponding key in `.env`.
+
+```bash
+# Pull SWE-bench Docker images (pulled on-demand, but you can pre-pull)
+docker pull swebench/sweb.eval.x86_64.django_1776_django-16527:latest
+```
+
+### Debug logging
+
+Set `GITNEXUS_EVAL_DEBUG=1` to include full Python tracebacks in run summaries and logs. By default, errors are sanitized to avoid leaking host paths or stack traces.
+
+## Quick Start
+
+### Debug a single instance
+
+```bash
+# Fastest way to verify everything works
+python run_eval.py debug -m claude-haiku -i django__django-16527 --subset lite
+```
+
+### Run a single configuration
+
+```bash
+# 5 instances, Claude Sonnet, native_augment mode (default)
+python run_eval.py single -m claude-sonnet --subset lite --slice 0:5
+
+# Baseline comparison (no GitNexus)
+python run_eval.py single -m claude-sonnet --mode baseline --subset lite --slice 0:5
+
+# Full Lite benchmark, 4 parallel workers
+python run_eval.py single -m claude-sonnet --subset lite -w 4
+```
+
+### Run the full matrix
+
+```bash
+# All models x all modes
+python run_eval.py matrix --subset lite -w 4
+
+# Key comparison: baseline vs native_augment
+python run_eval.py matrix -m claude-sonnet -m claude-haiku --modes baseline --modes native_augment --subset lite --slice 0:50
+```
+
+### Analyze results
+
+```bash
+# Summary table
+python -m analysis.analyze_results results/
+
+# Compare modes for a specific model
+python -m analysis.analyze_results compare-modes results/ -m claude-sonnet
+
+# GitNexus tool usage analysis
+python -m analysis.analyze_results gitnexus-usage results/
+
+# Export as CSV for further analysis
+python -m analysis.analyze_results summary results/ --format csv > results.csv
+
+# Run official SWE-bench test evaluation
+python -m analysis.analyze_results summary results/ --swebench-eval
+```
+
+### List available configurations
+
+```bash
+python run_eval.py list-configs
+```
+
+## Architecture
+
+```
+eval/
+  run_eval.py              # Main entry point (single, matrix, debug commands)
+  agents/
+    gitnexus_agent.py      # GitNexusAgent: extends DefaultAgent with augmentation + metrics
+  environments/
+    gitnexus_docker.py     # Docker env with GitNexus + eval-server + standalone tool scripts
+  bridge/
+    gitnexus_tools.sh      # Bash wrappers (legacy — now standalone scripts are installed directly)
+    mcp_bridge.py          # Legacy MCP bridge (kept for reference)
+  prompts/
+    system_baseline.jinja          # System: persona + format rules
+    instance_baseline.jinja        # Instance: task + workflow
+    system_native.jinja            # System: + GitNexus tool reference
+    instance_native.jinja          # Instance: + GitNexus debugging workflow
+    system_native_augment.jinja    # System: + GitNexus tools + grep enrichment docs
+    instance_native_augment.jinja  # Instance: + GitNexus workflow + risk assessment
+  configs/
+    models/                # Per-model YAML configs
+    modes/                 # Per-mode YAML configs (baseline, native, native_augment)
+  analysis/
+    analyze_results.py     # Post-run comparative analysis
+  results/                 # Output directory (gitignored)
+```
+
+## How It Works
+
+### Template structure
+
+mini-swe-agent requires two Jinja templates:
+- **system_template** → system message: persona, format rules, tool reference (static)
+- **instance_template** → first user message: task, workflow, rules, examples (contains `{{task}}`)
+
+Each mode has a `system_{mode}.jinja` + `instance_{mode}.jinja` pair. The agent loads both automatically based on the configured mode.
+
+### Per-instance flow
+
+1. Docker container starts with SWE-bench instance (repo at specific commit)
+2. **GitNexus setup**: Node.js + gitnexus installed, `gitnexus analyze` runs (or restores from cache)
+3. **Eval-server starts**: `gitnexus eval-server` daemon (persistent HTTP server, keeps LadybugDB warm)
+4. **Standalone tool scripts installed** in `/usr/local/bin/` — works with `subprocess.run` (no `.bashrc` needed)
+5. Agent runs with the configured model + system prompt + GitNexus tools
+6. Agent's patch is extracted as a git diff
+7. Metrics collected: cost, tokens, tool calls, GitNexus usage, augmentation stats
+
+### Tool architecture
+
+```
+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)
+```
+
+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.
+
+### Eval-server
+
+The eval-server is a lightweight HTTP daemon that:
+- Keeps LadybugDB warm in memory (no cold start per tool call)
+- Returns LLM-friendly text (not raw JSON — saves tokens)
+- 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.
+
+### Grep augmentation (native_augment mode)
+
+When the agent runs `grep` or `rg`, the observation is post-processed: the agent class calls `gitnexus-augment` on the search pattern and appends `[GitNexus]` annotations showing callers, callees, and execution flows for matched symbols. This mirrors the Claude Code / Cursor hook integration.
+
+## Adding Models
+
+Create a YAML file in `configs/models/`:
+
+```yaml
+# configs/models/my-model.yaml
+model:
+  model_name: "openrouter/provider/model-name"
+  cost_tracking: "ignore_errors"  # if not in litellm's cost DB
+  model_kwargs:
+    max_tokens: 8192
+    temperature: 0
+```
+
+The model name follows [litellm conventions](https://docs.litellm.ai/docs/providers).
+
+## Metrics Collected
+
+| Metric | Description |
+|--------|-------------|
+| Patch Rate | % of instances where agent produced a patch |
+| Resolve Rate | % of instances where patch passes tests (requires --swebench-eval) |
+| Total Cost | API cost across all instances |
+| Avg Cost/Instance | Cost efficiency |
+| API Calls | Number of LLM calls |
+| GN Tool Calls | How many GitNexus tools the agent used |
+| Augment Hits | How many grep/find results got enriched |
+| Augment Hit Rate | % of search commands that got useful enrichment |

eval/__init__.py

@@ -0,0 +1 @@
+# GitNexus SWE-bench Evaluation Harness

eval/agents/gitnexus_agent.py

@@ -0,0 +1,199 @@
+"""
+GitNexus-Enhanced Agent for SWE-bench Evaluation
+
+Extends mini-swe-agent's DefaultAgent with:
+1. Native augment mode: GitNexus tools via eval-server + grep enrichment (recommended)
+2. Native mode: GitNexus tools via eval-server only
+3. Baseline mode: Pure mini-swe-agent (no GitNexus — control group)
+
+The agent class itself is minimal — the heavy lifting is in:
+- Prompt selection (system + instance templates per mode)
+- Observation post-processing (grep result augmentation)
+- Metrics tracking (which tools the agent actually uses)
+
+Template structure (matches mini-swe-agent's expectations):
+  system_template  → system message: persona + format rules + tool reference
+  instance_template → first user message: task + workflow + rules + examples
+"""
+
+import logging
+import re
+import time
+from enum import Enum
+from pathlib import Path
+
+from constants import AUGMENT_TIMEOUT_SECONDS
+from minisweagent import Environment, Model
+from minisweagent.agents.default import AgentConfig, DefaultAgent
+from tool_registry import BINARIES_BY_KEY, TOOL_METRIC_KEYS
+
+logger = logging.getLogger("gitnexus_agent")
+
+PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
+
+
+class GitNexusMode(str, Enum):
+    """Evaluation modes for GitNexus integration."""
+    BASELINE = "baseline"               # No GitNexus — pure mini-swe-agent
+    NATIVE = "native"                   # GitNexus tools via eval-server
+    NATIVE_AUGMENT = "native_augment"   # Native tools + grep enrichment (recommended)
+
+
+class GitNexusAgentConfig(AgentConfig):
+    """Extended config for GitNexus evaluation agent."""
+    gitnexus_mode: GitNexusMode = GitNexusMode.BASELINE
+    augment_timeout: float = AUGMENT_TIMEOUT_SECONDS
+    augment_min_pattern_length: int = 3
+    track_gitnexus_usage: bool = True
+
+
+class GitNexusAgent(DefaultAgent):
+    """
+    Agent that optionally enriches its capabilities with GitNexus code intelligence.
+
+    In BASELINE mode, behaves identically to DefaultAgent.
+    In NATIVE mode, GitNexus tools are available as bash commands via eval-server.
+    In NATIVE_AUGMENT mode, GitNexus tools + automatic grep result enrichment.
+    """
+
+    def __init__(self, model: Model, env: Environment, *, config_class: type = GitNexusAgentConfig, **kwargs):
+        mode = kwargs.get("gitnexus_mode", GitNexusMode.BASELINE)
+        if isinstance(mode, str):
+            mode = GitNexusMode(mode)
+
+        # Load system template
+        system_file = PROMPTS_DIR / f"system_{mode.value}.jinja"
+        if system_file.exists() and "system_template" not in kwargs:
+            kwargs["system_template"] = system_file.read_text()
+
+        # Load instance template
+        instance_file = PROMPTS_DIR / f"instance_{mode.value}.jinja"
+        if instance_file.exists() and "instance_template" not in kwargs:
+            kwargs["instance_template"] = instance_file.read_text()
+
+        super().__init__(model, env, config_class=config_class, **kwargs)
+        self.gitnexus_mode = mode
+        self.gitnexus_metrics = GitNexusMetrics()
+
+    def execute_actions(self, message: dict) -> list[dict]:
+        """Execute actions with optional GitNexus augmentation and tracking."""
+        if self.config.track_gitnexus_usage:
+            self._track_tool_usage(message)
+
+        outputs = [self.env.execute(action) for action in message.get("extra", {}).get("actions", [])]
+
+        # Augment grep/find observations in NATIVE_AUGMENT mode
+        if self.gitnexus_mode == GitNexusMode.NATIVE_AUGMENT:
+            actions = message.get("extra", {}).get("actions", [])
+            for i, (action, output) in enumerate(zip(actions, outputs)):
+                augmented = self._maybe_augment(action, output)
+                if augmented:
+                    outputs[i] = augmented
+
+        return self.add_messages(
+            *self.model.format_observation_messages(message, outputs, self.get_template_vars())
+        )
+
+    def _maybe_augment(self, action: dict, output: dict) -> dict | None:
+        """
+        If the action is a search command (grep, find, rg, ag), augment the output
+        with GitNexus knowledge graph context.
+        """
+        command = action.get("command", "")
+        if not command:
+            return None
+
+        pattern = self._extract_search_pattern(command)
+        if not pattern or len(pattern) < self.config.augment_min_pattern_length:
+            return None
+
+        start = time.time()
+        try:
+            augment_result = self.env.execute({
+                "command": f'gitnexus-augment "{pattern}" 2>&1 || true',
+                "timeout": self.config.augment_timeout,
+            })
+            elapsed = time.time() - start
+            self.gitnexus_metrics.augmentation_calls += 1
+            self.gitnexus_metrics.augmentation_time += elapsed
+
+            augment_text = augment_result.get("output", "").strip()
+            if augment_text and "[GitNexus]" in augment_text:
+                original_output = output.get("output", "")
+                output = dict(output)
+                output["output"] = f"{original_output}\n\n{augment_text}"
+                self.gitnexus_metrics.augmentation_hits += 1
+                return output
+        except Exception as e:
+            logger.debug(f"Augmentation failed for pattern '{pattern}': {e}")
+            self.gitnexus_metrics.augmentation_errors += 1
+
+        return None
+
+    @staticmethod
+    def _extract_search_pattern(command: str) -> str | None:
+        """Extract the search pattern from a grep/find/rg command."""
+        patterns = [
+            r'(?:grep|rg|ag)\s+(?:-[a-zA-Z]*\s+)*["\']([^"\']+)["\']',
+            r'(?:grep|rg|ag)\s+(?:-[a-zA-Z]*\s+)*(\S+)',
+        ]
+
+        for pat in patterns:
+            match = re.search(pat, command)
+            if match:
+                result = match.group(1)
+                if result.startswith("/") or result.startswith("."):
+                    continue
+                if result.startswith("-"):
+                    continue
+                return result
+
+        return None
+
+    def _track_tool_usage(self, message: dict):
+        """Track which GitNexus tools the agent uses."""
+        for action in message.get("extra", {}).get("actions", []):
+            command = action.get("command", "")
+            for key, binary in BINARIES_BY_KEY.items():
+                if binary in command and key in self.gitnexus_metrics.tool_calls:
+                    self.gitnexus_metrics.tool_calls[key] += 1
+                    break
+
+    def serialize(self, *extra_dicts) -> dict:
+        """Serialize with GitNexus-specific metrics."""
+        gitnexus_data = {
+            "info": {
+                "gitnexus": {
+                    "mode": self.gitnexus_mode.value,
+                    "metrics": self.gitnexus_metrics.to_dict(),
+                },
+            },
+        }
+        return super().serialize(gitnexus_data, *extra_dicts)
+
+
+class GitNexusMetrics:
+    """Tracks GitNexus-specific metrics during evaluation."""
+
+    def __init__(self):
+        self.tool_calls: dict[str, int] = {key: 0 for key in TOOL_METRIC_KEYS}
+        self.augmentation_calls: int = 0
+        self.augmentation_hits: int = 0
+        self.augmentation_errors: int = 0
+        self.augmentation_time: float = 0.0
+        self.index_time: float = 0.0
+
+    @property
+    def total_tool_calls(self) -> int:
+        return sum(self.tool_calls.values())
+
+    def to_dict(self) -> dict:
+        return {
+            "tool_calls": dict(self.tool_calls),
+            "total_tool_calls": self.total_tool_calls,
+            "augmentation_calls": self.augmentation_calls,
+            "augmentation_hits": self.augmentation_hits,
+            "augmentation_errors": self.augmentation_errors,
+            "augmentation_time_seconds": round(self.augmentation_time, 2),
+            "index_time_seconds": round(self.index_time, 2),
+        }

eval/analysis/analyze_results.py

@@ -0,0 +1,455 @@
+#!/usr/bin/env python3
+"""
+Results Analyzer for GitNexus SWE-bench Evaluation
+
+Reads evaluation results and generates comparative analysis:
+- Resolve rate by model x mode
+- Cost comparison (total, per-instance)
+- Token/API call efficiency
+- GitNexus tool usage patterns
+- Augmentation hit rates
+
+Usage:
+    python -m analysis.analyze_results /path/to/results
+    python -m analysis.analyze_results /path/to/results --format markdown
+    python -m analysis.analyze_results /path/to/results --swebench-eval  # run actual test verification
+"""
+
+import json
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tool_registry import TOOL_METRIC_KEYS
+
+logger = logging.getLogger("analyze_results")
+console = Console()
+app = typer.Typer(rich_markup_mode="rich", add_completion=False)
+
+
+def load_run_results(results_dir: Path) -> dict[str, dict]:
+    """
+    Load all run results from the results directory.
+    
+    Returns: {run_id: {summary, preds, instances}}
+    """
+    runs = {}
+
+    for run_dir in sorted(results_dir.iterdir()):
+        if not run_dir.is_dir():
+            continue
+
+        run_id = run_dir.name
+        run_data: dict[str, Any] = {"run_id": run_id, "dir": run_dir}
+
+        # Load summary
+        summary_path = run_dir / "summary.json"
+        if summary_path.exists():
+            run_data["summary"] = json.loads(summary_path.read_text())
+
+        # Load predictions
+        preds_path = run_dir / "preds.json"
+        if preds_path.exists():
+            run_data["preds"] = json.loads(preds_path.read_text())
+
+        # Load individual trajectories for detailed metrics
+        run_data["trajectories"] = {}
+        for traj_dir in run_dir.iterdir():
+            if not traj_dir.is_dir():
+                continue
+            for traj_file in traj_dir.glob("*.traj.json"):
+                try:
+                    traj = json.loads(traj_file.read_text())
+                    instance_id = traj.get("instance_id", traj_dir.name)
+                    run_data["trajectories"][instance_id] = traj
+                except Exception:
+                    pass
+
+        if run_data.get("preds") or run_data.get("summary"):
+            runs[run_id] = run_data
+
+    return runs
+
+
+def parse_run_id(run_id: str) -> tuple[str, str]:
+    """Parse 'model_mode' into (model, mode) using known suffixes."""
+    # Match the longest known suffix first to avoid hyphen collisions in model names.
+    known_modes = [
+        "native_augment",
+        "native",
+        "baseline",
+        "mcp",
+        "augment",
+        "full",
+    ]
+    for mode in known_modes:
+        suffix = f"_{mode}"
+        if run_id.endswith(suffix):
+            return run_id[: -len(suffix)], mode
+    return run_id, "unknown"
+
+
+def compute_metrics(run_data: dict) -> dict:
+    """Compute evaluation metrics for a single run."""
+    preds = run_data.get("preds", {})
+    summary = run_data.get("summary", {})
+    trajectories = run_data.get("trajectories", {})
+
+    n_instances = len(preds)
+    n_with_patch = sum(1 for p in preds.values() if p.get("model_patch", "").strip())
+
+    # Cost and API call metrics from trajectories
+    costs = []
+    api_calls = []
+    gn_tool_calls = []
+    gn_augment_hits = []
+    gn_augment_calls = []
+
+    for instance_id, traj in trajectories.items():
+        info = traj.get("info", {})
+        model_stats = info.get("model_stats", {})
+        costs.append(model_stats.get("instance_cost", 0))
+        api_calls.append(model_stats.get("api_calls", 0))
+
+        gn = info.get("gitnexus", {}).get("metrics", {})
+        if gn:
+            gn_tool_calls.append(gn.get("total_tool_calls", 0))
+            gn_augment_hits.append(gn.get("augmentation_hits", 0))
+            gn_augment_calls.append(gn.get("augmentation_calls", 0))
+
+    # Also try summary-level metrics
+    if not costs and summary:
+        results = summary.get("results", [])
+        for r in results:
+            costs.append(r.get("cost", 0))
+            api_calls.append(r.get("n_calls", 0))
+            gn = r.get("gitnexus_metrics", {})
+            if gn:
+                gn_tool_calls.append(gn.get("total_tool_calls", 0))
+                gn_augment_hits.append(gn.get("augmentation_hits", 0))
+                gn_augment_calls.append(gn.get("augmentation_calls", 0))
+
+    total_cost = sum(costs)
+    total_calls = sum(api_calls)
+
+    return {
+        "n_instances": n_instances,
+        "n_with_patch": n_with_patch,
+        "patch_rate": n_with_patch / max(n_instances, 1),
+        "total_cost": total_cost,
+        "avg_cost": total_cost / max(n_instances, 1),
+        "total_api_calls": total_calls,
+        "avg_api_calls": total_calls / max(n_instances, 1),
+        "total_gn_tool_calls": sum(gn_tool_calls),
+        "avg_gn_tool_calls": sum(gn_tool_calls) / max(len(gn_tool_calls), 1) if gn_tool_calls else 0,
+        "total_augment_hits": sum(gn_augment_hits),
+        "total_augment_calls": sum(gn_augment_calls),
+        "augment_hit_rate": sum(gn_augment_hits) / max(sum(gn_augment_calls), 1) if gn_augment_calls else 0,
+    }
+
+
+def run_swebench_evaluation(results_dir: Path, run_id: str, subset: str = "lite") -> dict | None:
+    """
+    Run the official SWE-bench evaluation on predictions.
+    
+    Requires: pip install swebench
+    """
+    preds_path = results_dir / run_id / "preds.json"
+    if not preds_path.exists():
+        return None
+
+    dataset_mapping = {
+        "lite": "princeton-nlp/SWE-Bench_Lite",
+        "verified": "princeton-nlp/SWE-Bench_Verified",
+        "full": "princeton-nlp/SWE-Bench",
+    }
+
+    try:
+        eval_output = results_dir / run_id / "swebench_eval"
+        cmd = [
+            sys.executable, "-m", "swebench.harness.run_evaluation",
+            "--dataset_name", dataset_mapping.get(subset, subset),
+            "--predictions_path", str(preds_path),
+            "--max_workers", "4",
+            "--run_id", run_id,
+            "--output_dir", str(eval_output),
+        ]
+
+        logger.info(f"Running SWE-bench evaluation for {run_id}...")
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+
+        if result.returncode == 0:
+            # Parse evaluation results
+            report_path = eval_output / run_id / "results.json"
+            if report_path.exists():
+                return json.loads(report_path.read_text())
+
+        logger.error(f"SWE-bench eval failed: {result.stderr[:500]}")
+        return None
+
+    except Exception as e:
+        logger.error(f"SWE-bench eval error: {e}")
+        return None
+
+
+# ─── CLI Commands ───────────────────────────────────────────────────────────
+
+
+@app.command()
+def summary(
+    results_dir: str = typer.Argument(..., help="Path to results directory"),
+    format: str = typer.Option("table", "--format", help="Output format: table, markdown, json, csv"),
+    swebench_eval: bool = typer.Option(False, "--swebench-eval", help="Run official SWE-bench test evaluation"),
+    subset: str = typer.Option("lite", "--subset", help="SWE-bench subset (for --swebench-eval)"),
+):
+    """Generate comparative analysis of evaluation results."""
+    results_path = Path(results_dir)
+    if not results_path.exists():
+        console.print(f"[red]Results directory not found: {results_path}[/red]")
+        raise typer.Exit(1)
+
+    runs = load_run_results(results_path)
+    if not runs:
+        console.print("[yellow]No evaluation results found[/yellow]")
+        raise typer.Exit(0)
+
+    console.print(f"\n[bold]Found {len(runs)} evaluation runs[/bold]\n")
+
+    # Compute metrics per run
+    all_metrics = {}
+    for run_id, run_data in runs.items():
+        model, mode = parse_run_id(run_id)
+        metrics = compute_metrics(run_data)
+        metrics["model"] = model
+        metrics["mode"] = mode
+
+        # Optionally run SWE-bench evaluation
+        if swebench_eval:
+            eval_result = run_swebench_evaluation(results_path, run_id, subset)
+            if eval_result:
+                metrics["resolved"] = eval_result.get("resolved", 0)
+                metrics["resolve_rate"] = eval_result.get("resolved", 0) / max(metrics["n_instances"], 1)
+
+        all_metrics[run_id] = metrics
+
+    if format == "table":
+        _print_table(all_metrics)
+    elif format == "markdown":
+        _print_markdown(all_metrics)
+    elif format == "json":
+        console.print(json.dumps(all_metrics, indent=2))
+    elif format == "csv":
+        _print_csv(all_metrics)
+
+
+@app.command()
+def compare_modes(
+    results_dir: str = typer.Argument(..., help="Path to results directory"),
+    model: str = typer.Option(..., "-m", "--model", help="Model to compare across modes"),
+):
+    """Compare modes for a specific model (baseline vs mcp vs augment vs full)."""
+    results_path = Path(results_dir)
+    runs = load_run_results(results_path)
+
+    # Filter to the specified model
+    model_runs = {
+        run_id: data for run_id, data in runs.items()
+        if parse_run_id(run_id)[0] == model
+    }
+
+    if not model_runs:
+        console.print(f"[yellow]No results found for model: {model}[/yellow]")
+        raise typer.Exit(1)
+
+    console.print(f"\n[bold]Mode comparison for {model}[/bold]\n")
+
+    metrics = {}
+    for run_id, run_data in model_runs.items():
+        _, mode = parse_run_id(run_id)
+        metrics[mode] = compute_metrics(run_data)
+
+    mode_order = [
+        mode
+        for mode in ["baseline", "native", "native_augment", "mcp", "augment", "full"]
+        if mode in metrics
+    ] or sorted(metrics.keys())
+
+    # Print comparison table
+    table = Table(title=f"Mode Comparison: {model}")
+    table.add_column("Metric", style="bold")
+    for mode in mode_order:
+        table.add_column(mode, justify="right")
+
+    rows = [
+        ("Instances", "n_instances", "d"),
+        ("With Patch", "n_with_patch", "d"),
+        ("Patch Rate", "patch_rate", ".1%"),
+        ("Total Cost", "total_cost", "$.4f"),
+        ("Avg Cost", "avg_cost", "$.4f"),
+        ("Total API Calls", "total_api_calls", "d"),
+        ("Avg API Calls", "avg_api_calls", ".1f"),
+        ("GN Tool Calls", "total_gn_tool_calls", "d"),
+        ("Augment Hits", "total_augment_hits", "d"),
+        ("Augment Hit Rate", "augment_hit_rate", ".1%"),
+    ]
+
+    for label, key, fmt in rows:
+        values = []
+        for mode in mode_order:
+            if mode in metrics:
+                v = metrics[mode].get(key, 0)
+                if fmt == ".1%":
+                    values.append(f"{v:.1%}")
+                elif fmt == "$.4f":
+                    values.append(f"${v:.4f}")
+                elif fmt == ".1f":
+                    values.append(f"{v:.1f}")
+                else:
+                    values.append(str(v))
+        table.add_row(label, *values)
+
+    # Add delta rows (improvement over baseline)
+    if "baseline" in metrics:
+        baseline_cost = metrics["baseline"]["avg_cost"]
+        baseline_calls = metrics["baseline"]["avg_api_calls"]
+
+        table.add_section()
+        for mode in mode_order:
+            if mode == "baseline":
+                continue
+            mode_cost = metrics[mode]["avg_cost"]
+            mode_calls = metrics[mode]["avg_api_calls"]
+
+            cost_delta = ((mode_cost - baseline_cost) / max(baseline_cost, 0.001)) * 100
+            calls_delta = ((mode_calls - baseline_calls) / max(baseline_calls, 1)) * 100
+
+            cost_str = f"{cost_delta:+.1f}%"
+            calls_str = f"{calls_delta:+.1f}%"
+
+            # Color-code: negative is good (cheaper/fewer calls)
+            cost_color = "green" if cost_delta < 0 else "red"
+            calls_color = "green" if calls_delta < 0 else "red"
+
+            console.print(f"  {mode} vs baseline: cost [{cost_color}]{cost_str}[/{cost_color}], calls [{calls_color}]{calls_str}[/{calls_color}]")
+
+    console.print(table)
+
+
+@app.command()
+def gitnexus_usage(
+    results_dir: str = typer.Argument(..., help="Path to results directory"),
+):
+    """Analyze GitNexus tool usage patterns across all runs."""
+    results_path = Path(results_dir)
+    runs = load_run_results(results_path)
+
+    console.print("\n[bold]GitNexus Tool Usage Analysis[/bold]\n")
+
+    table = Table(title="Tool Usage by Run")
+    table.add_column("Run", style="bold")
+    for key in TOOL_METRIC_KEYS:
+        table.add_column(key, justify="right")
+    table.add_column("Total", justify="right")
+    table.add_column("Augment Hits", justify="right")
+
+    for run_id, run_data in sorted(runs.items()):
+        _, mode = parse_run_id(run_id)
+        if mode == "baseline":
+            continue
+
+        # Aggregate tool calls across trajectories
+        tool_totals: dict[str, int] = {key: 0 for key in TOOL_METRIC_KEYS}
+        augment_hits = 0
+
+        for traj in run_data.get("trajectories", {}).values():
+            gn = traj.get("info", {}).get("gitnexus", {}).get("metrics", {})
+            for tool, count in gn.get("tool_calls", {}).items():
+                tool_totals[tool] = tool_totals.get(tool, 0) + count
+            augment_hits += gn.get("augmentation_hits", 0)
+
+        # Also check summary
+        for r in run_data.get("summary", {}).get("results", []):
+            gn = r.get("gitnexus_metrics", {})
+            for tool, count in gn.get("tool_calls", {}).items():
+                tool_totals[tool] = tool_totals.get(tool, 0) + count
+            augment_hits += gn.get("augmentation_hits", 0)
+
+        total = sum(tool_totals.values())
+        if total > 0 or augment_hits > 0:
+            table.add_row(
+                run_id,
+                *[str(tool_totals.get(key, 0)) for key in TOOL_METRIC_KEYS],
+                str(total),
+                str(augment_hits),
+            )
+
+    console.print(table)
+
+
+# ─── Output Formatters ─────────────────────────────────────────────────────
+
+
+def _print_table(all_metrics: dict):
+    """Print rich table summary."""
+    table = Table(title="Evaluation Results")
+    table.add_column("Run", style="bold")
+    table.add_column("Model")
+    table.add_column("Mode")
+    table.add_column("N", justify="right")
+    table.add_column("Patched", justify="right")
+    table.add_column("Rate", justify="right")
+    table.add_column("Cost", justify="right")
+    table.add_column("Calls", justify="right")
+    table.add_column("GN Tools", justify="right")
+
+    for run_id, m in sorted(all_metrics.items()):
+        resolved_str = ""
+        if "resolve_rate" in m:
+            resolved_str = f" ({m['resolve_rate']:.0%})"
+
+        table.add_row(
+            run_id,
+            m["model"],
+            m["mode"],
+            str(m["n_instances"]),
+            str(m["n_with_patch"]),
+            f"{m['patch_rate']:.0%}{resolved_str}",
+            f"${m['total_cost']:.2f}",
+            str(m["total_api_calls"]),
+            str(m["total_gn_tool_calls"]) if m["total_gn_tool_calls"] > 0 else "-",
+        )
+
+    console.print(table)
+
+
+def _print_markdown(all_metrics: dict):
+    """Print markdown table."""
+    print("| Run | Model | Mode | N | Patched | Rate | Cost | Calls | GN Tools |")
+    print("|-----|-------|------|---|---------|------|------|-------|----------|")
+    for run_id, m in sorted(all_metrics.items()):
+        gn = str(m["total_gn_tool_calls"]) if m["total_gn_tool_calls"] > 0 else "-"
+        print(f"| {run_id} | {m['model']} | {m['mode']} | {m['n_instances']} | {m['n_with_patch']} | {m['patch_rate']:.0%} | ${m['total_cost']:.2f} | {m['total_api_calls']} | {gn} |")
+
+
+def _print_csv(all_metrics: dict):
+    """Print CSV output."""
+    print("run_id,model,mode,n_instances,n_with_patch,patch_rate,total_cost,avg_cost,total_api_calls,avg_api_calls,total_gn_tool_calls,total_augment_hits,augment_hit_rate")
+    for run_id, m in sorted(all_metrics.items()):
+        print(
+            f"{run_id},{m['model']},{m['mode']},{m['n_instances']},{m['n_with_patch']},"
+            f"{m['patch_rate']:.4f},{m['total_cost']:.4f},{m['avg_cost']:.4f},"
+            f"{m['total_api_calls']},{m['avg_api_calls']:.1f},{m['total_gn_tool_calls']},"
+            f"{m['total_augment_hits']},{m['augment_hit_rate']:.4f}"
+        )
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    app()

eval/bridge/gitnexus_tools.sh

@@ -0,0 +1,155 @@
+#!/bin/bash
+# GitNexus CLI tool wrappers for SWE-bench evaluation
+#
+# These functions call the GitNexus eval-server (HTTP daemon) for near-instant
+# tool responses. The eval-server keeps KuzuDB warm in memory.
+#
+# If the eval-server is not running, falls back to direct CLI commands.
+#
+# Usage:
+#   gitnexus-query "how does authentication work"
+#   gitnexus-context "validateUser"
+#   gitnexus-impact "AuthService" upstream
+#   gitnexus-cypher "MATCH (n:Function) RETURN n.name LIMIT 10"
+#   gitnexus-overview
+
+GITNEXUS_EVAL_PORT="${GITNEXUS_EVAL_PORT:-4848}"
+GITNEXUS_EVAL_URL="http://127.0.0.1:${GITNEXUS_EVAL_PORT}"
+
+_gitnexus_call() {
+    local tool="$1"
+    shift
+    local json_body="$1"
+
+    # Try eval-server first (fastest path — KuzuDB stays warm)
+    local result
+    result=$(curl -sf -X POST "${GITNEXUS_EVAL_URL}/tool/${tool}" \
+        -H "Content-Type: application/json" \
+        -d "${json_body}" 2>/dev/null)
+
+    if [ $? -eq 0 ] && [ -n "$result" ]; then
+        echo "$result"
+        return 0
+    fi
+
+    # Fallback: direct CLI (cold start, slower but always works)
+    case "$tool" in
+        query)
+            local q=$(echo "$json_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('query',''))" 2>/dev/null)
+            npx gitnexus query "$q" 2>&1
+            ;;
+        context)
+            local n=$(echo "$json_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('name',''))" 2>/dev/null)
+            npx gitnexus context "$n" 2>&1
+            ;;
+        impact)
+            local t=$(echo "$json_body" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('target',''))" 2>/dev/null)
+            local d=$(echo "$json_body" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('direction','upstream'))" 2>/dev/null)
+            npx gitnexus impact "$t" --direction "$d" 2>&1
+            ;;
+        cypher)
+            local cq=$(echo "$json_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('query',''))" 2>/dev/null)
+            npx gitnexus cypher "$cq" 2>&1
+            ;;
+        *)
+            echo "Unknown tool: $tool" >&2
+            return 1
+            ;;
+    esac
+}
+
+gitnexus-query() {
+    local query="$1"
+    local task_context="${2:-}"
+    local goal="${3:-}"
+
+    if [ -z "$query" ]; then
+        echo "Usage: gitnexus-query <query> [task_context] [goal]"
+        echo "Search the code knowledge graph for execution flows related to a concept."
+        echo ""
+        echo "Examples:"
+        echo '  gitnexus-query "authentication flow"'
+        echo '  gitnexus-query "database connection" "fixing connection pool leak"'
+        return 1
+    fi
+
+    local args="{\"query\": \"$query\""
+    [ -n "$task_context" ] && args="$args, \"task_context\": \"$task_context\""
+    [ -n "$goal" ] && args="$args, \"goal\": \"$goal\""
+    args="$args}"
+
+    _gitnexus_call query "$args"
+}
+
+gitnexus-context() {
+    local name="$1"
+    local file_path="${2:-}"
+
+    if [ -z "$name" ]; then
+        echo "Usage: gitnexus-context <symbol_name> [file_path]"
+        echo "Get a 360-degree view of a code symbol: callers, callees, processes, file location."
+        echo ""
+        echo "Examples:"
+        echo '  gitnexus-context "validateUser"'
+        echo '  gitnexus-context "AuthService" "src/auth/service.py"'
+        return 1
+    fi
+
+    local args="{\"name\": \"$name\""
+    [ -n "$file_path" ] && args="$args, \"file_path\": \"$file_path\""
+    args="$args}"
+
+    _gitnexus_call context "$args"
+}
+
+gitnexus-impact() {
+    local target="$1"
+    local direction="${2:-upstream}"
+
+    if [ -z "$target" ]; then
+        echo "Usage: gitnexus-impact <symbol_name> [upstream|downstream]"
+        echo "Analyze the blast radius of changing a code symbol."
+        echo ""
+        echo "  upstream  = what depends on this (what breaks if you change it)"
+        echo "  downstream = what this depends on (what it uses)"
+        echo ""
+        echo "Examples:"
+        echo '  gitnexus-impact "AuthService" upstream'
+        echo '  gitnexus-impact "validateUser" downstream'
+        return 1
+    fi
+
+    _gitnexus_call impact "{\"target\": \"$target\", \"direction\": \"$direction\"}"
+}
+
+gitnexus-cypher() {
+    local query="$1"
+
+    if [ -z "$query" ]; then
+        echo "Usage: gitnexus-cypher <cypher_query>"
+        echo "Execute a raw Cypher query against the code knowledge graph."
+        echo ""
+        echo "Schema: Nodes: File, Function, Class, Method, Interface, Community, Process"
+        echo "Edges via CodeRelation.type: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS"
+        echo ""
+        echo "Examples:"
+        echo "  gitnexus-cypher 'MATCH (a)-[:CodeRelation {type: \"CALLS\"}]->(b:Function {name: \"save\"}) RETURN a.name, a.filePath'"
+        echo "  gitnexus-cypher 'MATCH (n:Class) RETURN n.name, n.filePath LIMIT 20'"
+        return 1
+    fi
+
+    _gitnexus_call cypher "{\"query\": \"$query\"}"
+}
+
+gitnexus-overview() {
+    echo "=== Code Knowledge Graph Overview ==="
+    _gitnexus_call list_repos '{}'
+}
+
+# Export functions so they're available in subshells
+export -f _gitnexus_call 2>/dev/null
+export -f gitnexus-query 2>/dev/null
+export -f gitnexus-context 2>/dev/null
+export -f gitnexus-impact 2>/dev/null
+export -f gitnexus-cypher 2>/dev/null
+export -f gitnexus-overview 2>/dev/null