scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-10-27 06:12:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8
GitNexus/CLAUDE.md
Gergő Magyar 30676685e0
fix(rename): apply the exact reviewed edit plan (#3617) 
* fix(rename): bind apply to reviewed plans (U7)

Retain exact semantic edits behind single-use preview tokens and reject
source, target, inventory and graph drift before application. Preserve
explicit partial-write accounting and keep large unedited sources covered
with hashes instead of retained text.

Refs #2973

* fix(rename): cover unindexed sources (U7)

Address PR #3617 review by binding every supported source to streamed byte
hashes and canonical targets, including tracked and untracked files absent
from the graph. Keep the exact reviewed edits and bound evidence memory.

Use conventional even-sample medians and extend the existing CI benchmark
to capture and validate unindexed sources without relaxing timing gates.

Note: pre-existing packed Tree-sitter GLIBCXX_3.4.31 host failure in
parse-cache-identity-package.test.ts is not addressed by this PR.

* fix(rename): preserve lazy startup (U7)

Keep language providers off the MCP startup path; load their existing
classification only when rename inventory is requested. The existing
12 startup closure checks now pass.

Address PR #3617 review by including token validation in reviewed apply
timing and growing indexed evidence before preview, preserving the
20MiB controls under a 256MiB native pool. Migrate dispatch and retention
tests to the preview token contract, keeping write-failure oracles.

Note: pre-existing auto-sync /tmp fixture security and installed ARM64
grammar-header failures remain outside this PR; the packed Tree-sitter
GLIBCXX_3.4.31 host failure also reproduces on unchanged main.

* test(rename): always remove apply fixture (U7)

Own the temporary directory from creation in an outer finally so setup
and preview assertions cannot bypass cleanup. Keep spy restoration in
its inner finally and preserve all write-failure assertions.

Address PR #3617 cleanup feedback.

* fix(rename): retain targets and config evidence

* test(rename): verify approved physical output

* test(rename): cover native filesystem matrix

* test(rename): align preview contract fixtures

---------

Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com>
2026-10-17 19:38:01 +01:00

10 KiB
Raw Permalink Blame History

Last reviewed: 2026-10-17

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 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: 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 § Context budget).

