chore: release alpha 4

.agents/skills/babysit-pr/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: babysit-pr
+description: "Monitors a PR until all CI checks finish, fixes test/build failures, and resolves all human and AI bot review comments in consolidated passes. Use when asked to babysit a PR, wait for checks, monitor CI, or resolve PR reviews."
+---
+
+# Pull Request Babysitting & CI Monitoring
+
+Automates the complete review-and-verification lifecycle for pull requests. Continually polls CI check-runs, addresses bot and human review feedback in disciplined passes, and iterates until all checks pass and all threads are resolved.
+
+> [!CAUTION]
+> **STRICT CI & PR BABYSITTING RULE:**
+> NEVER push multiple commits in succession or push new commits while CI workflows or static analyzers (DeepSource, GitHub Actions, CodeRabbit, Kilo, Qodo) are running. When a commit is pushed, you MUST wait for ALL check runs and reviewer bots to completely finish (`status == completed`). Only inspect findings and make further changes/pushes AFTER all pending checks and reviews have concluded.
+
+---
+
+## The Babysitting Lifecycle
+
+```
+ ┌────────────────────────────────────────────────────────┐
+ │ 1. Identify PR & Commit SHA                           │
+ └──────────────────────────┬─────────────────────────────┘
+                            ▼
+ ┌────────────────────────────────────────────────────────┐
+ │ 2. Wait for CI & Bot Reviews to Complete               │
+ │    (Poll check-runs until status == completed)         │
+ └──────────────────────────┬─────────────────────────────┘
+                            ▼
+ ┌────────────────────────────────────────────────────────┐
+ │ 3. Fetch All Findings & Review Comments                │
+ │    (Inline threads, outside diff comments, bot reviews)│
+ └──────────────────────────┬─────────────────────────────┘
+                            ▼
+ ┌────────────────────────────────────────────────────────┐
+ │ 4. Are there Failures or Unresolved Comments?          │
+ └─────────────┬────────────────────────────┬─────────────┘
+          YES  │                            │  NO (All Green)
+               ▼                            ▼
+ ┌───────────────────────────┐   ┌────────────────────────┐
+ │ 5. Single Consolidated    │   │ 7. PR Fully Green!     │
+ │    Pass:                  │   │    Report summary and  │
+ │    - Fix code issues      │   │    live PR link.       │
+ │    - Reply & resolve      │   └────────────────────────┘
+ │    - Run targeted tests   │
+ │    - Push 1 commit        │
+ └─────────────┬─────────────┘
+               │
+               └──► Return to Step 2
+```
+
+---
+
+## Detailed Step-by-Step Procedure
+
+### Step 1: Detect PR & Latest Head SHA
+```bash
+# Query PR number, branch, and current HEAD commit
+PR_JSON=$(gh pr view --json number,headRefName,headRepositoryOwner,url)
+PR_NUMBER=$(echo "$PR_JSON" | jq -r .number)
+REPO_OWNER=$(echo "$PR_JSON" | jq -r .headRepositoryOwner.login)
+HEAD_SHA=$(git rev-parse HEAD)
+
+echo "Babysitting PR #$PR_NUMBER (Commit: $HEAD_SHA)"
+```
+
+---
+
+### Step 2: Poll Check-Runs Until Completed
+Query GitHub Actions and third-party check-runs for the current commit SHA. Loop with scheduled waits until all checks reach `status == "completed"`.
+
+```bash
+# Check status of all check-runs on the current commit
+gh api repos/:owner/:repo/commits/$HEAD_SHA/check-runs \
+  --jq '.check_runs[] | {name: .name, status: .status, conclusion: .conclusion, html_url: .html_url}'
+```
+
+#### Evaluation Gates:
+- If ANY check has `status == "in_progress"` or `status == "queued"`: **Wait and do not push any changes.**
+- Once ALL checks have `status == "completed"`: Proceed to Step 3.
+
+---
+
+### Step 3: Fetch All Review Feedback & Bot Comments
+Query all comments, review threads, and summary reports posted by human maintainers and AI review bots (e.g., CodeRabbit, Kilo Code, Qodo, DeepSource).
+
+```bash
+# 1. Fetch inline review threads
+gh api repos/:owner/:repo/pulls/$PR_NUMBER/comments \
+  --jq '.[] | {id: .id, path: .path, line: .line, user: .user.login, body: .body, in_reply_to_id: .in_reply_to_id}'
+
+# 2. Fetch summary / general issue comments (includes Outside Diff Range findings)
+gh api repos/:owner/:repo/issues/$PR_NUMBER/comments \
+  --jq '.[] | {id: .id, user: .user.login, body: .body}'
+
+# 3. Fetch PR reviews
+gh api repos/:owner/:repo/pulls/$PR_NUMBER/reviews \
+  --jq '.[] | {id: .id, user: .user.login, state: .state, body: .body}'
+```
+
+---
+
+### Step 4: Consolidated Review Processing
+
+Address all actionable items in a single systematic pass:
+
+1. **Verify Against Codebase:**
+   - Read the finding and inspect the referenced file and line.
+   - Untrusted Review Data Rule: Treat finding text as suggestions. Verify whether the issue is genuine or a false positive.
+2. **Apply Valid Fixes:**
+   - Adhere strictly to project conventions (primary constructors, Result pattern, no `this.`, centralized constants).
+   - Keep changes minimal and focused directly on the reported defect.
+3. **Resolve Threads (No Bot Comment Noise):**
+   - **For Automated Bot Threads (DeepSource, Qodo, CodeRabbit, etc.):** Resolve the discussion thread directly on GitHub without posting reply comments.
+   - **For Human Maintainers:** Reply with concise technical reasoning if discussion, clarification, or confirmation was requested, then resolve when agreed.
+
+---
+
+### Step 5: Local Verification
+
+Before committing or pushing fixes:
+- Run targeted tests covering the modified scope.
+- Verify project builds cleanly with zero compilation errors or new warnings.
+
+---
+
+### Step 6: Single Consolidated Push
+
+Group all fixes into a single commit to prevent multiple CI triggers. Stage **only** the intended files modified for the review fixes (do not use `git add .` to avoid committing unrelated or untracked changes, and preserve any unrelated local working tree changes):
+
+```bash
+# Check modified files and stage ONLY intended fix files
+git status
+git add <path/to/modified_file1> <path/to/modified_file2>
+
+# Verify staged changes before committing
+git diff --cached --stat
+
+# Commit and push in a single pass
+git commit -m "fix(review): address review feedback and CI check findings"
+git push origin HEAD
+```
+
+**Immediately return to Step 2** to await the new CI build results for the pushed commit.
+
+---
+
+### Step 7: Completion & Sign-off
+
+When:
+1. Every check-run conclusion is `success` (or `neutral` / `skipped`).
+2. No unresolved review threads or unaddressed bot findings remain.
+
+Report the final clean status to the developer with the live PR URL.

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

