@veewo/gitnexus 1.4.9 → 1.4.11-rc

package/dist/benchmark/u2-e2e/retrieval-runner.js

@@ -1,6 +1,9 @@
 import { performance } from 'node:perf_hooks';
 import path from 'node:path';
 import { estimateTokens } from './metrics.js';
+export function containsPlaceholderLeak(value) {
+    return /TODO|TBD|placeholder|<symbol-or-query>/i.test(String(value || ''));
+}
 function stringify(value) {
     try {
         return JSON.stringify(value ?? null);
@@ -53,7 +56,57 @@ function hasDeepDiveEvidence(output) {
     const outgoingRefs = countRefs(output?.outgoing);
     return processSymbols + definitions + candidates + rows + byDepth + impacted + incomingRefs + outgoingRefs > 0;
 }
-function assertScenario(scenario, contextOnOutput, deepDiveOutputs, contextUnityHydration) {
+function hasQueryUnityEvidence(output) {
+    const symbols = [
+        ...(Array.isArray(output?.process_symbols) ? output.process_symbols : []),
+        ...(Array.isArray(output?.definitions) ? output.definitions : []),
+    ];
+    return symbols.some((symbol) => {
+        const bindings = Array.isArray(symbol?.resourceBindings) ? symbol.resourceBindings.length : 0;
+        const scalarFields = Array.isArray(symbol?.serializedFields?.scalarFields) ? symbol.serializedFields.scalarFields.length : 0;
+        const referenceFields = Array.isArray(symbol?.serializedFields?.referenceFields) ? symbol.serializedFields.referenceFields.length : 0;
+        return bindings + scalarFields + referenceFields > 0;
+    });
+}
+function normalizeRate(count, total) {
+    if (!Number.isFinite(total) || total <= 0)
+        return 0;
+    const pct = (count / total) * 100;
+    return Number(pct.toFixed(3));
+}
+export function summarizePhase5ConfidenceCalibration(input) {
+    const artifactPath = String(input.baseline?.artifactPath || '').trim();
+    const gitCommit = String(input.baseline?.gitCommit || '').trim();
+    const sha256 = String(input.baseline?.sha256 || '').trim();
+    if (!artifactPath || !gitCommit || !sha256) {
+        throw new Error('baseline provenance missing: artifactPath/gitCommit/sha256 are required');
+    }
+    const baselineTotal = Number(input.baseline.totalEvaluated || input.current.totalEvaluated || 0);
+    const baselineFalseNegative = Number(input.baseline.falseNegativeCount || 0);
+    const baselineFalseConfidence = Number(input.baseline.falseConfidenceCount || 0);
+    const current = input.current;
+    const falseNegativeRateBaselinePct = normalizeRate(baselineFalseNegative, baselineTotal);
+    const falseNegativeRateCurrentPct = normalizeRate(current.falseNegativeCount, current.totalEvaluated);
+    const falseConfidenceRateBaselinePct = normalizeRate(baselineFalseConfidence, baselineTotal);
+    const falseConfidenceRateCurrentPct = normalizeRate(current.falseConfidenceCount, current.totalEvaluated);
+    return {
+        lowConfidenceHintCoverage: normalizeRate(current.lowConfidenceHintCovered, current.lowConfidenceCount),
+        falseConfidenceFailures: current.falseConfidenceCount,
+        falseNegativeFallbackCoverage: current.fallbackCovered,
+        falseNegativeRateBaselinePct,
+        falseNegativeRateCurrentPct,
+        falseNegativeRateDeltaPct: Number((falseNegativeRateCurrentPct - falseNegativeRateBaselinePct).toFixed(3)),
+        falseConfidenceRateBaselinePct,
+        falseConfidenceRateCurrentPct,
+        falseConfidenceRateDeltaPct: Number((falseConfidenceRateCurrentPct - falseConfidenceRateBaselinePct).toFixed(3)),
+        baseline: {
+            artifactPath,
+            gitCommit,
+            sha256,
+        },
+    };
+}
+function assertScenario(scenario, contextOnOutput, deepDiveExecutions, contextUnityHydration) {
     const failures = [];
     const bindings = Array.isArray(contextOnOutput?.resourceBindings) ? contextOnOutput.resourceBindings : [];
     const hasBindings = bindings.length > 0;
@@ -90,11 +143,48 @@ function assertScenario(scenario, contextOnOutput, deepDiveOutputs, contextUnity
         if (!hasBindings) {
             failures.push('AssetRef: context(on) must include resourceBindings');
         }
-        const deepDiveEvidence = deepDiveOutputs.some((output) => hasDeepDiveEvidence(output));
+        const deepDiveEvidence = deepDiveExecutions.some((step) => hasDeepDiveEvidence(step.output));
         if (!deepDiveEvidence) {
             failures.push('AssetRef: deep-dive must provide usage/dependency evidence');
         }
     }
+    const queryOnRuns = deepDiveExecutions.filter((step) => step.tool === 'query' && String(step.input?.unity_resources || '').toLowerCase() === 'on');
+    if (queryOnRuns.length > 0) {
+        const hasUnityEvidenceFromQueryOn = queryOnRuns.some((step) => hasQueryUnityEvidence(step.output));
+        if (!hasUnityEvidenceFromQueryOn) {
+            failures.push(`${scenario.symbol}: query(on) must include unity serialized/resource evidence`);
+        }
+        for (const step of queryOnRuns) {
+            const processes = Array.isArray(step.output?.processes) ? step.output.processes : [];
+            const hasUnityEvidence = hasQueryUnityEvidence(step.output);
+            if (hasUnityEvidence && processes.length === 0) {
+                failures.push(`${scenario.symbol}: empty process query(on) with unity evidence must emit confidence-guided fallback clue`);
+            }
+            for (const processRow of processes) {
+                const confidence = String(processRow?.confidence || '').toLowerCase();
+                const evidenceMode = String(processRow?.evidence_mode || '').toLowerCase();
+                const processSubtype = String(processRow?.process_subtype || '').toLowerCase();
+                if (confidence === 'low') {
+                    const hint = processRow?.verification_hint;
+                    const action = String(hint?.action || '').trim();
+                    const target = String(hint?.target || '').trim();
+                    const nextCommand = String(hint?.next_command || '').trim();
+                    if (!action || !target || !nextCommand) {
+                        failures.push(`${scenario.symbol}: low confidence query(on) row missing verification_hint action/target/next_command`);
+                    }
+                    else if (!/parity|asset|meta/i.test(nextCommand)) {
+                        failures.push(`${scenario.symbol}: low confidence verification_hint must include parity/manual asset-meta guidance`);
+                    }
+                    else if (containsPlaceholderLeak(nextCommand)) {
+                        failures.push(`${scenario.symbol}: low confidence verification_hint leaks placeholder command text`);
+                    }
+                }
+                if (evidenceMode === 'direct_step' && processSubtype === 'static_calls' && confidence !== 'high') {
+                    failures.push(`${scenario.symbol}: direct static chain rows must remain high confidence`);
+                }
+            }
+        }
+    }
     return {
         pass: failures.length === 0,
         failures,
@@ -168,7 +258,7 @@ export async function runSymbolScenario(runner, scenario, repo) {
     const t1 = performance.now();
     const contextOn = await runContextWithDisambiguation(runner, scenario, contextOnInput);
     steps.push(buildMetric('context-on', 'context', performance.now() - t1, contextOnInput, contextOn));
-    const deepDiveOutputs = [];
+    const deepDiveExecutions = [];
     for (let i = 0; i < scenario.deepDivePlan.length; i += 1) {
         const step = scenario.deepDivePlan[i];
         const input = { ...(step.input || {}) };
@@ -177,12 +267,12 @@ export async function runSymbolScenario(runner, scenario, repo) {
         }
         const ts = performance.now();
         const output = await invokeTool(runner, step.tool, input);
-        deepDiveOutputs.push(output);
+        deepDiveExecutions.push({ tool: step.tool, input, output });
         steps.push(buildMetric(`deep-dive-${i + 1}`, step.tool, performance.now() - ts, input, output));
     }
     return {
         symbol: scenario.symbol,
         steps,
-        assertions: assertScenario(scenario, contextOn, deepDiveOutputs, contextUnityHydration),
+        assertions: assertScenario(scenario, contextOn, deepDiveExecutions, contextUnityHydration),
     };
 }

package/dist/benchmark/u2-e2e/retrieval-runner.test.js

@@ -1,7 +1,10 @@
-import test from 'node:test';
 import assert from 'node:assert/strict';
-import { runSymbolScenario } from './retrieval-runner.js';
+import { containsPlaceholderLeak, runSymbolScenario, summarizePhase5ConfidenceCalibration } from './retrieval-runner.js';
 import { loadE2EConfig } from './config.js';
+const { test: rawTest } = process.env.VITEST
+    ? await import('vitest')
+    : await import('node:test');
+const test = rawTest;
 test('runSymbolScenario executes context off/on + deepDive and records metrics', async () => {
     const mockToolRunner = {
         context: async (input) => {
@@ -186,3 +189,159 @@ test('runSymbolScenario fails when compact context hydrationMeta.needsParityRetr
     assert.equal(out.assertions.pass, false);
     assert.ok(out.assertions.failures.some((f) => f.includes('hydrationMeta.needsParityRetry')));
 });
+test('runSymbolScenario fails when query(on) has no unity serialized/resource evidence', async () => {
+    const runner = {
+        context: async (input) => {
+            if (input.unity_resources === 'on') {
+                return {
+                    status: 'found',
+                    hydrationMeta: {
+                        requestedMode: 'compact',
+                        effectiveMode: 'compact',
+                        isComplete: false,
+                        needsParityRetry: true,
+                    },
+                    resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab', resourceType: 'prefab' }],
+                    serializedFields: { scalarFields: [], referenceFields: [] },
+                };
+            }
+            return { status: 'found' };
+        },
+        query: async () => ({ process_symbols: [{ id: 'Class:A' }] }),
+        impact: async () => ({ impactedCount: 1 }),
+        cypher: async () => ({ rows: [] }),
+    };
+    const out = await runSymbolScenario(runner, {
+        symbol: 'MainUIManager',
+        kind: 'component',
+        objectives: ['verify query evidence gate'],
+        deepDivePlan: [{ tool: 'query', input: { query: 'MainUIManager', unity_resources: 'on' } }],
+    });
+    assert.equal(out.assertions.pass, false);
+    assert.ok(out.assertions.failures.some((f) => f.includes('query(on) must include unity serialized/resource evidence')));
+});
+test('phase5 confidence calibration fails when low confidence process is missing verification_hint', async () => {
+    const runner = {
+        context: async (input) => {
+            if (input.unity_resources === 'on') {
+                return {
+                    status: 'found',
+                    hydrationMeta: {
+                        requestedMode: 'compact',
+                        effectiveMode: 'compact',
+                        isComplete: false,
+                        needsParityRetry: true,
+                    },
+                    resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab', resourceType: 'prefab' }],
+                };
+            }
+            return { status: 'found' };
+        },
+        query: async () => ({
+            processes: [{ confidence: 'low', evidence_mode: 'resource_heuristic' }],
+            process_symbols: [{ id: 'Class:A', resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab' }] }],
+        }),
+        impact: async () => ({ impactedCount: 0 }),
+        cypher: async () => ({ rows: [] }),
+    };
+    const out = await runSymbolScenario(runner, {
+        symbol: 'MainUIManager',
+        kind: 'component',
+        objectives: ['phase5 low confidence hint gate'],
+        deepDivePlan: [{ tool: 'query', input: { query: 'MainUIManager', unity_resources: 'on' } }],
+    });
+    assert.equal(out.assertions.pass, false);
+    assert.ok(out.assertions.failures.some((f) => /verification_hint/i.test(f)));
+});
+test('phase5 confidence calibration fails when empty process result with unity evidence has no fallback clue', async () => {
+    const runner = {
+        context: async (input) => {
+            if (input.unity_resources === 'on') {
+                return {
+                    status: 'found',
+                    hydrationMeta: {
+                        requestedMode: 'compact',
+                        effectiveMode: 'compact',
+                        isComplete: false,
+                        needsParityRetry: true,
+                    },
+                    resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab', resourceType: 'prefab' }],
+                };
+            }
+            return { status: 'found' };
+        },
+        query: async () => ({
+            processes: [],
+            process_symbols: [{ id: 'Class:A', resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab' }] }],
+        }),
+        impact: async () => ({ impactedCount: 0 }),
+        cypher: async () => ({ rows: [] }),
+    };
+    const out = await runSymbolScenario(runner, {
+        symbol: 'MainUIManager',
+        kind: 'component',
+        objectives: ['phase5 empty process fallback gate'],
+        deepDivePlan: [{ tool: 'query', input: { query: 'MainUIManager', unity_resources: 'on' } }],
+    });
+    assert.equal(out.assertions.pass, false);
+    assert.ok(out.assertions.failures.some((f) => /fallback|empty process/i.test(f)));
+});
+test('phase5 confidence calibration fails when direct static chain is not high confidence', async () => {
+    const runner = {
+        context: async (input) => {
+            if (input.unity_resources === 'on') {
+                return {
+                    status: 'found',
+                    hydrationMeta: {
+                        requestedMode: 'compact',
+                        effectiveMode: 'compact',
+                        isComplete: false,
+                        needsParityRetry: true,
+                    },
+                    resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab', resourceType: 'prefab' }],
+                };
+            }
+            return { status: 'found' };
+        },
+        query: async () => ({
+            processes: [{
+                    confidence: 'medium',
+                    evidence_mode: 'direct_step',
+                    process_subtype: 'static_calls',
+                    verification_hint: { action: 'none', target: 'none', next_command: 'none' },
+                }],
+            process_symbols: [{ id: 'Class:A', resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab' }] }],
+        }),
+        impact: async () => ({ impactedCount: 0 }),
+        cypher: async () => ({ rows: [] }),
+    };
+    const out = await runSymbolScenario(runner, {
+        symbol: 'MainUIManager',
+        kind: 'component',
+        objectives: ['phase5 direct static confidence gate'],
+        deepDivePlan: [{ tool: 'query', input: { query: 'MainUIManager', unity_resources: 'on' } }],
+    });
+    assert.equal(out.assertions.pass, false);
+    assert.ok(out.assertions.failures.some((f) => /direct.*static.*high/i.test(f)));
+});
+test('phase5 confidence calibration summary requires baseline provenance fields', async () => {
+    assert.throws(() => summarizePhase5ConfidenceCalibration({
+        current: {
+            totalEvaluated: 4,
+            falseNegativeCount: 1,
+            falseConfidenceCount: 1,
+            lowConfidenceHintCovered: 1,
+            lowConfidenceCount: 2,
+            fallbackCovered: 2,
+        },
+        baseline: {
+            totalEvaluated: 4,
+            falseNegativeCount: 2,
+            falseConfidenceCount: 2,
+        },
+    }), /baseline provenance/i);
+});
+test('phase5 confidence calibration detects placeholder leakage in next_command', async () => {
+    assert.equal(containsPlaceholderLeak('Inspect <symbol-or-query> later'), true);
+    assert.equal(containsPlaceholderLeak('gitnexus query --unity-resources on'), false);
+});

package/dist/cli/ai-context.js

@@ -42,6 +42,7 @@ function generateGitNexusContent(projectName, stats, skillScope, cliPackageSpec,
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 4. **Follow config/state file rules:** \`docs/gitnexus-config-files.md\`
+5. **If user asks to release/publish a specific version and this repo has \`DISTRIBUTION.md\`, execute that workflow in full-release mode by default** (unless user explicitly asks \`prepare-only\` or \`publish-only\`).
 
 > If step 1 warns the index is stale, ask user whether to rebuild index via \`gitnexus analyze\` when local CLI exists; otherwise resolve the pinned npx package spec from \`~/.gitnexus/config.json\` (\`cliPackageSpec\` first, then \`cliVersion\`) and run \`${reindexCmd}\` with that exact package spec (it reuses previous analyze scope/options by default; add \`--no-reuse-options\` to reset). If user declines, explicitly warn that retrieval may not reflect current codebase. For build/analyze/test commands, use a 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently fall back to glob/grep.
 
@@ -56,6 +57,12 @@ function generateGitNexusContent(projectName, stats, skillScope, cliPackageSpec,
 | Tools, resources, schema reference | \`${skillRoot}/gitnexus-guide/SKILL.md\` |
 | Index, status, clean, wiki CLI commands | \`${skillRoot}/gitnexus-cli/SKILL.md\` |${generatedRows}
 
+## Unity Runtime Process 真理源
+
+- 统一设计与实现对照文档：\`docs/unity-runtime-process-source-of-truth.md\`
+- 涉及 Unity runtime process 的任务，先阅读该文档，再执行检索/实现/验收。
+- 若历史设计文档与当前实现不一致，以该真理源文档和对应代码为准，并在变更后同步更新。
+
 ${GITNEXUS_END_MARKER}`;
 }
 /**
@@ -106,6 +113,7 @@ async function upsertGitNexusSection(filePath, content) {
 async function installSkills(repoPath) {
     const skillsDir = path.join(repoPath, '.agents', 'skills', 'gitnexus');
     const installedSkills = [];
+    const packageSkillsRoot = path.join(__dirname, '..', '..', 'skills');
     // Skill definitions bundled with the package
     const skills = [
         {
@@ -140,7 +148,7 @@ async function installSkills(repoPath) {
             // 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`);
+            const packageSkillPath = path.join(packageSkillsRoot, `${skill.name}.md`);
             let skillContent;
             try {
                 skillContent = await fs.readFile(packageSkillPath, 'utf-8');
@@ -167,8 +175,31 @@ Use GitNexus tools to accomplish this task.
             console.warn(`Warning: Could not install skill ${skill.name}:`, err);
         }
     }
+    // Shared workflow contracts (if bundled).
+    const packageSharedDir = path.join(packageSkillsRoot, '_shared');
+    try {
+        await fs.access(packageSharedDir);
+        await copyDirRecursive(packageSharedDir, path.join(skillsDir, '_shared'));
+    }
+    catch {
+        // Optional: older bundles may not include shared docs.
+    }
     return installedSkills;
 }
+async function copyDirRecursive(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+        }
+    }
+}
 /**
  * Generate AI context files after indexing
  */

package/dist/cli/ai-context.test.js

@@ -15,12 +15,18 @@ test('generateAIContextFiles installs repo skills under .agents/skills/gitnexus'
         const agentsPath = path.join(repoPath, 'AGENTS.md');
         const claudePath = path.join(repoPath, 'CLAUDE.md');
         const skillPath = path.join(repoPath, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        const sharedRuntimeContractPath = path.join(repoPath, '.agents', 'skills', 'gitnexus', '_shared', 'unity-runtime-process-contract.md');
         const legacyClaudeSkillsDir = path.join(repoPath, '.claude', 'skills');
         const agentsContent = await fs.readFile(agentsPath, 'utf-8');
         const claudeContent = await fs.readFile(claudePath, 'utf-8');
         await fs.access(skillPath);
+        await fs.access(sharedRuntimeContractPath);
         assert.match(agentsContent, /\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
         assert.match(claudeContent, /\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
+        assert.match(agentsContent, /## Unity Runtime Process 真理源/);
+        assert.match(agentsContent, /docs\/unity-runtime-process-source-of-truth\.md/);
+        assert.match(claudeContent, /## Unity Runtime Process 真理源/);
+        assert.match(claudeContent, /docs\/unity-runtime-process-source-of-truth\.md/);
         assert.ok(result.files.some((entry) => entry.includes('.agents/skills/gitnexus/')), 'expected generated file summary to include .agents/skills/gitnexus/');
         await assert.rejects(fs.access(legacyClaudeSkillsDir));
     }
@@ -43,6 +49,10 @@ test('generateAIContextFiles with global scope skips repo skill install', async
         const claudeContent = await fs.readFile(claudePath, 'utf-8');
         assert.match(agentsContent, /~\/\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
         assert.match(claudeContent, /~\/\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
+        assert.match(agentsContent, /## Unity Runtime Process 真理源/);
+        assert.match(agentsContent, /docs\/unity-runtime-process-source-of-truth\.md/);
+        assert.match(claudeContent, /## Unity Runtime Process 真理源/);
+        assert.match(claudeContent, /docs\/unity-runtime-process-source-of-truth\.md/);
         assert.ok(!result.files.some((entry) => entry.includes('.agents/skills/gitnexus/')), 'did not expect repo-local skills in generated file summary');
         await assert.rejects(fs.access(localSkillsDir));
     }

package/dist/cli/analyze-summary.d.ts

@@ -5,3 +5,4 @@ export interface FallbackInsertStats {
 }
 export declare function formatUnityDiagnosticsSummary(diagnostics: string[] | undefined, previewLimit?: number): string[];
 export declare function formatFallbackSummary(warnings: string[] | undefined, stats: FallbackInsertStats | undefined, previewLimit?: number): string[];
+export declare function resolveFallbackStats(warnings: string[] | undefined, stats: FallbackInsertStats | undefined): FallbackInsertStats;

package/dist/cli/analyze-summary.js

@@ -35,3 +35,24 @@ export function formatFallbackSummary(warnings, stats, previewLimit = 5) {
     }
     return lines;
 }
+export function resolveFallbackStats(warnings, stats) {
+    if (stats) {
+        return stats;
+    }
+    if (!warnings || warnings.length === 0) {
+        return {
+            attempted: 0,
+            succeeded: 0,
+            failed: 0,
+        };
+    }
+    const attempted = warnings.reduce((sum, warning) => {
+        const match = warning.match(/\((\d+)\s+edges\)/);
+        return sum + (match ? Number.parseInt(match[1] || '0', 10) : 0);
+    }, 0);
+    return {
+        attempted,
+        succeeded: 0,
+        failed: attempted,
+    };
+}

package/dist/cli/analyze-summary.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { formatFallbackSummary, formatUnityDiagnosticsSummary } from './analyze-summary.js';
+import { formatFallbackSummary, formatUnityDiagnosticsSummary, resolveFallbackStats } from './analyze-summary.js';
 test('formatUnityDiagnosticsSummary returns empty when diagnostics are missing', () => {
     const lines = formatUnityDiagnosticsSummary([]);
     assert.deepEqual(lines, []);
@@ -56,3 +56,9 @@ test('formatFallbackSummary renders attempted/succeeded/failed with warning prev
         '... 1 more',
     ]);
 });
+test('resolveFallbackStats prefers runtime fallback insert stats when available', () => {
+    assert.deepEqual(resolveFallbackStats(['Class->File (12 edges): missing rel pair in schema'], { attempted: 12, succeeded: 3, failed: 9 }), { attempted: 12, succeeded: 3, failed: 9 });
+});
+test('resolveFallbackStats derives attempted/failed from warnings when runtime stats are missing', () => {
+    assert.deepEqual(resolveFallbackStats(['Class->File (7 edges): missing rel pair in schema'], undefined), { attempted: 7, succeeded: 0, failed: 7 });
+});

package/dist/cli/analyze.js

@@ -19,7 +19,7 @@ import { generateAIContextFiles } from './ai-context.js';
 import { generateSkillFiles } from './skill-gen.js';
 import fs from 'fs/promises';
 import { resolveEffectiveAnalyzeOptions } from './analyze-options.js';
-import { formatFallbackSummary, formatUnityDiagnosticsSummary } from './analyze-summary.js';
+import { formatFallbackSummary, formatUnityDiagnosticsSummary, resolveFallbackStats } from './analyze-summary.js';
 import { resolveChildProcessExit } from './exit-code.js';
 import { toPipelineRuntimeSummary } from './analyze-runtime-summary.js';
 import { resolveCliSpec } from '../config/cli-spec.js';
@@ -442,15 +442,8 @@ export const analyzeCommand = async (inputPath, options) => {
         console.log(`  Context: ${aiContext.files.join(', ')}`);
     }
     if (lbugWarnings.length > 0) {
-        const totalFallback = lbugWarnings.reduce((sum, warning) => {
-            const match = warning.match(/\((\d+) edges\)/);
-            return sum + (match ? Number.parseInt(match[1], 10) : 0);
-        }, 0);
-        const fallbackLines = formatFallbackSummary(lbugWarnings, {
-            attempted: totalFallback,
-            succeeded: totalFallback,
-            failed: 0,
-        });
+        const fallbackStats = resolveFallbackStats(lbugWarnings, lbugResult.fallbackInsertStats);
+        const fallbackLines = formatFallbackSummary(lbugWarnings, fallbackStats);
         for (const line of fallbackLines) {
             console.log(`  ${line}`);
         }

package/dist/cli/eval-server.js

@@ -111,7 +111,7 @@ export function formatContextResult(result) {
     if (procs.length > 0) {
         lines.push(`Participates in ${procs.length} execution flow(s):`);
         for (const p of procs) {
-            lines.push(`  • ${p.name} (step ${p.step_index}/${p.step_count})`);
+            lines.push(`  • ${p.name} (step ${p.step_index}/${p.step_count}, evidence=${p.evidence_mode || 'direct_step'}, confidence=${p.confidence || 'high'})`);
         }
     }
     if (sym.content) {

package/dist/cli/index.js

@@ -85,6 +85,7 @@ program
     .option('--scope-preset <preset>', 'Scope preset for retrieval: unity-gameplay|unity-all')
     .option('--unity-resources <mode>', 'Unity resource retrieval mode: off|on|auto', 'off')
     .option('--unity-hydration <mode>', 'Unity hydration mode when resources are enabled: parity|compact', 'compact')
+    .option('--runtime-chain-verify <mode>', 'Runtime chain verification mode: off|on-demand', 'off')
     .action(createLazyAction(() => import('./tool.js'), 'queryCommand'));
 program
     .command('context [name]')
@@ -95,6 +96,7 @@ program
     .option('--content', 'Include full symbol source code')
     .option('--unity-resources <mode>', 'Unity resource retrieval mode: off|on|auto', 'off')
     .option('--unity-hydration <mode>', 'Unity hydration mode when resources are enabled: parity|compact', 'compact')
+    .option('--runtime-chain-verify <mode>', 'Runtime chain verification mode: off|on-demand', 'off')
     .action(createLazyAction(() => import('./tool.js'), 'contextCommand'));
 program
     .command('unity-bindings <symbol>')

package/dist/cli/setup.js

@@ -450,6 +450,15 @@ async function installSkillsTo(targetDir) {
             // Source skill not found — skip
         }
     }
+    // Shared workflow contracts distributed alongside skills.
+    const sharedSource = path.join(skillsRoot, '_shared');
+    try {
+        await fs.access(sharedSource);
+        await copyDirRecursive(sharedSource, path.join(targetDir, '_shared'));
+    }
+    catch {
+        // Optional shared contracts directory may be absent in older packages.
+    }
     return installed;
 }
 /**

package/dist/cli/setup.test.js

@@ -90,8 +90,10 @@ test('setup installs global skills under ~/.agents/skills/gitnexus', async () =>
             USERPROFILE: fakeHome,
         });
         const skillPath = path.join(fakeHome, '.agents', 'skills', 'gitnexus', 'gitnexus-exploring', 'SKILL.md');
+        const sharedRuntimeContractPath = path.join(fakeHome, '.agents', 'skills', 'gitnexus', '_shared', 'unity-runtime-process-contract.md');
         const configPath = path.join(fakeHome, '.gitnexus', 'config.json');
         await fs.access(skillPath);
+        await fs.access(sharedRuntimeContractPath);
         const configRaw = await fs.readFile(configPath, 'utf-8');
         const config = JSON.parse(configRaw);
         assert.equal(config.setupScope, 'global');

package/dist/cli/tool.d.ts

@@ -24,6 +24,7 @@ export declare function queryCommand(queryText: string, options?: {
     scopePreset?: 'unity-gameplay' | 'unity-all';
     unityResources?: UnityResourcesMode;
     unityHydration?: UnityHydrationMode;
+    runtimeChainVerify?: 'off' | 'on-demand';
 }): Promise<void>;
 export declare function contextCommand(name: string, options?: {
     repo?: string;
@@ -32,6 +33,7 @@ export declare function contextCommand(name: string, options?: {
     content?: boolean;
     unityResources?: UnityResourcesMode;
     unityHydration?: UnityHydrationMode;
+    runtimeChainVerify?: 'off' | 'on-demand';
 }): Promise<void>;
 export declare function impactCommand(target: string, options?: {
     direction?: string;

package/dist/cli/tool.js

@@ -94,6 +94,7 @@ export async function queryCommand(queryText, options) {
         scope_preset: options?.scopePreset,
         unity_resources: options?.unityResources,
         unity_hydration_mode: options?.unityHydration,
+        runtime_chain_verify: options?.runtimeChainVerify,
         repo,
     });
     output(result);
@@ -112,6 +113,7 @@ export async function contextCommand(name, options) {
         include_content: options?.content ?? false,
         unity_resources: options?.unityResources,
         unity_hydration_mode: options?.unityHydration,
+        runtime_chain_verify: options?.runtimeChainVerify,
         repo,
     });
     output(result);

package/dist/core/ingestion/pipeline.js

@@ -8,6 +8,8 @@ import { computeMRO } from './mro-processor.js';
 import { processCommunities } from './community-processor.js';
 import { processProcesses } from './process-processor.js';
 import { processUnityResources } from './unity-resource-processor.js';
+import { applyUnityLifecycleSyntheticCalls } from './unity-lifecycle-synthetic-calls.js';
+import { resolveUnityLifecycleConfig } from './unity-lifecycle-config.js';
 import { createResolutionContext } from './resolution-context.js';
 import { createASTCache } from './ast-cache.js';
 import { walkRepositoryPaths, readFileContents, walkUnityResourcePaths } from './filesystem-walker.js';
@@ -342,11 +344,20 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
                     reason: 'leiden-algorithm',
                 });
             });
+            const unityLifecycleConfig = resolveUnityLifecycleConfig(process.env);
+            const persistLifecycleProcessMetadata = unityLifecycleConfig.persistLifecycleProcessMetadata;
+            const unityLifecycleSyntheticResult = applyUnityLifecycleSyntheticCalls(graph, unityLifecycleConfig);
+            const syntheticEdgeDetail = unityLifecycleSyntheticResult.syntheticEdgeCount > 0
+                ? ` (Unity synthetic edges: ${unityLifecycleSyntheticResult.syntheticEdgeCount})`
+                : '';
+            if (isDev && unityLifecycleConfig.enabled) {
+                console.log(`[UnityLifecycle] enabled=${unityLifecycleConfig.enabled} hosts=${unityLifecycleSyntheticResult.hostCount} syntheticEdges=${unityLifecycleSyntheticResult.syntheticEdgeCount} rejectedHosts=${unityLifecycleSyntheticResult.rejectedHostCount}`);
+            }
             // ── Phase 6: Processes ─────────────────────────────────────────────
             onProgress({
                 phase: 'processes',
                 percent: 94,
-                message: 'Detecting execution flows...',
+                message: `Detecting execution flows...${syntheticEdgeDetail}`,
                 stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
             });
             let symbolCount = 0;
@@ -378,17 +389,27 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
                         communities: proc.communities,
                         entryPointId: proc.entryPointId,
                         terminalId: proc.terminalId,
+                        ...(persistLifecycleProcessMetadata
+                            ? {
+                                processSubtype: proc.processSubtype,
+                                runtimeChainConfidence: proc.runtimeChainConfidence,
+                                sourceReasons: proc.sourceReasons,
+                                sourceConfidences: proc.sourceConfidences,
+                            }
+                            : {}),
                     }
                 });
             });
             processResult.steps.forEach(step => {
+                const persistedReason = persistLifecycleProcessMetadata ? (step.reason || 'trace-detection') : 'trace-detection';
+                const persistedConfidence = persistLifecycleProcessMetadata ? (step.confidence ?? 1.0) : 1.0;
                 graph.addRelationship({
                     id: `${step.nodeId}_step_${step.step}_${step.processId}`,
                     type: 'STEP_IN_PROCESS',
                     sourceId: step.nodeId,
                     targetId: step.processId,
-                    confidence: 1.0,
-                    reason: 'trace-detection',
+                    confidence: persistedConfidence,
+                    reason: persistedReason,
                     step: step.step,
                 });
             });