Reference Documentation

  • This repository: AGENTS.md (Cursor + monorepo notes), ARCHITECTURE.md, CONTRIBUTING.md, GUARDRAILS.md.
  • Call & inheritance resolution: See ARCHITECTURE.md § Scope-Resolution Pipeline. Shared pipeline code in gitnexus/src/core/ingestion/ must not name languages — use LanguageProvider / ScopeResolver hooks instead (see AGENTS.md). (The legacy call-resolution DAG was removed in #942.)
  • GitNexus: standard skills in .claude/skills/gitnexus-*/; MCP and indexed-repo rules live only in AGENTS.md (gitnexus:start … gitnexus:end). See GitNexus rules below.
  • Engineering plans, execution & review: /gitnexus-plan <task> (implementation-ready plans via GitNexus + statement-level PDG + source verification; Deepen mode for existing plans), /gitnexus-work [plan] (executes a plan as impact-checked, detect_changes-gated atomic commits), /gitnexus-review [PR|branch|range|local] (read-only graph-backed review), /gitnexus-lfg <task> (plan with depth asked up front → proceed/stop gate → work → review pipeline). Specs in .claude/skills/gitnexus-{plan,work,review,lfg}/SKILL.md (see AGENTS.md § Engineering planning & execution).

Changelog

Date Version Change
2026-10-17 1.9.0 Require the reviewed preview's plan_token when applying semantic rename (#2973).
2026-07-20 1.8.0 The CI review agent runs gitnexus-review as a coordinated swarm — six ci-personas/ lanes dispatched via the Agent tool with a bounded critic gate.
2026-07-16 1.7.0 /gitnexus-plan asks depth up front in interactive runs; /gitnexus-lfg gate slimmed to proceed/stop.
2026-07-16 1.6.0 Renamed /gitnexus-pr-review to /gitnexus-review and added PR, branch/range, and local-change targets.
2026-07-11 1.5.0 Added /gitnexus-work and /gitnexus-lfg to the engineering plans & execution pointer.
2026-07-11 1.4.0 Added /gitnexus-plan pointer to Reference Documentation.
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 for the canonical MCP tools, impact analysis rules, and index instructions.

GitNexus — Code Intelligence

This project is indexed by GitNexus as GitNexus (248612 symbols, 565510 relationships, 918 execution flows).

Index stale? Run node .gitnexus/run.cjs analyze --index-only from the project root — it auto-selects an available runner. No .gitnexus/run.cjs yet? Bootstrap with npx, bunx, or pnpm dlx — e.g. bunx gitnexus@latest analyze (npm 11 npx crash; #1939). On query/context/impact/cypher object results, read staleness.status and branch/lastCommit. Re-analyze only for behind or diverged — current is clone HEAD, not main.

Always Do

  • MUST run impact analysis before editing. Use impact({target: "symbolName", direction: "upstream"}) (MCP) or node .gitnexus/run.cjs impact "symbolName" --direction upstream --repo . (CLI fallback); report callers, processes, and risk. Never substitute grep for graph analysis. For unified PDG impact, add mode: "pdg" with optional line: <N> — it returns statement-level affectedStatements over CDG + REACHING_DEF and inter-procedural symbols in interproceduralByDepth/byDepth; no-layer/degraded PDG results are UNKNOWN-risk notes (--pdg layer). CLI equivalent: node .gitnexus/run.cjs impact "symbolName" --direction upstream --mode pdg --line <N> --repo ..
  • MUST analyze changes before commit. Run detect_changes({scope: "all"}) or node .gitnexus/run.cjs detect-changes --scope all --repo .. partial: true or truncated: true is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review, fetch target branch "main" from its remote; compute its merge base with the reviewed HEAD and pass that SHA to detect_changes({scope: "compare", base_ref: "<merge-base SHA>"}) or node .gitnexus/run.cjs detect-changes --scope compare --base-ref "<merge-base SHA>" --repo ..
  • MUST warn on HIGH/CRITICAL risk pre-edit; never use riskSharedAxes to waive a HIGH/CRITICAL risk warning. Compare File/symbol: MCP File omits axes; Graph-RAG expands File.
  • MUST treat risk: UNKNOWN as unresolved, not as low. An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). impact pairs UNKNOWN with a riskNote saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
  • MUST use query({search_query: "concept"}) for concepts/flows, context({name: "symbolName"}) for a named symbol, or impact for blast radius, on read-only callers, dependencies, imports, or execution flow. Graph first; text search only for empty/UNKNOWN/literals.
  • For security review, explain({target: "fileOrSymbol"}) lists taint findings (source→sink flows; needs analyze --pdg).
  • For control/data dependence, pdg_query({mode: "controls", target: "fileOrSymbol"}) answers "under what condition does X run?" (CDG, incl. guard clauses) and pdg_query({mode: "flows", target, variable}) traces "where does variable Y flow?" (REACHING_DEF). --pdg layer.

Never Do

  • NEVER edit a function, class, or method before MCP/CLI impact analysis.
  • NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read UNKNOWN as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
  • NEVER rename symbols with find-and-replace — use rename with dry_run: true first, review the graph-backed semantic spans and coverage, then apply with dry_run: false and that preview's plan_token.
  • NEVER commit before MCP/CLI graph change analysis.

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-exploring/SKILL.md
Blast radius / "What breaks if I change X?" .claude/skills/gitnexus-impact-analysis/SKILL.md
Trace bugs / "Why is X failing?" .claude/skills/gitnexus-debugging/SKILL.md
Rename / extract / split / refactor .claude/skills/gitnexus-refactoring/SKILL.md
Tools, resources, schema reference .claude/skills/gitnexus-guide/SKILL.md
Index, status, clean, wiki CLI commands .claude/skills/gitnexus-cli/SKILL.md