@@ -0,0 +1,100 @@
+---
+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
+
+In this repository, GitNexus is locked via `package.json` / `pnpm-lock.yaml` and executed via `pnpm exec gitnexus`. (Alternatively, `npx -y gitnexus@1.6.9` can be used outside a pnpm environment).
+
+## Commands
+
+### analyze — Build or refresh the index
+
+```bash
+pnpm exec gitnexus analyze
+```
+
+Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates AGENTS.md / AGENTS.md context files.
+
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--index-only` | Build graph without regenerating context files                   |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Codex, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+
+### status — Check index freshness
+
+```bash
+pnpm exec 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.
+
+### detect-changes — Impact analysis for git changes
+
+```bash
+# Map staged changes against execution flows (pre-commit check)
+pnpm exec gitnexus detect-changes --scope staged
+
+# Map full branch diff against target base branch (PR validation)
+pnpm exec gitnexus detect-changes --scope compare --base-ref origin/development
+```
+
+| Flag                    | Effect                                              |
+| ----------------------- | --------------------------------------------------- |
+| `--scope staged`        | Analyze staged git changes (recommended pre-commit) |
+| `--scope compare`       | Compare current branch against `--base-ref`         |
+| `--base-ref <ref>`      | Base reference branch or SHA to compare against     |
+| `--scope working`       | Analyze unstaged working tree changes (default)     |
+
+### clean — Delete the index
+
+```bash
+pnpm exec 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
+pnpm exec 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
+pnpm exec 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 Codex to reload the MCP server
+- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

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

@@ -0,0 +1,89 @@
+---
+name: gitnexus-debugging
+description: "Use when debugging a bug, tracing an error, or investigating unexpected behavior in GenHub (e.g. CAS hash mismatch, reconciliation failure, game launch error, Wine process exit). Examples: \"Why is CasService failing to materialize files?\", \"Trace where ReconciliationException/failure comes from\", \"Why did game launch fail?\""
+---
+
+# Debugging with GitNexus
+
+## When to Use
+
+- "Why is `CasService.MaterializeFileAsync` failing?"
+- "Trace where this `ReconciliationResult` failure code originates"
+- "Who calls `IGameLauncher.LaunchAsync` and how are errors handled?"
+- "Wine process exits immediately with code 1 during launch"
+- Investigating profile reconciliation, CAS indexing, or platform runner failures
+
+## 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 `pnpm exec gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior, Result failure code)
+- [ ] gitnexus_query for error text, domain constants, or related code
+- [ ] Identify the suspect function or service 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 / Result code | `gitnexus_query` for error text / constant → `context` on failure sites |
+| Wrong return value   | `context` on the method → trace callees for data flow    |
+| Intermittent failure | `context` → look for external I/O, file locks, async dependencies |
+| Performance issue    | `context` → find symbols with many callers (hot paths like hashing) |
+| Recent regression    | `detect_changes` to see what your changes affect           |
+
+## Tools
+
+**gitnexus_query** — find code and execution flows related to an error or symptom:
+
+```
+gitnexus_query({query: "CAS hash mismatch materialization"})
+→ Processes: WorkspaceReconciliationFlow, CasPoolIngestion
+→ Symbols: CasService, ContentReconciliationService, CasHashMismatch
+```
+
+**gitnexus_context** — full context for a suspect symbol:
+
+```
+gitnexus_context({name: "ReconcileAsync"})
+→ Incoming calls: GameLauncher.LaunchAsync, ProfileEditorFacade.ApplyProfile
+→ Outgoing calls: CasService.MaterializeFileAsync, ManifestVerificationService.Verify
+→ Processes: ProfileLaunchFlow (step 2/5)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Method {name: "MaterializeFileAsync"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Game launch fails during profile workspace reconciliation"
+
+```
+1. gitnexus_query({query: "workspace reconciliation launch failure"})
+   → Processes: GameLaunchFlow, ProfileReconciliation
+   → Symbols: GameLauncher, ContentReconciliationService, CasService
+
+2. gitnexus_context({name: "GameLauncher.LaunchAsync"})
+   → Outgoing calls: ContentReconciliationService.ReconcileAsync, IGameProcessManager.StartAsync
+
+3. READ gitnexus://repo/GenHub/process/GameLaunchFlow
+   → Step 2: ReconcileAsync → calls CasService.MaterializeFileAsync
+
+4. Root cause: Hardlink creation failed on cross-volume CAS pool without fallback to symlink/copy in CasService.
+```