gitnexus 1.6.11-rc.25 → 1.6.11-rc.27

package/README.md

@@ -240,7 +240,7 @@ gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus embeddings install      # Fetch the optional local embedding stack on demand (--cuda, --force)
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
-gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
+gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits (does not skip standard skills; use --skip-skills; community --skills files are unaffected)
 gitnexus analyze --skip-skills   # Skip installing standard .claude/skills/gitnexus-* skill files
 gitnexus analyze --skip-git      # Index folders that are not Git repositories
 gitnexus analyze --workers <n>   # Parse worker pool size (>=1; default: cores-1, capped at 16)

package/dist/cli/ai-context.js

@@ -9,6 +9,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { STANDARD_SKILL_CATALOG } from './standard-skills.js';
+import { isEnoent } from './editor-targets.js';
 import { logger } from '../core/logger.js';
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -145,8 +146,7 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 - **MUST analyze graph changes before committing.** Use \`detect_changes({scope: "all"})\` (MCP) or \`${runner} detect-changes --scope all --repo .\` (CLI fallback). \`partial: true\` or \`truncated: true\` is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: \`detect_changes({scope: "compare", base_ref: ${JSON.stringify(markdownSafeBranch(defaultBranch))}})\` or \`${runner} detect-changes --scope compare --base-ref ${JSON.stringify(markdownSafeBranch(defaultBranch))} --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.
-- Explore with \`query({search_query: "concept"})\` for process-grouped flows.
-- Use \`context({name: "symbolName"})\` for callers, callees, and flows.${hasSpringActuator
+- **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.${hasSpringActuator
         ? '\n- Spring Actuator runtime evidence is enabled. A Route is authoritative only when `runtimeConfirmed === true`; `runtimeSource` is provenance and may also describe conflicts. Snapshot values are never persisted.'
         : ''}
 - For security review, \`explain({target: "fileOrSymbol"})\` lists taint findings (source→sink flows; needs \`analyze --pdg\`).${hasPdg
@@ -322,6 +322,55 @@ export async function shouldMirrorSkillsToAgents(repoPath) {
         return false;
     }
 }
+const SKILL_PRESERVE_HINT = 'delete the file to refresh from the bundled template, or pass --skip-skills to skip skill install';
+async function readUtf8IfPresent(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return null;
+        throw err;
+    }
+}
+function skillBytesDiverge(existing, bundled) {
+    return existing !== null && existing !== bundled;
+}
+/** Write bundled skill bytes unless an existing file already differs. */
+async function writeSkillUnlessDivergent(filePath, content) {
+    const existing = await readUtf8IfPresent(filePath);
+    if (skillBytesDiverge(existing, content)) {
+        logger.warn(`Preserved customized skill ${filePath}; ${SKILL_PRESERVE_HINT}.`);
+        return true;
+    }
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+    return false;
+}
+async function inspectLegacySkillDir(legacyDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(legacyDir);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return null;
+        throw err;
+    }
+    const nestedExisting = entries.includes('SKILL.md')
+        ? await fs.readFile(path.join(legacyDir, 'SKILL.md'), 'utf-8')
+        : null;
+    return {
+        nestedExisting,
+        hasSiblings: entries.some((entry) => entry !== 'SKILL.md'),
+    };
+}
+function formatSkillInstallLine(prefix, total, preserved, allWrittenSuffix, partialSuffix) {
+    if (preserved > 0) {
+        return `${prefix} (${total - preserved} written, ${preserved} ${partialSuffix})`;
+    }
+    return `${prefix} (${total} ${allWrittenSuffix})`;
+}
 /**
  * Install GitNexus skills as direct children of .claude/skills/
  * Works natively with Claude Code, Cursor, and GitHub Copilot.
@@ -331,13 +380,14 @@ async function installSkills(repoPath) {
     const skillsDir = path.join(repoPath, '.claude', 'skills');
     const legacySkillsDir = path.join(skillsDir, 'gitnexus');
     const installedSkills = [];
+    let claudePreserved = 0;
+    let agentsPreserved = 0;
+    let legacyPreserved = 0;
     const agentsMirror = await shouldMirrorSkillsToAgents(repoPath);
     for (const skill of STANDARD_SKILL_CATALOG.filter((entry) => entry.distributions.project && entry.distributions.npm)) {
         const skillDir = path.join(skillsDir, skill.name);
         const skillPath = path.join(skillDir, 'SKILL.md');
         try {
-            // Create skill directory
-            await fs.mkdir(skillDir, { recursive: true });
             // Try to read from package skills directory
             const packageSkillPath = path.join(__dirname, '..', '..', 'skills', `${skill.name}.md`);
             let skillContent;
@@ -358,13 +408,14 @@ ${skill.fallbackDescription}
 Use GitNexus tools to accomplish this task.
 `;
             }
