gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

package/dist/cli/skill-gen.js

@@ -8,6 +8,10 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
+import { shouldMirrorSkillsToAgents } from './ai-context.js';
+const GENERATED_SKILL_PREFIX = 'gitnexus-area-';
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_COMMUNITY_NAME_LENGTH = MAX_SKILL_NAME_LENGTH - GENERATED_SKILL_PREFIX.length;
 // ============================================================================
 // MAIN EXPORT
 // ============================================================================
@@ -20,7 +24,47 @@ import path from 'path';
  */
 export const generateSkillFiles = async (repoPath, projectName, pipelineResult) => {
     const { communityResult, processResult, graph } = pipelineResult;
-    const outputDir = path.join(repoPath, '.claude', 'skills', 'generated');
+    const outputDir = path.join(repoPath, '.claude', 'skills');
+    const legacyOutputDir = path.join(outputDir, 'generated');
+    // Some agents prioritize repo-local .agents/skills over the global
+    // ~/.agents/skills install (see shouldMirrorSkillsToAgents). When .agents/
+    // exists, mirror the generated community skills there too so those agents
+    // serve the up-to-date copies.
+    const agentsOutputDir = path.join(repoPath, '.agents', 'skills');
+    let mirrorToAgents = await shouldMirrorSkillsToAgents(repoPath);
+    // Community skills used to live under an undiscoverable `generated/`
+    // grouping directory. Clear that GitNexus-owned legacy output and
+    // stale direct outputs in the reserved namespace, while preserving every
+    // unrelated project skill under .claude/skills/.
+    try {
+        const entries = await fs.readdir(outputDir, { withFileTypes: true });
+        await Promise.all(entries
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith(GENERATED_SKILL_PREFIX))
+            .map((entry) => fs.rm(path.join(outputDir, entry.name), { recursive: true, force: true })));
+    }
+    catch {
+        /* output root may not exist yet */
+    }
+    try {
+        await fs.rm(legacyOutputDir, { recursive: true, force: true });
+    }
+    catch {
+        /* legacy output may not exist */
+    }
+    // Mirror cleanup: clear only stale GitNexus-generated community skills under
+    // .agents/skills/ (reserved gitnexus-area-* namespace), preserving mirrored
+    // standard skills and any user-authored skills. Never clear the whole root.
+    if (mirrorToAgents) {
+        try {
+            const entries = await fs.readdir(agentsOutputDir, { withFileTypes: true });
+            await Promise.all(entries
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith(GENERATED_SKILL_PREFIX))
+                .map((entry) => fs.rm(path.join(agentsOutputDir, entry.name), { recursive: true, force: true })));
+        }
+        catch {
+            /* mirror root may not exist yet */
+        }
+    }
     if (!communityResult || !communityResult.memberships.length) {
         console.log('\n  Skills: no communities detected, skipping skill generation');
         return { skills: [], outputPath: outputDir };
@@ -47,14 +91,22 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
     // Step 3: Build lookup maps
     const membershipsByComm = buildMembershipMap(communityResult.memberships);
     const nodeIdToCommunityLabel = buildNodeCommunityLabelMap(communityResult.memberships, communities);
-    // Step 4: Clear and recreate output directory
-    try {
-        await fs.rm(outputDir, { recursive: true, force: true });
-    }
-    catch {
-        /* may not exist */
-    }
+    // Step 4: Ensure the shared project-skill root exists. Never clear it: it
+    // also contains user-authored and standard GitNexus skills.
     await fs.mkdir(outputDir, { recursive: true });
+    // The .agents/ mirror is a side flow: keep it a weak dependency. If the
+    // mirror root cannot be created (e.g. `.agents/skills` exists as a file),
+    // warn and disable mirroring for this run instead of aborting canonical
+    // community-skill generation. Canonical writes below stay unaffected.
+    if (mirrorToAgents) {
+        try {
+            await fs.mkdir(agentsOutputDir, { recursive: true });
+        }
+        catch (err) {
+            console.log(`Warning: Could not create mirror root ${agentsOutputDir} — .agents/skills mirroring disabled for this run: ${err}`);
+            mirrorToAgents = false;
+        }
+    }
     // Step 5: Generate skill files
     const skills = [];
     const usedNames = new Set();
@@ -74,14 +126,28 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
         // Generate kebab name
         const kebabName = toKebabName(community.label, usedNames);
         usedNames.add(kebabName);
+        const skillName = `${GENERATED_SKILL_PREFIX}${kebabName}`;
         // Generate SKILL.md content
-        const content = renderSkillMarkdown(community, projectName, members, files, entryPoints, flows, connections, kebabName);
+        const content = renderSkillMarkdown(community, projectName, members, files, entryPoints, flows, connections, skillName);
         // Write file
-        const skillDir = path.join(outputDir, kebabName);
+        const skillDir = path.join(outputDir, skillName);
         await fs.mkdir(skillDir, { recursive: true });
         await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+        // Mirror to .agents/skills/ for agents that read repo-local skills
+        // (see mirrorToAgents above). Best-effort: a per-skill mirror failure
+        // must not abort canonical community-skill generation.
+        if (mirrorToAgents) {
+            try {
+                const agentsSkillDir = path.join(agentsOutputDir, skillName);
+                await fs.mkdir(agentsSkillDir, { recursive: true });
+                await fs.writeFile(path.join(agentsSkillDir, 'SKILL.md'), content, 'utf-8');
+            }
+            catch (err) {
+                console.log(`Warning: Could not mirror skill ${skillName} to .agents/skills: ${err}`);
+            }
+        }
         const info = {
-            name: kebabName,
+            name: skillName,
             label: community.label,
             symbolCount: community.symbolCount,
             fileCount: files.length,
@@ -89,7 +155,10 @@ export const generateSkillFiles = async (repoPath, projectName, pipelineResult)
         skills.push(info);
         console.log(`    \u2713 ${community.label} (${community.symbolCount} symbols, ${files.length} files)`);
     }
-    console.log(`\n  ${skills.length} skills generated \u2192 .claude/skills/generated/`);
+    console.log(`\n  ${skills.length} skills generated \u2192 .claude/skills/${GENERATED_SKILL_PREFIX}*/`);
+    if (mirrorToAgents) {
+        console.log(`  ${skills.length} skills mirrored \u2192 .agents/skills/${GENERATED_SKILL_PREFIX}*/ (.agents)`);
+    }
     return { skills, outputPath: outputDir };
 };
 // ============================================================================
