@veewo/gitnexus 1.4.9 → 1.4.11-rc

package/dist/mcp/local/unity-runtime-hydration.js

@@ -0,0 +1,323 @@
+import { buildUnityScanContext, buildUnityScanContextFromSeed } from '../../core/unity/scan-context.js';
+import { resolveUnityBindings } from '../../core/unity/resolver.js';
+import { formatLazyHydrationBudgetDiagnostic, } from './unity-enrichment.js';
+import { resolveUnityLazyConfig } from './unity-lazy-config.js';
+import { hydrateLazyBindings } from './unity-lazy-hydrator.js';
+import { readUnityOverlayBindings, upsertUnityOverlayBindings } from './unity-lazy-overlay.js';
+import { readUnityParityCache, upsertUnityParityCache } from './unity-parity-cache.js';
+import { createParityWarmupQueue } from './unity-parity-warmup-queue.js';
+import { loadUnityParitySeed } from './unity-parity-seed-loader.js';
+const inFlightParityHydration = new Map();
+const parityWarmupQueue = createParityWarmupQueue({
+    maxParallel: resolveParityWarmupMaxParallel(process.env),
+});
+function resolveParityWarmupMaxParallel(env) {
+    const raw = String(env.GITNEXUS_UNITY_PARITY_WARMUP_MAX_PARALLEL || '').trim();
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
+    }
+    return 2;
+}
+function normalizePath(filePath) {
+    return String(filePath || '').replace(/\\/g, '/');
+}
+function bindingIdentity(binding) {
+    return [
+        normalizePath(binding.resourcePath),
+        binding.bindingKind,
+        binding.componentObjectId,
+    ].join('|');
+}
+export function mergeUnityBindings(baseBindings, resolvedByPath) {
+    const merged = [];
+    const expandedPaths = new Set();
+    for (const binding of baseBindings) {
+        const resourcePath = normalizePath(binding.resourcePath);
+        if (!binding.lightweight) {
+            merged.push(binding);
+            continue;
+        }
+        const expanded = resolvedByPath.get(resourcePath);
+        if (expanded && expanded.length > 0) {
+            if (!expandedPaths.has(resourcePath)) {
+                merged.push(...expanded.map((row) => ({ ...row, lightweight: false })));
+                expandedPaths.add(resourcePath);
+            }
+            continue;
+        }
+        merged.push(binding);
+    }
+    return merged;
+}
+export function mergeParityUnityBindings(baseNonLightweightBindings, resolvedBindings) {
+    const merged = [];
+    const seen = new Set();
+    for (const row of [...baseNonLightweightBindings, ...resolvedBindings]) {
+        const key = bindingIdentity(row);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push({ ...row, lightweight: false });
+    }
+    return merged;
+}
+export function attachUnityHydrationMeta(payload, input) {
+    const { hasExpandableBindings, ...metaInput } = input;
+    const reasons = [];
+    if (metaInput.effectiveMode === 'compact' && hasExpandableBindings) {
+        reasons.push('mode_compact');
+    }
+    if (metaInput.fallbackToCompact) {
+        reasons.push('fallback_to_compact');
+    }
+    if (hasExpandableBindings) {
+        reasons.push('lightweight_bindings_remaining');
+    }
+    if ((payload.unityDiagnostics || []).some((diag) => /budget exceeded/i.test(String(diag || '')))) {
+        reasons.push('budget_exceeded');
+    }
+    const isComplete = reasons.length === 0;
+    const needsParityRetry = !isComplete && metaInput.effectiveMode === 'compact';
+    return {
+        ...payload,
+        hydrationMeta: {
+            ...metaInput,
+            resourceBindingCount: payload.resourceBindings.length,
+            unityDiagnosticsCount: payload.unityDiagnostics.length,
+            isComplete,
+            completenessReason: reasons,
+            needsParityRetry,
+            ...(needsParityRetry ? { retryHint: 'rerun_with_unity_hydration=parity' } : {}),
+        },
+    };
+}
+export async function hydrateUnityForSymbol(input) {
+    const runtime = resolveRuntime(input.runtime);
+    const startedAt = runtime.now();
+    if (input.mode === 'compact') {
+        const compactPayload = await runCompactHydration(input, runtime);
+        const withMeta = attachUnityHydrationMeta(compactPayload, {
+            requestedMode: 'compact',
+            effectiveMode: 'compact',
+            elapsedMs: runtime.now() - startedAt,
+            fallbackToCompact: false,
+            hasExpandableBindings: hasExpandableBindings(compactPayload),
+        });
+        if (withMeta.hydrationMeta?.needsParityRetry) {
+            scheduleParityWarmup(input, runtime);
+        }
+        return withMeta;
+    }
+    const parityResult = await runParityHydrationWithFallback(input, runtime);
+    return attachUnityHydrationMeta(parityResult.payload, {
+        requestedMode: 'parity',
+        effectiveMode: parityResult.effectiveMode,
+        elapsedMs: runtime.now() - startedAt,
+        fallbackToCompact: parityResult.fallbackToCompact,
+        hasExpandableBindings: hasExpandableBindings(parityResult.payload),
+    });
+}
+function resolveRuntime(overrides) {
+    return {
+        now: () => Date.now(),
+        queue: parityWarmupQueue,
+        resolveLazyConfig: resolveUnityLazyConfig,
+        hydrateLazyBindings,
+        readOverlayBindings: readUnityOverlayBindings,
+        upsertOverlayBindings: upsertUnityOverlayBindings,
+        readParityCache: readUnityParityCache,
+        upsertParityCache: upsertUnityParityCache,
+        loadParitySeed: loadUnityParitySeed,
+        buildScanContext: buildUnityScanContext,
+        buildScanContextFromSeed: buildUnityScanContextFromSeed,
+        resolveBindings: resolveUnityBindings,
+        shouldEnableWarmup,
+        ...overrides,
+    };
+}
+function hasExpandableBindings(payload) {
+    return payload.resourceBindings.some((binding) => binding.lightweight || binding.componentObjectId === 'summary');
+}
+function buildParityWarmupKey(input) {
+    return `${input.deps.storagePath}::${input.deps.indexedCommit}::${input.symbol.uid}`;
+}
+function scheduleParityWarmup(input, runtime) {
+    if (!runtime.shouldEnableWarmup(process.env)) {
+        return;
+    }
+    if (!input.symbol.uid || !input.symbol.name || !input.symbol.filePath) {
+        return;
+    }
+    void runtime.queue.run(() => getOrRunParityHydration(input, runtime))
+        .then(() => undefined)
+        .catch(() => undefined);
+}
+function shouldEnableWarmup(env) {
+    const raw = String(env.GITNEXUS_UNITY_PARITY_WARMUP || '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'on';
+}
+async function getOrRunParityHydration(input, runtime) {
+    const key = buildParityWarmupKey(input);
+    const existing = inFlightParityHydration.get(key);
+    if (existing) {
+        return existing;
+    }
+    const pending = (async () => {
+        const cached = await runtime.readParityCache(input.deps.storagePath, input.deps.indexedCommit, input.symbol.uid);
+        if (cached) {
+            return cached;
+        }
+        const payload = await computeParityPayload(input, runtime);
+        await runtime.upsertParityCache(input.deps.storagePath, input.deps.indexedCommit, input.symbol.uid, payload);
+        return payload;
+    })().finally(() => {
+        inFlightParityHydration.delete(key);
+    });
+    inFlightParityHydration.set(key, pending);
+    return pending;
+}
+async function computeParityPayload(input, runtime) {
+    const symbolDeclarations = [{ symbol: input.symbol.name, scriptPath: input.symbol.filePath }];
+    const paritySeed = await runtime.loadParitySeed(input.deps.storagePath, {
+        indexedCommit: input.deps.indexedCommit,
+    });
+    const seededScanContext = paritySeed
+        ? runtime.buildScanContextFromSeed({ seed: paritySeed, symbolDeclarations })
+        : null;
+    let resolved = await runtime.resolveBindings({
+        repoRoot: input.deps.repoPath,
+        symbol: input.symbol.name,
+        scanContext: seededScanContext || await runtime.buildScanContext({
+            repoRoot: input.deps.repoPath,
+            symbolDeclarations,
+        }),
+        deepParseLargeResources: true,
+    });
+    if (seededScanContext && resolved.resourceBindings.length === 0 && input.basePayload.resourceBindings.length > 0) {
+        const fallbackScanContext = await runtime.buildScanContext({
+            repoRoot: input.deps.repoPath,
+            symbolDeclarations,
+        });
+        resolved = await runtime.resolveBindings({
+            repoRoot: input.deps.repoPath,
+            symbol: input.symbol.name,
+            scanContext: fallbackScanContext,
+            deepParseLargeResources: true,
+        });
+    }
+    if (resolved.resourceBindings.length === 0 && input.basePayload.resourceBindings.length > 0) {
+        throw new Error('parity-expand returned zero bindings');
+    }
+    const baseNonLightweight = input.basePayload.resourceBindings.filter((binding) => !binding.lightweight && binding.componentObjectId !== 'summary');
+    const mergedBindings = mergeParityUnityBindings(baseNonLightweight, resolved.resourceBindings);
+    return toUnityContextPayload(mergedBindings, [
+        ...input.basePayload.unityDiagnostics,
+        ...resolved.unityDiagnostics,
+    ]);
+}
+async function runParityHydrationWithFallback(input, runtime) {
+    try {
+        return {
+            payload: await getOrRunParityHydration(input, runtime),
+            effectiveMode: 'parity',
+            fallbackToCompact: false,
+        };
+    }
+    catch (error) {
+        const compactFallback = await runCompactHydration(input, runtime);
+        const message = String(error instanceof Error ? error.message : error);
+        return {
+            payload: {
+                ...compactFallback,
+                unityDiagnostics: [
+                    ...compactFallback.unityDiagnostics,
+                    /parity-expand returned zero bindings/i.test(message)
+                        ? 'parity-expand returned zero bindings; fell back to compact hydration'
+                        : `parity-expand failed: ${message}`,
+                ],
+            },
+            effectiveMode: 'compact',
+            fallbackToCompact: true,
+        };
+    }
+}
+async function runCompactHydration(input, runtime) {
+    const lightweightPaths = [...new Set(input.basePayload.resourceBindings
+            .filter((binding) => binding.lightweight || binding.componentObjectId === 'summary')
+            .map((binding) => normalizePath(binding.resourcePath))
+            .filter((value) => value.length > 0))];
+    if (lightweightPaths.length === 0) {
+        return input.basePayload;
+    }
+    const overlayHits = await runtime.readOverlayBindings(input.deps.storagePath, input.deps.indexedCommit, input.symbol.uid, lightweightPaths);
+    const pendingPaths = lightweightPaths.filter((resourcePath) => !overlayHits.has(resourcePath));
+    const resolvedByPath = new Map(overlayHits);
+    const unityDiagnostics = [...input.basePayload.unityDiagnostics];
+    if (pendingPaths.length > 0) {
+        try {
+            const cfg = runtime.resolveLazyConfig(process.env);
+            const hydration = await runtime.hydrateLazyBindings({
+                pendingPaths,
+                config: cfg,
+                dedupeKey: `${input.symbol.uid}::${pendingPaths.slice().sort().join('|')}`,
+                resolveBatch: async (resourcePaths) => {
+                    const scopedPaths = [
+                        input.symbol.filePath,
+                        `${input.symbol.filePath}.meta`,
+                        ...resourcePaths,
+                        ...resourcePaths.map((resourcePath) => `${resourcePath}.meta`),
+                    ].map(normalizePath);
+                    const scanContext = await runtime.buildScanContext({
+                        repoRoot: input.deps.repoPath,
+                        scopedPaths,
+                        symbolDeclarations: [{ symbol: input.symbol.name, scriptPath: input.symbol.filePath }],
+                    });
+                    const resolved = await runtime.resolveBindings({
+                        repoRoot: input.deps.repoPath,
+                        symbol: input.symbol.name,
+                        scanContext,
+                        resourcePathAllowlist: resourcePaths,
+                        deepParseLargeResources: true,
+                    });
+                    unityDiagnostics.push(...resolved.unityDiagnostics);
+                    const byPath = new Map();
+                    for (const resourcePath of resourcePaths) {
+                        byPath.set(resourcePath, resolved.resourceBindings.filter((binding) => normalizePath(binding.resourcePath) === normalizePath(resourcePath)));
+                    }
+                    return byPath;
+                },
+            });
+            const freshByPath = hydration.resolvedByPath;
+            if (hydration.timedOut) {
+                unityDiagnostics.push(formatLazyHydrationBudgetDiagnostic(hydration.elapsedMs));
+            }
+            const hydrationExtras = hydration.diagnostics.filter((diag) => !/budget exceeded/i.test(diag));
+            if (hydrationExtras.length > 0) {
+                unityDiagnostics.push(...hydrationExtras);
+            }
+            await runtime.upsertOverlayBindings(input.deps.storagePath, input.deps.indexedCommit, input.symbol.uid, freshByPath);
+            for (const [resourcePath, bindings] of freshByPath.entries()) {
+                resolvedByPath.set(resourcePath, bindings);
+            }
+        }
+        catch (error) {
+            unityDiagnostics.push(`lazy-expand failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const mergedBindings = mergeUnityBindings(input.basePayload.resourceBindings, resolvedByPath);
+    return toUnityContextPayload(mergedBindings, unityDiagnostics);
+}
+function toUnityContextPayload(resourceBindings, unityDiagnostics) {
+    return {
+        resourceBindings,
+        serializedFields: {
+            scalarFields: resourceBindings.flatMap((binding) => binding.serializedFields.scalarFields),
+            referenceFields: resourceBindings.flatMap((binding) => binding.serializedFields.referenceFields),
+        },
+        unityDiagnostics,
+    };
+}
+export function __resetUnityRuntimeHydrationStateForTest() {
+    inFlightParityHydration.clear();
+}

package/dist/mcp/local/unity-runtime-hydration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/local/unity-runtime-hydration.test.js

@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { hydrateUnityForSymbol } from './unity-runtime-hydration.js';
+test('hydrateUnityForSymbol(compact) marks needsParityRetry when lightweight bindings remain', async () => {
+    const out = await hydrateUnityForSymbol({
+        mode: 'compact',
+        basePayload: {
+            resourceBindings: [
+                {
+                    resourcePath: 'Assets/A.prefab',
+                    resourceType: 'prefab',
+                    bindingKind: 'direct',
+                    componentObjectId: 'summary',
+                    lightweight: true,
+                    evidence: { line: 0, lineText: '' },
+                    serializedFields: { scalarFields: [], referenceFields: [] },
+                    resolvedReferences: [],
+                    assetRefPaths: [],
+                },
+            ],
+            serializedFields: { scalarFields: [], referenceFields: [] },
+            unityDiagnostics: [],
+        },
+        deps: {
+            executeQuery: async () => [],
+            repoPath: '/tmp/repo',
+            storagePath: '/tmp/storage',
+            indexedCommit: 'abc123',
+        },
+        symbol: {
+            uid: 'Class:Assets/Scripts/A.cs:A',
+            name: 'A',
+            filePath: 'Assets/Scripts/A.cs',
+        },
+        runtime: {
+            shouldEnableWarmup: () => false,
+            resolveLazyConfig: () => ({ maxPendingPathsPerRequest: 10, batchSize: 10, maxHydrationMs: 5000 }),
+            hydrateLazyBindings: async () => ({
+                resolvedByPath: new Map(),
+                timedOut: false,
+                elapsedMs: 1,
+                diagnostics: [],
+            }),
+            readOverlayBindings: async () => new Map(),
+            upsertOverlayBindings: async () => undefined,
+        },
+    });
+    assert.equal(out.hydrationMeta?.effectiveMode, 'compact');
+    assert.equal(out.hydrationMeta?.needsParityRetry, true);
+});
+test('hydrateUnityForSymbol(parity) sets isComplete=true on parity success', async () => {
+    const out = await hydrateUnityForSymbol({
+        mode: 'parity',
+        basePayload: {
+            resourceBindings: [
+                {
+                    resourcePath: 'Assets/A.prefab',
+                    resourceType: 'prefab',
+                    bindingKind: 'direct',
+                    componentObjectId: 'summary',
+                    lightweight: true,
+                    evidence: { line: 0, lineText: '' },
+                    serializedFields: { scalarFields: [], referenceFields: [] },
+                    resolvedReferences: [],
+                    assetRefPaths: [],
+                },
+            ],
+            serializedFields: { scalarFields: [], referenceFields: [] },
+            unityDiagnostics: [],
+        },
+        deps: {
+            executeQuery: async () => [],
+            repoPath: '/tmp/repo',
+            storagePath: '/tmp/storage',
+            indexedCommit: 'abc123',
+        },
+        symbol: {
+            uid: 'Class:Assets/Scripts/A.cs:A',
+            name: 'A',
+            filePath: 'Assets/Scripts/A.cs',
+        },
+        runtime: {
+            shouldEnableWarmup: () => false,
+            readParityCache: async () => null,
+            upsertParityCache: async () => undefined,
+            loadParitySeed: async () => null,
+            buildScanContext: async () => ({}),
+            resolveBindings: async () => ({
+                resourceBindings: [
+                    {
+                        resourcePath: 'Assets/A.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'direct',
+                        componentObjectId: '114',
+                        lightweight: false,
+                        evidence: { line: 1, lineText: 'stub' },
+                        serializedFields: { scalarFields: [], referenceFields: [] },
+                        resolvedReferences: [],
+                        assetRefPaths: [],
+                    },
+                ],
+                unityDiagnostics: [],
+            }),
+        },
+    });
+    assert.equal(out.hydrationMeta?.effectiveMode, 'parity');
+    assert.equal(out.hydrationMeta?.isComplete, true);
+});

package/dist/mcp/resources.js

@@ -64,7 +64,7 @@ export function getResourceTemplates() {
         {
             uriTemplate: 'gitnexus://repo/{name}/process/{processName}',
             name: 'Process Trace',
-            description: 'Step-by-step execution trace',
+            description: 'Step-by-step execution trace with lifecycle subtype and step evidence when available',
             mimeType: 'text/yaml',
         },
     ];
@@ -250,6 +250,12 @@ async function getProcessesResource(backend, repoName) {
             lines.push(`  - name: "${label}"`);
             lines.push(`    type: ${proc.processType || 'unknown'}`);
             lines.push(`    steps: ${proc.stepCount || 0}`);
+            if (proc.processSubtype) {
+                lines.push(`    subtype: ${proc.processSubtype}`);
+            }
+            if (proc.runtimeChainConfidence) {
+                lines.push(`    runtime_chain_confidence: ${proc.runtimeChainConfidence}`);
+            }
         }
         if (result.processes.length > displayLimit) {
             lines.push(`\n# Showing top ${displayLimit} of ${result.processes.length} processes. Use gitnexus_query for deeper search.`);
@@ -358,13 +364,17 @@ async function getProcessDetailResource(name, backend, repoName) {
         const lines = [
             `name: "${proc.heuristicLabel || proc.label || proc.id}"`,
             `type: ${proc.processType || 'unknown'}`,
+            `subtype: ${proc.processSubtype || 'static_calls'}`,
+            `runtime_chain_confidence: ${proc.runtimeChainConfidence || 'high'}`,
             `step_count: ${proc.stepCount || steps.length}`,
         ];
         if (steps.length > 0) {
             lines.push('');
             lines.push('trace:');
             for (const step of steps) {
-                lines.push(`  ${step.step}: ${step.name} (${step.filePath})`);
+                const reason = step.reason ? ` reason=${step.reason}` : '';
+                const confidence = step.confidence !== undefined ? ` confidence=${step.confidence}` : '';
+                lines.push(`  ${step.step}: ${step.name} (${step.filePath})${reason}${confidence}`);
             }
         }
         return lines.join('\n');

package/dist/mcp/tools.js

@@ -34,6 +34,18 @@ Returns results grouped by process (execution flow):
 - processes: ranked execution flows with relevance priority
 - process_symbols: all symbols in those flows with file locations and module (functional area)
 - definitions: standalone types/interfaces not in any process
+- processes[].evidence_mode: direct_step | method_projected | resource_heuristic
+- processes[].confidence: high | medium | low
+- processes[].process_subtype: unity_lifecycle | static_calls (when persisted metadata exists)
+- processes[].runtime_chain_confidence: high | medium | low (when GITNEXUS_UNITY_PROCESS_CONFIDENCE_FIELDS=on)
+- processes[].runtime_chain_evidence_level: none | clue | verified_segment | verified_chain (when GITNEXUS_UNITY_PROCESS_CONFIDENCE_FIELDS=on)
+- processes[].verification_hint: { action, target, next_command } (required when confidence=low and confidence fields flag is on)
+- process_symbols[].process_evidence_mode: direct_step | method_projected | resource_heuristic
+- process_symbols[].process_confidence: high | medium | low
+- process_symbols[].process_subtype: unity_lifecycle | static_calls (when persisted metadata exists)
+- process_symbols[].runtime_chain_confidence: high | medium | low (when GITNEXUS_UNITY_PROCESS_CONFIDENCE_FIELDS=on)
+- process_symbols[].runtime_chain_evidence_level: none | clue | verified_segment | verified_chain (when GITNEXUS_UNITY_PROCESS_CONFIDENCE_FIELDS=on)
+- process_symbols[].verification_hint: { action, target, next_command } (when confidence fields flag is on)
 
 Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.
 Supports optional scope controls for noisy codebases:
@@ -70,6 +82,12 @@ Includes optional Unity retrieval contract:
                     description: 'Unity hydration mode when unity_resources is enabled (default: compact)',
                     default: 'compact',
                 },
+                runtime_chain_verify: {
+                    type: 'string',
+                    enum: ['off', 'on-demand'],
+                    description: 'Explicit runtime chain verification mode (default: off)',
+                    default: 'off',
+                },
                 repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
             },
             required: ['query'],
@@ -134,6 +152,14 @@ AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/pro
 
 Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.
 
+Process participation metadata:
+- processes[].evidence_mode: direct_step | method_projected | resource_heuristic
+- processes[].confidence: high | medium | low
+- processes[].process_subtype: unity_lifecycle | static_calls (when persisted metadata exists)
+- processes[].runtime_chain_confidence: high | medium | low (when GITNEXUS_UNITY_PROCESS_CONFIDENCE_FIELDS=on)
+- processes[].runtime_chain_evidence_level: none | clue | verified_segment | verified_chain (when GITNEXUS_UNITY_PROCESS_CONFIDENCE_FIELDS=on)
+- processes[].verification_hint: { action, target, next_command } (required when confidence=low and confidence fields flag is on)
+
 Unity retrieval contract:
 - Set unity_resources=on|auto to include Unity resource evidence.
 - Default unity_hydration_mode=compact (fast path).
@@ -157,6 +183,12 @@ Unity retrieval contract:
                     description: 'Unity hydration mode when unity_resources is enabled (default: compact)',
                     default: 'compact',
                 },
+                runtime_chain_verify: {
+                    type: 'string',
+                    enum: ['off', 'on-demand'],
+                    description: 'Explicit runtime chain verification mode (default: off)',
+                    default: 'off',
+                },
                 repo: { type: 'string', description: 'Repository name or path. Omit if only one repo is indexed.' },
             },
             required: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.4.9",
+  "version": "1.4.11-rc",
   "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",

package/skills/_shared/unity-runtime-process-contract.md

@@ -0,0 +1,38 @@
+# Unity Runtime Process Contract
+
+Use this contract when analysis touches Unity runtime process semantics (runtime chain, lifecycle/loader stitching, or confidence-based closure).
+
+## Trigger Conditions
+
+Load this contract when any of the following is true:
+
+- Query/debug/impact/refactor task requires Unity runtime process closure.
+- Result contains Unity process evidence with `confidence` interpretation.
+- Result has empty `processes` but Unity resource evidence is present.
+- User asks for runtime-chain verification quality or closure certainty.
+
+## Required Workflow
+
+1. Run `query/context` with `unity_resources: "on"` and `unity_hydration_mode: "compact"` first.
+2. If `hydrationMeta.needsParityRetry === true`, rerun with `unity_hydration_mode: "parity"` before conclusions.
+3. Do not conclude "no runtime chain" from empty `processes` alone.
+4. If Unity evidence exists, continue stitching:
+   - `processes`
+   - `resourceBindings`
+   - asset/meta mapping anchors
+   - runtime candidate symbols
+5. Treat low-confidence rows as unresolved unless `verification_hint` includes:
+   - `action`
+   - `target`
+   - `next_command`
+6. Semantic closure requires hop anchors/evidence anchors for each stitched step.
+
+## Optional Strong Verification
+
+For Reload-focused confirmation, request on-demand verification:
+
+- pass `runtime_chain_verify: "on-demand"` in MCP tools, or
+- use CLI `--runtime-chain-verify on-demand`.
+
+When on-demand verification is used, report `runtime_chain.status`, `evidence_level`, `hops`, and `gaps` before final risk/closure statements.
+

package/skills/gitnexus-cli.md

@@ -113,6 +113,22 @@ Rules:
 - If response `hydrationMeta.needsParityRetry=true`, rerun with `--unity-hydration parity`.
 - `--unity-hydration parity` is completeness-first mode for advanced verification.
 
+### Unity runtime process contract trigger
+
+When CLI analysis targets Unity runtime process semantics (runtime chain closure/confidence), load:
+
+- `_shared/unity-runtime-process-contract.md`
+
+Runtime-process verification examples:
+
+```bash
+$GN query "Reload NEON.Game.Graph.Nodes.Reloads" --repo neonspark --unity-resources on --unity-hydration parity --runtime-chain-verify on-demand
+```
+
+```bash
+$GN context ReloadNode --repo neonspark --unity-resources on --unity-hydration compact --runtime-chain-verify on-demand
+```
+
 ### unity-ui-trace — Unity UI evidence tracing workflow
 
 ```bash

package/skills/gitnexus-debugging.md

@@ -39,6 +39,12 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 - [ ] Read source files to confirm root cause
 ```
 
+## Unity Runtime Process Trigger
+
+When debugging involves Unity runtime process semantics (runtime chain confidence, process closure certainty, lifecycle/loader stitching), load and follow:
+
+- `_shared/unity-runtime-process-contract.md`
+
 ## Debugging Patterns
 
 | Symptom              | GitNexus Approach                                          |

package/skills/gitnexus-exploring.md

@@ -39,6 +39,12 @@ description: "Use when the user asks how code works, wants to understand archite
 - [ ] Read source files for implementation details
 ```
 
+## Unity Runtime Process Trigger
+
+When exploration touches Unity runtime process semantics (runtime chain closure, lifecycle/loader stitching, confidence-based closure), load and follow:
+
+- `_shared/unity-runtime-process-contract.md`
+
 ## Resources
 
 | Resource                                | What you get                                            |

package/skills/gitnexus-guide.md

@@ -56,6 +56,10 @@ Recommended default workflow:
    - `isComplete: true` → keep compact result
 3. Treat parity as the completeness path for advanced verification.
 
+When task scope includes Unity runtime process semantics, load and follow:
+
+- `_shared/unity-runtime-process-contract.md`
+
 ### Unity UI Trace Contract (`unity_ui_trace` / `gitnexus unity-ui-trace`)
 
 Input:

package/skills/gitnexus-impact-analysis.md

@@ -38,6 +38,12 @@ description: "Use when the user wants to know what will break if they change som
 - [ ] Assess risk level and report to user
 ```
 
+## Unity Runtime Process Trigger
+
+When impact analysis depends on Unity runtime process closure or confidence interpretation, load and follow:
+
+- `_shared/unity-runtime-process-contract.md`
+
 ## Understanding Output
 
 | Depth | Risk Level       | Meaning                  |

package/skills/gitnexus-pr-review.md

@@ -28,6 +28,11 @@ description: "Use when the user wants to review a pull request, understand what
 
 > If "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze` before reviewing.
 
+Conditional triggers:
+- If analysis touches Unity serialized/binding-state interpretation, apply `_shared/unity-resource-binding-contract.md`.
+- If analysis touches UIToolkit visual semantics, apply `_shared/unity-ui-trace-contract.md`.
+- If analysis touches Unity runtime process semantics (runtime chain closure/confidence), apply `_shared/unity-runtime-process-contract.md`.
+
 ## Checklist
 
 ```