-            await fs.writeFile(skillPath, skillContent, 'utf-8');
+            if (await writeSkillUnlessDivergent(skillPath, skillContent))
+                claudePreserved += 1;
             // Mirror to .agents/skills/ for agents that read repo-local skills
             if (agentsMirror) {
                 try {
-                    const agentsSkillDir = path.join(repoPath, '.agents', 'skills', skill.name);
-                    await fs.mkdir(agentsSkillDir, { recursive: true });
-                    await fs.writeFile(path.join(agentsSkillDir, 'SKILL.md'), skillContent, 'utf-8');
+                    const agentsSkillPath = path.join(repoPath, '.agents', 'skills', skill.name, 'SKILL.md');
+                    if (await writeSkillUnlessDivergent(agentsSkillPath, skillContent))
+                        agentsPreserved += 1;
                 }
                 catch (err) {
                     logger.warn({ err }, `Warning: Could not mirror skill ${skill.name} to .agents/skills:`);
@@ -375,7 +426,20 @@ Use GitNexus tools to accomplish this task.
             // deep. Remove only the child owned by this installer; unknown siblings
             // under the legacy grouping directory may be user-authored and survive.
             try {
-                await fs.rm(path.join(legacySkillsDir, skill.name), { recursive: true, force: true });
+                const legacyDir = path.join(legacySkillsDir, skill.name);
+                const nestedSkill = path.join(legacyDir, 'SKILL.md');
+                const leftover = await inspectLegacySkillDir(legacyDir);
+                if (leftover !== null && skillBytesDiverge(leftover.nestedExisting, skillContent)) {
+                    logger.warn(`Preserved customized skill ${nestedSkill}; ${SKILL_PRESERVE_HINT}.`);
+                    legacyPreserved += 1;
+                }
+                else if (leftover?.hasSiblings) {
+                    logger.warn(`Preserved legacy skill directory ${legacyDir} because it contains operator-owned files.`);
+                    legacyPreserved += 1;
+                }
+                else if (leftover !== null) {
+                    await fs.rm(legacyDir, { recursive: true, force: true });
+                }
             }
             catch (err) {
                 logger.warn({ err }, `Warning: Could not remove legacy skill ${skill.name}:`);
@@ -386,7 +450,13 @@ Use GitNexus tools to accomplish this task.
             logger.warn({ err }, `Warning: Could not install skill ${skill.name}:`);
         }
     }
-    return { skills: installedSkills, agentsMirror };
+    return {
+        skills: installedSkills,
+        agentsMirror,
+        claudePreserved,
+        agentsPreserved,
+        legacyPreserved,
+    };
 }
 /**
  * Generate AI context files after indexing
@@ -435,11 +505,14 @@ export async function generateAIContextFiles(repoPath, storagePath, projectName,
     }
     // Install standard skills directly under .claude/skills/ (unless --skip-skills)
     if (!options?.skipSkills) {
-        const { skills: installedSkills, agentsMirror } = await installSkills(repoPath);
+        const { skills: installedSkills, agentsMirror, claudePreserved, agentsPreserved, legacyPreserved, } = await installSkills(repoPath);
         if (installedSkills.length > 0) {
-            createdFiles.push(`.claude/skills/gitnexus-*/ (${installedSkills.length} skills)`);
+            createdFiles.push(formatSkillInstallLine('.claude/skills/gitnexus-*/', installedSkills.length, claudePreserved, 'skills', 'preserved'));
             if (agentsMirror) {
-                createdFiles.push(`.agents/skills/gitnexus-*/ (${installedSkills.length} skills mirrored for .agents)`);
+                createdFiles.push(formatSkillInstallLine('.agents/skills/gitnexus-*/', installedSkills.length, agentsPreserved, 'skills mirrored for .agents', 'preserved for .agents'));
+            }
+            if (legacyPreserved > 0) {
+                createdFiles.push(`.claude/skills/gitnexus/<name>/ (legacy directories preserved: ${legacyPreserved})`);
             }
         }
     }

package/dist/cli/i18n/en.d.ts

@@ -162,7 +162,7 @@ export declare const en: {
     readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
     readonly 'help.option.analyze.dropEmbeddings': "Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves any embeddings already present in the index.";
     readonly 'help.option.analyze.skills': "Generate repo-specific skill files from detected communities (no-op when --index-only is also set).";
-    readonly 'help.option.analyze.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md";
+    readonly 'help.option.analyze.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.";
     readonly 'help.option.analyze.noStats': "Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md";
     readonly 'help.option.analyze.selfCommit': "Auto-commit AGENTS.md/CLAUDE.md changes after analyze (opt-in, off by default). Scoped to only those two files (never `git add -A`); no-ops if neither exists, neither changed, or the repo has no git identity configured.";
     readonly 'help.option.analyze.skipSkills': "Skip installing standard GitNexus skill files directly under .claude/skills/ and .agents/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.";

package/dist/cli/i18n/en.js

@@ -164,7 +164,7 @@ export const en = {
     'help.option.analyze.embeddings': 'Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.',
     'help.option.analyze.dropEmbeddings': 'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves any embeddings already present in the index.',
     'help.option.analyze.skills': 'Generate repo-specific skill files from detected communities (no-op when --index-only is also set).',
-    'help.option.analyze.skipAgentsMd': 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md',
+    'help.option.analyze.skipAgentsMd': 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.',
     'help.option.analyze.noStats': 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md',
     'help.option.analyze.selfCommit': 'Auto-commit AGENTS.md/CLAUDE.md changes after analyze (opt-in, off by default). Scoped to only those two files (never `git add -A`); no-ops if neither exists, neither changed, or the repo has no git identity configured.',
     'help.option.analyze.skipSkills': 'Skip installing standard GitNexus skill files directly under .claude/skills/ and .agents/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.',

package/dist/cli/i18n/resources.d.ts

@@ -163,7 +163,7 @@ export declare const cliResources: {
         readonly 'help.option.analyze.embeddings': "Enable embedding generation for semantic search (off by default). Optional [limit] overrides the 50,000-node safety cap; pass 0 to disable the cap entirely.";
         readonly 'help.option.analyze.dropEmbeddings': "Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves any embeddings already present in the index.";
         readonly 'help.option.analyze.skills': "Generate repo-specific skill files from detected communities (no-op when --index-only is also set).";
-        readonly 'help.option.analyze.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md";
+        readonly 'help.option.analyze.skipAgentsMd': "Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.";
         readonly 'help.option.analyze.noStats': "Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md";
         readonly 'help.option.analyze.selfCommit': "Auto-commit AGENTS.md/CLAUDE.md changes after analyze (opt-in, off by default). Scoped to only those two files (never `git add -A`); no-ops if neither exists, neither changed, or the repo has no git identity configured.";
         readonly 'help.option.analyze.skipSkills': "Skip installing standard GitNexus skill files directly under .claude/skills/ and .agents/skills/. Does not suppress community skills from --skills (those use .claude/skills/gitnexus-area-*). Use --index-only to skip all AI-context file injection.";

package/dist/cli/i18n/zh-CN.js

@@ -162,7 +162,7 @@ export const zhCN = {
     'help.option.analyze.embeddings': '启用语义搜索的嵌入生成（默认关闭）。可选 [limit] 覆盖 50,000 节点安全上限；传 0 可完全禁用上限。',
     'help.option.analyze.dropEmbeddings': '重建时删除现有嵌入。默认情况下，未传 `--embeddings` 的 `analyze` 会保留索引中已有嵌入。',
     'help.option.analyze.skills': '根据检测到的社区生成仓库专属 skill 文件（同时设置 --index-only 时无效）。',
-    'help.option.analyze.skipAgentsMd': '跳过更新 AGENTS.md 和 CLAUDE.md 中的 gitnexus 区块',
+    'help.option.analyze.skipAgentsMd': '跳过更新 AGENTS.md 和 CLAUDE.md 中的 gitnexus 区块。不会跳过 .claude/skills 或 .agents/skills 下的标准 skill；如需跳过那些请使用 --skip-skills。--skills 生成的社区 skill 不受影响。',
     'help.option.analyze.noStats': '从 AGENTS.md 和 CLAUDE.md 中省略易变的文件/符号计数',
     'help.option.analyze.selfCommit': '在 analyze 后自动提交 AGENTS.md/CLAUDE.md 的变更（默认关闭，需显式开启）。仅限这两个文件（绝不使用 `git add -A`）；若两者均不存在、均未变更，或仓库未配置 git 身份，则不执行任何操作。',
     'help.option.analyze.skipSkills': '跳过直接安装在 .claude/skills/ 和 .agents/skills/ 下的标准 GitNexus skill 文件。不抑制 --skills 生成的社区 skill（位于 .claude/skills/gitnexus-area-*）。使用 --index-only 可跳过所有 AI 上下文文件注入。',

package/dist/cli/index.js

@@ -46,7 +46,7 @@ program
     'preserves any embeddings already present in the index.')
     .option('--skills', 'Generate repo-specific skill files from detected communities ' +
     '(no-op when --index-only is also set).')
-    .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
+    .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md. Does not skip standard skills in .claude/skills or .agents/skills; use --skip-skills for those. Community skills from --skills are unaffected.')
     .option('--pdg', 'Build the control-flow-graph / PDG substrate (BasicBlock nodes + CFG edges) ' +
     'for supported languages. Opt-in; off by default. (#2081 M1)')
     .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +

package/dist/cli/setup.js

@@ -947,15 +947,29 @@ async function installSkillsTo(targetDir) {
     for (const [skillName, source] of skillSources) {
         const skillDir = path.join(targetDir, skillName);
         try {
-            if (source.isDirectory) {
-                const dirSource = path.join(skillsRoot, skillName);
-                await copyDirRecursive(dirSource, skillDir);
+            const sourceSkillPath = source.isDirectory
+                ? path.join(skillsRoot, skillName, 'SKILL.md')
+                : path.join(skillsRoot, `${skillName}.md`);
+            const destinationSkillPath = path.join(skillDir, 'SKILL.md');
+            const [sourceSkillContent, destinationSkillContent] = await Promise.all([
+                fs.readFile(sourceSkillPath, 'utf-8'),
+                fs.readFile(destinationSkillPath, 'utf-8').catch((err) => {
+                    if (!isEnoent(err))
+                        throw err;
+                    return null;
+                }),
+            ]);
+            const preserved = destinationSkillContent !== null && destinationSkillContent !== sourceSkillContent;
+            if (preserved && !source.isDirectory) {
+                console.log(`[gitnexus] preserved customized skill ${destinationSkillPath}; ` +
+                    'delete the file and rerun setup to refresh it.');
             }
-            else {
-                const flatSource = path.join(skillsRoot, `${skillName}.md`);
-                const content = await fs.readFile(flatSource, 'utf-8');
+            else if (source.isDirectory) {
+                await copyDirRecursive(path.join(skillsRoot, skillName), skillDir);
+            }
+            else if (!preserved) {
                 await fs.mkdir(skillDir, { recursive: true });
-                await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+                await fs.writeFile(destinationSkillPath, sourceSkillContent, 'utf-8');
             }
             // A directory superseded by a shipped rename is warned about, never
             // deleted: the installer cannot prove it owns the contents (users
@@ -968,7 +982,8 @@ async function installSkillsTo(targetDir) {
                         `left ${legacyDir} in place — delete it manually if you have not customized it.`);
                 }
             }
-            installed.push(skillName);
+            if (!preserved)
+                installed.push(skillName);
         }
         catch {
             // Source skill not found — skip
@@ -987,10 +1002,22 @@ async function copyDirRecursive(src, dest) {
         const destPath = path.join(dest, entry.name);
         if (entry.isDirectory()) {
             await copyDirRecursive(srcPath, destPath);
+            continue;
         }
-        else {
-            await fs.copyFile(srcPath, destPath);
+        const [srcBuf, destBuf] = await Promise.all([
+            fs.readFile(srcPath),
+            fs.readFile(destPath).catch((err) => {
+                if (!isEnoent(err))
+                    throw err;
+                return null;
+            }),
+        ]);
+        if (destBuf !== null && !destBuf.equals(srcBuf)) {
+            console.log(`[gitnexus] preserved customized skill ${destPath}; ` +
+                'delete the file and rerun setup to refresh it.');
+            continue;
         }
+        await fs.writeFile(destPath, srcBuf);
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.11-rc.25",
+  "version": "1.6.11-rc.27",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",