@@ -380,10 +449,10 @@ const gatherCrossConnections = (rawIds, ownLabel, membershipsByComm, nodeIdToCom
  * @param {MemberSymbol[]} entryPoints - Exported entry point symbols
  * @param {ProcessNode[]} flows - Execution flows touching this community
  * @param {CrossConnection[]} connections - Cross-community connections
- * @param {string} kebabName - Kebab-case name for the skill
+ * @param {string} skillName - Namespaced kebab-case name for the skill
  * @returns {string} Full SKILL.md content
  */
-const renderSkillMarkdown = (community, projectName, members, files, entryPoints, flows, connections, kebabName) => {
+const renderSkillMarkdown = (community, projectName, members, files, entryPoints, flows, connections, skillName) => {
     const cohesionPct = Math.round(community.cohesion * 100);
     // Dominant directory: most common top-level directory
     const dominantDir = getDominantDirectory(files);
@@ -396,7 +465,7 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
     const lines = [];
     // Frontmatter
     lines.push('---');
-    lines.push(`name: ${kebabName}`);
+    lines.push(`name: ${skillName}`);
     lines.push(`description: "Skill for the ${community.label} area of ${projectName}. ${community.symbolCount} symbols across ${files.length} files."`);
     lines.push('---');
     lines.push('');
@@ -496,20 +565,21 @@ const renderSkillMarkdown = (community, projectName, members, files, entryPoints
  * @brief Convert a community label to a kebab-case directory name
  * @param {string} label - The community label
  * @param {Set<string>} usedNames - Already-used names for collision detection
- * @returns {string} Unique kebab-case name capped at 50 characters
+ * @returns {string} Unique kebab-case name that leaves room for the GitNexus prefix
  */
 const toKebabName = (label, usedNames) => {
     let name = label
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '')
-        .slice(0, 50);
+        .slice(0, MAX_COMMUNITY_NAME_LENGTH);
     if (!name)
         name = 'skill';
     let candidate = name;
     let counter = 2;
     while (usedNames.has(candidate)) {
-        candidate = `${name}-${counter}`;
+        const suffix = `-${counter}`;
+        candidate = `${name.slice(0, MAX_COMMUNITY_NAME_LENGTH - suffix.length)}${suffix}`;
         counter++;
     }
     return candidate;

package/dist/cli/standard-skills.d.ts

@@ -0,0 +1,76 @@
+export type StandardSkillDistribution = 'project' | 'npm' | 'claudePlugin' | 'cursor';
+export interface StandardSkillCatalogEntry {
+    readonly name: `gitnexus-${string}`;
+    readonly agentTableTask: string;
+    readonly fallbackDescription: string;
+    readonly distributions: Readonly<Record<StandardSkillDistribution, boolean>>;
+}
+/**
+ * Canonical metadata for the standard skills installed by `gitnexus analyze`.
+ *
+ * Keep distribution intent here so generated agent guidance and drift guards
+ * cannot disagree about which copies should exist. The ordering intentionally
+ * matches the generated AGENTS.md / CLAUDE.md task table.
+ */
+export declare const STANDARD_SKILL_CATALOG: readonly [{
+    readonly name: "gitnexus-exploring";
+    readonly agentTableTask: "Understand architecture / \"How does X work?\"";
+    readonly fallbackDescription: "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\"";
+    readonly distributions: {
+        readonly project: true;
+        readonly npm: true;
+        readonly claudePlugin: true;
+        readonly cursor: true;
+    };
+}, {
+    readonly name: "gitnexus-impact-analysis";
+    readonly agentTableTask: "Blast radius / \"What breaks if I change X?\"";
+    readonly fallbackDescription: "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?\"";
+    readonly distributions: {
+        readonly project: true;
+        readonly npm: true;
+        readonly claudePlugin: true;
+        readonly cursor: true;
+    };
+}, {
+    readonly name: "gitnexus-debugging";
+    readonly agentTableTask: "Trace bugs / \"Why is X failing?\"";
+    readonly fallbackDescription: "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\"";
+    readonly distributions: {
+        readonly project: true;
+        readonly npm: true;
+        readonly claudePlugin: true;
+        readonly cursor: true;
+    };
+}, {
+    readonly name: "gitnexus-refactoring";
+    readonly agentTableTask: "Rename / extract / split / refactor";
+    readonly fallbackDescription: "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\"";
+    readonly distributions: {
+        readonly project: true;
+        readonly npm: true;
+        readonly claudePlugin: true;
+        readonly cursor: true;
+    };
+}, {
+    readonly name: "gitnexus-guide";
+    readonly agentTableTask: "Tools, resources, schema reference";
+    readonly fallbackDescription: "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?\"";
+    readonly distributions: {
+        readonly project: true;
+        readonly npm: true;
+        readonly claudePlugin: true;
+        readonly cursor: false;
+    };
+}, {
+    readonly name: "gitnexus-cli";
+    readonly agentTableTask: "Index, status, clean, wiki CLI commands";
+    readonly fallbackDescription: "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\"";
+    readonly distributions: {
+        readonly project: true;
+        readonly npm: true;
+        readonly claudePlugin: true;
+        readonly cursor: false;
+    };
+}];
+export type StandardSkillName = (typeof STANDARD_SKILL_CATALOG)[number]['name'];

package/dist/cli/standard-skills.js

@@ -0,0 +1,45 @@
+/**
+ * Canonical metadata for the standard skills installed by `gitnexus analyze`.
+ *
+ * Keep distribution intent here so generated agent guidance and drift guards
+ * cannot disagree about which copies should exist. The ordering intentionally
+ * matches the generated AGENTS.md / CLAUDE.md task table.
+ */
+export const STANDARD_SKILL_CATALOG = [
+    {
+        name: 'gitnexus-exploring',
+        agentTableTask: 'Understand architecture / "How does X work?"',
+        fallbackDescription: '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"',
+        distributions: { project: true, npm: true, claudePlugin: true, cursor: true },
+    },
+    {
+        name: 'gitnexus-impact-analysis',
+        agentTableTask: 'Blast radius / "What breaks if I change X?"',
+        fallbackDescription: '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?"',
+        distributions: { project: true, npm: true, claudePlugin: true, cursor: true },
+    },
+    {
+        name: 'gitnexus-debugging',
+        agentTableTask: 'Trace bugs / "Why is X failing?"',
+        fallbackDescription: '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"',
+        distributions: { project: true, npm: true, claudePlugin: true, cursor: true },
+    },
+    {
+        name: 'gitnexus-refactoring',
+        agentTableTask: 'Rename / extract / split / refactor',
+        fallbackDescription: '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"',
+        distributions: { project: true, npm: true, claudePlugin: true, cursor: true },
+    },
+    {
+        name: 'gitnexus-guide',
+        agentTableTask: 'Tools, resources, schema reference',
+        fallbackDescription: '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?"',
+        distributions: { project: true, npm: true, claudePlugin: true, cursor: false },
+    },
+    {
+        name: 'gitnexus-cli',
+        agentTableTask: 'Index, status, clean, wiki CLI commands',
+        fallbackDescription: '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"',
+        distributions: { project: true, npm: true, claudePlugin: true, cursor: false },
+    },
+];

package/dist/cli/status.d.ts

@@ -3,4 +3,7 @@
  *
  * Shows the indexing status of the current repository.
  */
-export declare const statusCommand: () => Promise<void>;
+export interface StatusOptions {
+    json?: boolean;
+}
+export declare const statusCommand: (options?: StatusOptions) => Promise<void>;

package/dist/cli/status.js

@@ -5,11 +5,17 @@
  */
 import path from 'path';
 import { findRepo, getStoragePaths, loadMeta, hasKuzuIndex } from '../storage/repo-manager.js';
-import { getCurrentCommit, getCurrentBranch, isGitRepo, getGitRoot } from '../storage/git.js';
+import { getCurrentCommit, getCurrentBranch, isGitRepo, getGitRoot, isWorkingTreeDirty, } from '../storage/git.js';
+import { analyzerRunnerIdentitiesEqual, resolveAnalyzerRunnerIdentity, } from '../core/analyzer-identity.js';
+import { getIndexIncompleteReasons } from '../core/index-freshness.js';
 import { t } from './i18n/index.js';
-export const statusCommand = async () => {
+export const statusCommand = async (options = {}) => {
     const cwd = process.cwd();
     if (!isGitRepo(cwd)) {
+        if (options.json) {
+            console.log(JSON.stringify({ schemaVersion: 1, error: 'not-git-repository' }));
+            return;
+        }
         console.log(t('status.notGitRepo'));
         return;
     }
@@ -18,7 +24,16 @@ export const statusCommand = async () => {
         // Check if there's a stale KuzuDB index that needs migration
         const repoRoot = getGitRoot(cwd) ?? cwd;
         const { storagePath } = getStoragePaths(repoRoot);
-        if (await hasKuzuIndex(storagePath)) {
+        const staleKuzu = await hasKuzuIndex(storagePath);
+        if (options.json) {
+            console.log(JSON.stringify({
+                schemaVersion: 1,
+                repository: repoRoot,
+                error: staleKuzu ? 'stale-kuzu-index' : 'not-indexed',
+            }));
+            return;
+        }
+        if (staleKuzu) {
             console.log(t('status.staleKuzu'));
             console.log(t('status.rebuildLadybug'));
         }
@@ -45,14 +60,52 @@ export const statusCommand = async () => {
         else
             workspaceLagsBranch = true;
     }
+    const currentRunnerIdentity = resolveAnalyzerRunnerIdentity(import.meta.url);
+    const runnerIdentityIsCurrent = analyzerRunnerIdentitiesEqual(activeMeta.runnerIdentity, currentRunnerIdentity);
+    const incompleteReasons = getIndexIncompleteReasons(activeMeta);
+    // A matching HEAD is not enough: `analyze` re-indexes a dirty working tree,
+    // so a repo with uncommitted source changes is stale even at the same commit.
+    // Skip the check for non-git folders (currentCommit === '') to match analyze.
+    const isUpToDate = currentCommit === activeMeta.lastCommit &&
+        runnerIdentityIsCurrent &&
+        incompleteReasons.length === 0 &&
+        (currentCommit === '' || !isWorkingTreeDirty(repo.repoPath));
+    if (options.json) {
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            repository: repo.repoPath,
+            branch: currentBranch,
+            workspaceIndexBranch: workspaceLagsBranch ? (repo.meta.branch ?? null) : null,
+            index: {
+                indexedAt: activeMeta.indexedAt,
+                commit: activeMeta.lastCommit,
+                runnerIdentity: activeMeta.runnerIdentity ?? null,
+                runnerIdentityStatus: runnerIdentityIsCurrent ? 'current' : 'stale-or-unknown',
+                incompleteReasons,
+            },
+            current: {
+                commit: currentCommit,
+                runnerIdentity: currentRunnerIdentity,
+            },
+            status: isUpToDate ? 'up-to-date' : 'stale',
+        }));
+        return;
+    }
     console.log(`${t('status.repository')}: ${repo.repoPath}`);
     console.log(`${t('status.branch')}: ${currentBranch ?? t('status.detached')}`);
     if (workspaceLagsBranch) {
         console.log(t('status.workspaceIndexLabel', { primary: repo.meta.branch ?? '' }));
     }
-    const isUpToDate = currentCommit === activeMeta.lastCommit;
     console.log(`${t('status.indexed')}: ${new Date(activeMeta.indexedAt).toLocaleString()}`);
     console.log(`${t('status.indexedCommit')}: ${activeMeta.lastCommit?.slice(0, 7)}`);
     console.log(`${t('status.currentCommit')}: ${currentCommit?.slice(0, 7)}`);
+    // Emit the complete, versioned receipt as JSON so humans can inspect it and
+    // automation can compare it without reverse-engineering a display string.
+    // `null` is the backward-compatible signal for pre-receipt metadata.
+    console.log(`${t('status.indexRunnerIdentity')}: ${JSON.stringify(activeMeta.runnerIdentity ?? null)}`);
+    if (incompleteReasons.length > 0) {
+        console.log(`Index incomplete reasons: ${JSON.stringify(incompleteReasons)}`);
+    }
+    console.log(`${t('status.currentRunnerIdentity')}: ${JSON.stringify(currentRunnerIdentity)}`);
     console.log(`${t('status.status')}: ${isUpToDate ? t('status.upToDate') : t('status.stale')}`);
 };

package/dist/cli/tool.d.ts

@@ -66,6 +66,7 @@ export declare function checkCommand(options?: {
 }): Promise<void>;
 export declare function traceCommand(from?: string, to?: string, options?: {
     fromUid?: string;
+    file?: string;
     fromFile?: string;
     toUid?: string;
     toFile?: string;

package/dist/cli/tool.js

@@ -39,9 +39,18 @@ async function getBackend() {
  * and write directly to the real stdout fd (#324).
  *
  * Falls back to stderr if the fd write fails (e.g., broken pipe).
+ *
+ * `render` is for the commands that print prose instead of JSON: they hand over
+ * the STRUCTURED result and a formatter, so the payload stays visible to the
+ * exit-code test below — pre-formatting it into a string would hide the very
+ * fields that test reads.
  */
-function output(data) {
-    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+function output(data, render) {
+    const text = render
+        ? render(data)
+        : typeof data === 'string'
+            ? data
+            : JSON.stringify(data, null, 2);
     try {
         writeSync(1, text + '\n');
     }
@@ -54,6 +63,35 @@ function output(data) {
         // Fallback: stderr (previous behavior, works on all platforms)
         process.stderr.write(text + '\n');
     }
+    // Every tool command routes its result through here, so this is the one place
+    // that keeps scripted callers honest — `gitnexus impact … && <edit>` and
+    // `gitnexus detect-changes && git commit` must not proceed on a result that
+    // did not complete. Two shapes say so, and both exit non-zero:
+    //
+    //   • `error` — a backend failure, returned as a payload rather than thrown
+    //     (#2469).
+    //   • `partial` — a step failed and was SWALLOWED (#2915), so the counts and
+    //     risk level are lower bounds a caller would otherwise read as clean. It
+    //     is cross-tool vocabulary, not detect_changes' private flag: `query`
+    //     raises it for degraded enrichment or a partial FTS failure, and `impact`
+    //     for an interrupted traversal or capped per-symbol enrichment — a short
+    //     caller set and an under-ranked risk, on the tool AGENTS.md makes a MUST
+    //     gate before every edit.
+    //
+    // One code for both, because `&&` cannot tell two apart and a "softer" code
+    // for `partial` would invite exempting it again.
+    //
+    // NOT here: `truncated`, where only the LISTING is capped while the counts and
+    // risk are computed over the full set — the verdict is sound, so failing on it
+    // would fire on every large-but-healthy diff. Nor `partialProbe`, a narrower
+    // per-candidate flag on ambiguous impact targets.
+    if (data && typeof data === 'object') {
+        const payload = data;
+        const failed = (typeof payload.error === 'string' && payload.error.trim().length > 0) ||
+            payload.partial === true;
+        if (failed)
+            process.exitCode = 1;
+    }
 }
 /**
  * Parse a `--limit` CLI option into a positive row cap, or `undefined` when the
@@ -264,7 +302,9 @@ export async function detectChangesCommand(options) {
         if (Array.isArray(result.affected_processes))
             result.affected_processes = result.affected_processes.slice(0, limit);
     }
-    output(formatDetectChangesResult(result));
+    // Hand over the structured result plus its formatter, not the formatted text:
+    // `output()` reads `error` / `partial` off the payload to set the exit code.
+    output(result, formatDetectChangesResult);
 }
 export async function checkCommand(options) {
     if (!options?.cycles) {
@@ -279,21 +319,42 @@ export async function checkCommand(options) {
             repo: options.repo,
             branch: options.branch,
         });
+        // A rendering guard, not an exit-code decision — `output()` owns that. An
+        // error payload carries no `cycles` array, so the prose branch below would
+        // throw on it; print the structured payload and stop.
         if (result?.error) {
             output(result);
-            process.exitCode = 1;
             return;
         }
         if (options.json) {
             output(result);
         }
-        else if (result.cycleCount === 0) {
+        else if (result.status === 'clean') {
             output('No circular imports found.');
         }
         else {
             output(result.cycles.map((cycle) => cycle.files.join(' -> ')).join('\n'));
+            // Past the enumeration cap the tool reports one representative cycle per
+            // component instead of every elementary cycle. Say so, or the short list
+            // reads as the whole truth on exactly the repositories where it is not.
+            if (result.enumeration === 'component-representatives') {
+                // Phrased to need no plural: `checkCommand` predates the `t()` i18n
+                // layer and none of its output goes through it, so inventing a plural
+                // here by hand would be the only one in the file.
+                output(`\n(showing one representative cycle per circular component — ` +
+                    `${result.componentCount} in total; the full enumeration exceeded the safety limit.)`);
+            }
         }
-        if (result.cycleCount > 0)
+        // Policy, not degradation: a clean run that FOUND cycles is `check` failing
+        // its own check, so `output()` — which fails closed on `error` and `partial`
+        // — deliberately knows nothing about it.
+        //
+        // Keyed on `status`, NOT on `cycleCount`. Past the enumeration cap the
+        // report carries `cycleCount: null` on purpose, because a partial count must
+        // not read as a real one — and `null > 0` is false, so counting here would
+        // exit 0 on precisely the repositories with the most cycles. `status`
+        // answers "were any found" in both enumeration modes.
+        if (result.status === 'cycles_found')
             process.exitCode = 1;
     }
     catch (error) {
@@ -306,6 +367,12 @@ export async function traceCommand(from, to, options) {
         cliErrorKey('tool.usage.trace');
         process.exit(1);
     }
+    if (options?.file !== undefined &&
+        options?.fromFile !== undefined &&
+        options.file !== options.fromFile) {
+        cliErrorKey('tool.usage.trace');
+        process.exit(1);
+    }
     if ((!from?.trim() && !options?.fromUid) || (!to?.trim() && !options?.toUid)) {
         cliErrorKey('tool.usage.trace');
         process.exit(1);
@@ -321,10 +388,11 @@ export async function traceCommand(from, to, options) {
     }
     try {
         const backend = await getBackend();
+        const fromFile = options?.fromFile ?? options?.file;
         const result = await backend.callTool('trace', {
             from: from || undefined,
             from_uid: options?.fromUid,
-            from_file: options?.fromFile,
+            from_file: fromFile,
             to: to || undefined,
             to_uid: options?.toUid,
             to_file: options?.toFile,

package/dist/cli/uninstall.js

@@ -34,6 +34,7 @@ import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { parseTree, modify, applyEdits, findNodeAtLocation, parse as parseJsonc, } from 'jsonc-parser';
 import { getEditorTargets, detectIndentation, isEnoent } from './editor-targets.js';
+import { LEGACY_SKILL_DIR_NAMES } from './setup.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const execFileAsync = promisify(execFile);
@@ -177,13 +178,17 @@ async function removeDir(dirPath, dryRun) {
 /**
  * The exact set of skill directory names setup installs, derived from the
  * bundled `skills/` source the same way installSkillsTo does (flat
- * `{name}.md` and `{name}/SKILL.md` layouts). Deriving the set — rather
+ * `{name}.md` and `{name}/SKILL.md` layouts), plus the legacy names that
+ * older setups installed before a shipped rename. Deriving the set — rather
  * than globbing `gitnexus-*` — ensures we never delete a user's own
  * similarly-named skill folder.
  */
 async function listGitnexusSkillNames() {
     const skillsRoot = process.env.GITNEXUS_TEST_SKILLS_ROOT ?? path.join(__dirname, '..', '..', 'skills');
-    const names = new Set();
+    // Seed with legacy names superseded by shipped renames: they dropped out of
+    // the bundled source, but a pre-rename install left them behind in every
+    // target. Setup only warns about them; uninstall removes by name by design.
+    const names = new Set(LEGACY_SKILL_DIR_NAMES);
     try {
         const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
         for (const entry of entries) {

package/dist/cli/wiki.d.ts

@@ -20,5 +20,6 @@ export interface WikiCommandOptions {
     timeout?: string;
     retries?: string;
     lang?: string;
+    allowInsecureConnection?: string;
 }
 export declare const wikiCommand: (inputPath?: string, options?: WikiCommandOptions) => Promise<void>;