@veewo/gitnexus 1.5.0 → 1.5.2

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

@@ -43,6 +43,52 @@ test('runSymbolScenario executes context off/on + deepDive and records metrics',
     assert.ok(out.steps.every((s) => s.totalTokensEst >= 0));
     assert.equal(out.assertions.pass, true);
 });
+test('runSymbolScenario injects response_profile=full for legacy context/query steps', async () => {
+    const seen = [];
+    const runner = {
+        context: async (input) => {
+            seen.push({ tool: 'context', input });
+            if (input.unity_resources === 'on') {
+                return {
+                    status: 'found',
+                    hydrationMeta: {
+                        requestedMode: 'compact',
+                        effectiveMode: 'compact',
+                        isComplete: false,
+                        needsParityRetry: true,
+                    },
+                    resourceBindings: [{ resourcePath: 'Assets/Prefabs/UI.prefab', resourceType: 'prefab' }],
+                };
+            }
+            return { status: 'found' };
+        },
+        query: async (input) => {
+            seen.push({ tool: 'query', input });
+            return {
+                process_symbols: [{ id: 'Class:MainUIManager' }],
+                definitions: [{ name: 'DoorObj', resourceBindings: [{ resourcePath: 'Assets/A.prefab' }] }],
+            };
+        },
+        impact: async (input) => {
+            seen.push({ tool: 'impact', input });
+            return { impactedCount: 1 };
+        },
+        cypher: async (input) => {
+            seen.push({ tool: 'cypher', input });
+            return { rows: [] };
+        },
+    };
+    await runSymbolScenario(runner, {
+        symbol: 'MainUIManager',
+        kind: 'component',
+        objectives: ['verify context'],
+        deepDivePlan: [{ tool: 'query', input: { query: 'MainUIManager' } }],
+    });
+    const contextCalls = seen.filter((entry) => entry.tool === 'context');
+    const queryCalls = seen.filter((entry) => entry.tool === 'query');
+    assert.equal(contextCalls.every((entry) => entry.input.response_profile === 'full'), true);
+    assert.equal(queryCalls.every((entry) => entry.input.response_profile === 'full'), true);
+});
 test('AssetRef requires context(on) resourceBindings after serializable-class coverage', async () => {
     const noEvidenceRunner = {
         context: async () => ({

package/dist/cli/ai-context.js

@@ -43,6 +43,8 @@ function generateGitNexusContent(projectName, stats, skillScope, generatedSkills
 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 \`npx -y <resolved-spec> analyze\` (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.
+> \`query/context\` slim guidance is narrowing-first: inspect \`decision.recommended_follow_up\`, \`missing_proof_targets\`, and \`suggested_context_targets\` before upgrading to \`response_profile=full\`.
+> Query-time runtime closure is graph-only and does not require \`verification_rules\` / \`trigger_tokens\`; if you need hydration diagnostics such as \`needsParityRetry\` or strict fallback state, rerun with \`response_profile=full\` and then use parity before closure claims.
 
 ## Skills
 
@@ -56,18 +58,6 @@ function generateGitNexusContent(projectName, stats, skillScope, generatedSkills
 | Index, status, clean, wiki CLI commands | \`${skillRoot}/gitnexus-cli/SKILL.md\` |
 | Create Unity analyze_rules interactively | \`${skillRoot}/gitnexus-unity-rule-gen/SKILL.md\` |${generatedRows}
 
-## Dev Workflow (Source Build)
-
-To use a locally built dist instead of the globally installed package (useful when testing unreleased changes):
-
-\`\`\`bash
-cd /path/to/GitNexus/gitnexus
-npm run build
-npm link   # replaces global install with symlink to local dist/cli/index.js
-\`\`\`
-
-After \`npm link\`, \`gitnexus\` on this machine points to the local dist. All repos using \`gitnexus mcp\` in their MCP config will pick up the new build after restarting the agent session. To restore the published package: \`npm unlink -g @veewo/gitnexus && npm install -g @veewo/gitnexus\`.
-
 ${GITNEXUS_END_MARKER}`;
 }
 /**

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

@@ -21,10 +21,14 @@ test('generateAIContextFiles installs repo skills under .agents/skills/gitnexus'
         const claudeContent = await fs.readFile(claudePath, 'utf-8');
         await fs.access(skillPath);
         await fs.access(sharedRuntimeContractPath);
+        assert.match(agentsContent, /slim guidance is narrowing-first/);
+        assert.match(agentsContent, /Query-time runtime closure is graph-only/);
         assert.match(agentsContent, /\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
         assert.match(claudeContent, /\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
         assert.doesNotMatch(agentsContent, /## Unity Runtime Process 真理源/);
         assert.doesNotMatch(claudeContent, /## Unity Runtime Process 真理源/);
+        assert.doesNotMatch(agentsContent, /## Dev Workflow \(Source Build\)/);
+        assert.doesNotMatch(claudeContent, /## Dev Workflow \(Source Build\)/);
         assert.equal(agentsContent, claudeContent, 'AGENTS.md and CLAUDE.md should stay content-identical');
         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));
@@ -46,10 +50,14 @@ test('generateAIContextFiles with global scope skips repo skill install', async
         const localSkillsDir = path.join(repoPath, '.agents', 'skills', 'gitnexus');
         const agentsContent = await fs.readFile(agentsPath, 'utf-8');
         const claudeContent = await fs.readFile(claudePath, 'utf-8');
+        assert.match(agentsContent, /slim guidance is narrowing-first/);
+        assert.match(agentsContent, /Query-time runtime closure is graph-only/);
         assert.match(agentsContent, /~\/\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
         assert.match(claudeContent, /~\/\.agents\/skills\/gitnexus\/gitnexus-exploring\/SKILL\.md/);
         assert.doesNotMatch(agentsContent, /## Unity Runtime Process 真理源/);
         assert.doesNotMatch(claudeContent, /## Unity Runtime Process 真理源/);
+        assert.doesNotMatch(agentsContent, /## Dev Workflow \(Source Build\)/);
+        assert.doesNotMatch(claudeContent, /## Dev Workflow \(Source Build\)/);
         assert.equal(agentsContent, claudeContent, 'AGENTS.md and CLAUDE.md should stay content-identical');
         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-runtime-summary.js

@@ -4,6 +4,7 @@ export function toPipelineRuntimeSummary(input) {
         communityResult: input.communityResult,
         processResult: input.processResult,
         unityResult: input.unityResult,
+        unityRuleBindingResult: input.unityRuleBindingResult,
         scopeDiagnostics: input.scopeDiagnostics,
         csharpPreprocDiagnostics: input.csharpPreprocDiagnostics,
     };

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

@@ -7,6 +7,7 @@ test('toPipelineRuntimeSummary drops graph reference and preserves reporting fie
         communityResult: { stats: { totalCommunities: 3 } },
         processResult: { stats: { totalProcesses: 2 } },
         unityResult: { diagnostics: ['scanContext: scripts=1'] },
+        unityRuleBindingResult: { edgesInjected: 1, ruleResults: [], diagnostics: { summary: [] } },
         csharpPreprocDiagnostics: {
             enabled: true,
             defineSymbolCount: 2,
@@ -20,5 +21,6 @@ test('toPipelineRuntimeSummary drops graph reference and preserves reporting fie
     assert.equal('graph' in out, false);
     assert.equal(out.totalFileCount, 12);
     assert.equal(out.communityResult?.stats.totalCommunities, 3);
+    assert.equal(out.unityRuleBindingResult?.edgesInjected, 1);
     assert.equal(out.csharpPreprocDiagnostics?.normalizedFiles, 1);
 });

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

@@ -1,4 +1,5 @@
 import type { CSharpPreprocDiagnostics } from '../types/pipeline.js';
+import type { UnityRuntimeBindingResult } from '../core/ingestion/unity-runtime-binding-rules.js';
 export interface FallbackInsertStats {
     attempted: number;
     succeeded: number;
@@ -6,5 +7,6 @@ export interface FallbackInsertStats {
 }
 export declare function formatCSharpPreprocDiagnosticsSummary(diagnostics: CSharpPreprocDiagnostics | undefined, previewLimit?: number): string[];
 export declare function formatUnityDiagnosticsSummary(diagnostics: string[] | undefined, previewLimit?: number): string[];
+export declare function formatUnityRuleBindingSummary(result: UnityRuntimeBindingResult | 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

@@ -32,6 +32,30 @@ export function formatUnityDiagnosticsSummary(diagnostics, previewLimit = 3) {
     }
     return lines;
 }
+export function formatUnityRuleBindingSummary(result, previewLimit = 3) {
+    if (!result)
+        return [];
+    const diagnostics = result.diagnostics;
+    const lines = ['Unity Rule Binding Diagnostics:'];
+    for (const message of diagnostics.summary) {
+        if (!message.startsWith('rule_binding.anomaly:')) {
+            lines.push(`- ${message}`);
+        }
+    }
+    const anomalies = diagnostics.anomalies;
+    if (anomalies.length === 0) {
+        return lines;
+    }
+    lines.push(`- rule_binding.anomalies: count=${anomalies.length}`);
+    const limit = previewLimit > 0 ? previewLimit : anomalies.length;
+    for (const message of anomalies.slice(0, limit)) {
+        lines.push(`- rule_binding.anomaly: ${message}`);
+    }
+    if (anomalies.length > limit) {
+        lines.push(`- rule_binding.anomaly: ... ${anomalies.length - limit} more`);
+    }
+    return lines;
+}
 export function formatFallbackSummary(warnings, stats, previewLimit = 5) {
     if (!warnings || warnings.length === 0) {
         return [];

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, resolveFallbackStats } from './analyze-summary.js';
+import { formatFallbackSummary, formatUnityDiagnosticsSummary, formatUnityRuleBindingSummary, resolveFallbackStats, } from './analyze-summary.js';
 test('formatUnityDiagnosticsSummary returns empty when diagnostics are missing', () => {
     const lines = formatUnityDiagnosticsSummary([]);
     assert.deepEqual(lines, []);
@@ -29,6 +29,70 @@ test('formatUnityDiagnosticsSummary truncates output after max preview items', (
         '... 1 more',
     ]);
 });
+test('formatUnityRuleBindingSummary renders diagnostics and agent report status', () => {
+    const lines = formatUnityRuleBindingSummary({
+        edgesInjected: 3,
+        ruleResults: [{ ruleId: 'unity.global-init', edgesInjected: 3 }],
+        diagnostics: {
+            rulesEvaluated: 1,
+            bindingsEvaluated: 1,
+            bindingsByKind: { method_triggers_scene_load: 1 },
+            methodLookupCalls: 5,
+            methodLookupCacheHits: 4,
+            sceneRuntimeTraversalCalls: 3,
+            sceneRuntimeTraversalCacheHits: 2,
+            sceneRuntimeResourcesVisited: 6,
+            anomalies: [],
+            shouldAgentReport: false,
+            agentReportReason: 'no anomalies detected',
+            summary: [
+                'rule_binding.summary: rules=1, bindings=1, edges=3',
+                'rule_binding.lookup: method_calls=5, cache_hits=4',
+                'rule_binding.agent_report: should_report=false reason="no anomalies detected"',
+            ],
+        },
+    });
+    assert.deepEqual(lines, [
+        'Unity Rule Binding Diagnostics:',
+        '- rule_binding.summary: rules=1, bindings=1, edges=3',
+        '- rule_binding.lookup: method_calls=5, cache_hits=4',
+        '- rule_binding.agent_report: should_report=false reason="no anomalies detected"',
+    ]);
+});
+test('formatUnityRuleBindingSummary renders anomaly preview', () => {
+    const lines = formatUnityRuleBindingSummary({
+        edgesInjected: 0,
+        ruleResults: [],
+        diagnostics: {
+            rulesEvaluated: 1,
+            bindingsEvaluated: 1,
+            bindingsByKind: { method_triggers_scene_load: 1 },
+            methodLookupCalls: 0,
+            methodLookupCacheHits: 0,
+            sceneRuntimeTraversalCalls: 0,
+            sceneRuntimeTraversalCacheHits: 0,
+            sceneRuntimeResourcesVisited: 0,
+            anomalies: [
+                'rule=unity.global-init: scene "Global" not found in File(.unity) index',
+                'rule=unity.global-init: method_triggers_scene_load missing host_class_pattern, loader_methods, or scene_name',
+            ],
+            shouldAgentReport: true,
+            agentReportReason: 'rule-binding anomalies detected',
+            summary: [
+                'rule_binding.summary: rules=1, bindings=1, edges=0',
+                'rule_binding.agent_report: should_report=true reason="rule-binding anomalies detected"',
+            ],
+        },
+    }, 1);
+    assert.deepEqual(lines, [
+        'Unity Rule Binding Diagnostics:',
+        '- rule_binding.summary: rules=1, bindings=1, edges=0',
+        '- rule_binding.agent_report: should_report=true reason="rule-binding anomalies detected"',
+        '- rule_binding.anomalies: count=2',
+        '- rule_binding.anomaly: rule=unity.global-init: scene "Global" not found in File(.unity) index',
+        '- rule_binding.anomaly: ... 1 more',
+    ]);
+});
 test('formatFallbackSummary returns empty when no warnings exist', () => {
     const lines = formatFallbackSummary([], {
         attempted: 0,

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 { formatCSharpPreprocDiagnosticsSummary, formatFallbackSummary, formatUnityDiagnosticsSummary, resolveFallbackStats } from './analyze-summary.js';
+import { formatCSharpPreprocDiagnosticsSummary, formatFallbackSummary, formatUnityDiagnosticsSummary, formatUnityRuleBindingSummary, resolveFallbackStats, } from './analyze-summary.js';
 import { resolveChildProcessExit } from './exit-code.js';
 import { toPipelineRuntimeSummary } from './analyze-runtime-summary.js';
 import { enforceSyncManifestConsistency, resolveScopeManifestForAnalyze } from './sync-manifest.js';
@@ -444,6 +444,10 @@ export const analyzeCommand = async (inputPath, options) => {
     for (const line of unitySummaryLines) {
         console.log(`  ${line}`);
     }
+    const unityRuleBindingSummaryLines = formatUnityRuleBindingSummary(pipelineRuntime.unityRuleBindingResult);
+    for (const line of unityRuleBindingSummaryLines) {
+        console.log(`  ${line}`);
+    }
     const csharpPreprocSummaryLines = formatCSharpPreprocDiagnosticsSummary(pipelineRuntime.csharpPreprocDiagnostics);
     for (const line of csharpPreprocSummaryLines) {
         console.log(`  ${line}`);

package/dist/cli/benchmark-agent-safe-query-context.d.ts

@@ -0,0 +1,20 @@
+import { runAnalyze } from '../benchmark/analyze-runner.js';
+import { runAgentSafeQueryContextBenchmark, writeAgentSafeQueryContextReports, type AgentSafeQueryContextBenchmarkReport } from '../benchmark/agent-safe-query-context/report.js';
+import type { AgentSafeBenchmarkSuite } from '../benchmark/agent-safe-query-context/types.js';
+export declare function benchmarkAgentSafeQueryContextCommand(dataset: string, options: {
+    repo?: string;
+    repoAlias?: string;
+    targetPath?: string;
+    reportDir?: string;
+    subagentRunsDir?: string;
+    extensions?: string;
+    scopeManifest?: string;
+    scopePrefix?: string[];
+    skipAnalyze?: boolean;
+}, deps?: {
+    loadSuite?: (root: string) => Promise<AgentSafeBenchmarkSuite>;
+    runBenchmark?: typeof runAgentSafeQueryContextBenchmark;
+    writeReports?: typeof writeAgentSafeQueryContextReports;
+    writeLine?: (line: string) => void;
+    analyze?: typeof runAnalyze;
+}): Promise<AgentSafeQueryContextBenchmarkReport>;

package/dist/cli/benchmark-agent-safe-query-context.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import { runAnalyze } from '../benchmark/analyze-runner.js';
+import { loadAgentSafeQueryContextSuite } from '../benchmark/agent-safe-query-context/io.js';
+import { runAgentSafeQueryContextBenchmark, writeAgentSafeQueryContextReports, } from '../benchmark/agent-safe-query-context/report.js';
+export async function benchmarkAgentSafeQueryContextCommand(dataset, options, deps) {
+    const loadSuite = deps?.loadSuite || loadAgentSafeQueryContextSuite;
+    const runBenchmark = deps?.runBenchmark || runAgentSafeQueryContextBenchmark;
+    const writeReports = deps?.writeReports || writeAgentSafeQueryContextReports;
+    const writeLine = deps?.writeLine || ((line) => process.stderr.write(`${line}\n`));
+    const analyze = deps?.analyze || runAnalyze;
+    const reportDir = path.resolve(options.reportDir || '.gitnexus/benchmark-agent-safe-query-context');
+    if (!(options.skipAnalyze ?? false)) {
+        if (!options.targetPath) {
+            throw new Error('targetPath is required unless skipAnalyze is true');
+        }
+        await analyze(path.resolve(options.targetPath), {
+            extensions: options.extensions,
+            repoAlias: options.repoAlias,
+            scopeManifest: options.scopeManifest,
+            scopePrefix: options.scopePrefix,
+        });
+    }
+    const suite = await loadSuite(path.resolve(dataset));
+    const report = await runBenchmark(suite, {
+        repo: options.repo || options.repoAlias || (options.targetPath ? path.basename(path.resolve(options.targetPath)) : undefined),
+        subagentRunsDir: options.subagentRunsDir ? path.resolve(options.subagentRunsDir) : undefined,
+    });
+    await writeReports(reportDir, report);
+    writeLine(`${report.pass ? 'PASS' : 'FAIL'}`);
+    for (const key of ['weapon_powerup', 'reload']) {
+        const row = report.workflow_replay_slim[key];
+        writeLine(`${key}: guid_invariance_pass=${row.guid_invariance_pass}, live_tool_evidence_pass=${row.live_tool_evidence_pass}, freeze_ready=${row.freeze_ready}, confirmed_chain_steps=${row.confirmed_chain.steps.length}, placeholder_leak_detected=${row.placeholder_leak_detected}, heuristic_top_summary_detected=${row.heuristic_top_summary_detected}`);
+    }
+    writeLine(`Report: ${reportDir}`);
+    if (!report.pass) {
+        process.exitCode = 1;
+    }
+    return report;
+}

package/dist/cli/benchmark-agent-safe-query-context.test.d.ts

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

package/dist/cli/benchmark-agent-safe-query-context.test.js

@@ -0,0 +1,271 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { benchmarkAgentSafeQueryContextCommand } from './benchmark-agent-safe-query-context.js';
+test('benchmark-agent-safe-query-context runs suite loader, benchmark, and report writer', async () => {
+    const output = [];
+    const calls = [];
+    const report = await benchmarkAgentSafeQueryContextCommand('../benchmarks/agent-safe-query-context/neonspark-v1', {
+        repo: 'neonspark-core',
+        reportDir: '.gitnexus/benchmark-agent-safe-query-context-test',
+        subagentRunsDir: '.gitnexus/subagent-runs',
+        skipAnalyze: true,
+    }, {
+        loadSuite: async () => ({
+            thresholds: {
+                workflowReplay: { maxSteps: 5 },
+                tokenReduction: { weapon_powerup: 0.5, reload: 0.4 },
+            },
+            cases: {
+                weapon_powerup: {
+                    label: 'weapon_powerup',
+                    start_query: 'weapon powerup equip chain',
+                    retry_query: 'retry',
+                    proof_contexts: ['WeaponPowerUp'],
+                    proof_cypher: 'MATCH () RETURN 1',
+                    tool_plan: [],
+                    live_task: {
+                        objective: 'Investigate WeaponPowerUp from the provided asset seed.',
+                        symbol_seed: 'WeaponPowerUp',
+                        resource_seed: 'Assets/NEON/DataAssets/Powerups/1_newWeapon/0_pick/法器_Orb/1_weapon_orb_key.asset',
+                    },
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/DataAssets/Powerups/1_newWeapon/0_pick/法器_Orb/1_weapon_orb_key.asset',
+                        symbol_anchor: 'WeaponPowerUp',
+                        proof_edges: ['HoldPickup -> WeaponPowerUp.PickItUp'],
+                        closure_status: 'not_verified_full',
+                    },
+                },
+                reload: {
+                    label: 'reload',
+                    start_query: 'reload getvalue checkreload',
+                    retry_query: 'retry',
+                    proof_contexts: ['ReloadBase'],
+                    proof_cypher: 'MATCH () RETURN 1',
+                    tool_plan: [],
+                    live_task: {
+                        objective: 'Investigate ReloadBase from the provided graph seed.',
+                        symbol_seed: 'ReloadBase',
+                        resource_seed: 'Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset',
+                    },
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset',
+                        symbol_anchor: 'ReloadBase',
+                        proof_edge: 'ReloadBase.GetValue -> ReloadBase.CheckReload',
+                        closure_status: 'not_verified_full',
+                    },
+                },
+            },
+        }),
+        runBenchmark: async (_suite, options) => {
+            calls.push({ repo: options.repo });
+            const workflowReplayCases = {
+                weapon_powerup: {
+                    steps: [],
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/DataAssets/Powerups/1_newWeapon/0_pick/法器_Orb/1_weapon_orb_key.asset',
+                        symbol_anchor: 'WeaponPowerUp',
+                        proof_edges: ['HoldPickup -> WeaponPowerUp.PickItUp'],
+                        closure_status: 'not_verified_full',
+                    },
+                    normalized_tuple_pass: true,
+                    evidence_validation_pass: true,
+                    failure_class: undefined,
+                    semantic_tuple_pass: true,
+                    anchor_top1_pass: true,
+                    recommended_follow_up_hit: true,
+                    post_narrowing_anchor_pass: true,
+                    post_narrowing_follow_up_hit: true,
+                    guid_invariance_pass: true,
+                    base: {
+                        primary_candidate: 'WeaponPowerUp',
+                        recommended_follow_up: 'resource_path_prefix=Assets/NEON/DataAssets/Powerups/1_newWeapon/0_pick/法器_Orb/1_weapon_orb_key.asset',
+                    },
+                    guid_variant: {
+                        primary_candidate: 'WeaponPowerUp',
+                        recommended_follow_up: 'resource_path_prefix=Assets/NEON/DataAssets/Powerups/1_newWeapon/0_pick/法器_Orb/1_weapon_orb_key.asset',
+                    },
+                    confirmed_chain: { steps: ['HoldPickup -> PickItUp'] },
+                    live_tool_evidence_pass: true,
+                    freeze_ready: true,
+                    tier_envelope: {
+                        facts_present: true,
+                        closure_present: true,
+                        clues_present: true,
+                        semantic_order_pass: true,
+                        summary_source: 'facts',
+                    },
+                    ambiguity_detour_count: 0,
+                    placeholder_leak_detected: false,
+                    heuristic_top_summary_detected: false,
+                    tool_calls_to_completion: 1,
+                    tokens_to_completion: 1,
+                    retry_breakdown: { query_retry_count: 0, context_retry_count: 0, cypher_retry_count: 0 },
+                    stop_reason: 'semantic_tuple_satisfied',
+                },
+                reload: {
+                    steps: [],
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset',
+                        symbol_anchor: 'ReloadBase',
+                        proof_edge: 'ReloadBase.GetValue -> ReloadBase.CheckReload',
+                        closure_status: 'not_verified_full',
+                    },
+                    normalized_tuple_pass: true,
+                    evidence_validation_pass: true,
+                    failure_class: undefined,
+                    semantic_tuple_pass: true,
+                    anchor_top1_pass: true,
+                    recommended_follow_up_hit: true,
+                    post_narrowing_anchor_pass: true,
+                    post_narrowing_follow_up_hit: true,
+                    guid_invariance_pass: true,
+                    base: {
+                        primary_candidate: 'ReloadBase',
+                        recommended_follow_up: 'resource_path_prefix=Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset',
+                    },
+                    guid_variant: {
+                        primary_candidate: 'ReloadBase',
+                        recommended_follow_up: 'resource_path_prefix=Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset',
+                    },
+                    confirmed_chain: { steps: ['GetValue -> CheckReload'] },
+                    live_tool_evidence_pass: true,
+                    freeze_ready: true,
+                    tier_envelope: {
+                        facts_present: true,
+                        closure_present: true,
+                        clues_present: true,
+                        semantic_order_pass: true,
+                        summary_source: 'facts',
+                    },
+                    ambiguity_detour_count: 0,
+                    placeholder_leak_detected: false,
+                    heuristic_top_summary_detected: false,
+                    tool_calls_to_completion: 1,
+                    tokens_to_completion: 1,
+                    retry_breakdown: { query_retry_count: 0, context_retry_count: 0, cypher_retry_count: 0 },
+                    stop_reason: 'semantic_tuple_satisfied',
+                },
+            };
+            const sameScriptCases = {
+                weapon_powerup: {
+                    tool_plan: [],
+                    steps: [],
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/DataAssets/Powerups/1_newWeapon/0_pick/法器_Orb/1_weapon_orb_key.asset',
+                        symbol_anchor: 'WeaponPowerUp',
+                        proof_edges: ['HoldPickup -> WeaponPowerUp.PickItUp'],
+                        closure_status: 'not_verified_full',
+                    },
+                    semantic_tuple_pass: true,
+                    tool_calls_to_completion: 1,
+                    tokens_to_completion: 1,
+                },
+                reload: {
+                    tool_plan: [],
+                    steps: [],
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset',
+                        symbol_anchor: 'ReloadBase',
+                        proof_edge: 'ReloadBase.GetValue -> ReloadBase.CheckReload',
+                        closure_status: 'not_verified_full',
+                    },
+                    semantic_tuple_pass: true,
+                    tool_calls_to_completion: 1,
+                    tokens_to_completion: 1,
+                },
+            };
+            const subagentLive = {
+                weapon_powerup: {
+                    steps: [],
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/DataAssets/Powerups/1_newWeapon/0_pick/法器_Orb/1_weapon_orb_key.asset',
+                        symbol_anchor: 'WeaponPowerUp',
+                        proof_edges: ['HoldPickup -> WeaponPowerUp.PickItUp'],
+                        closure_status: 'not_verified_full',
+                    },
+                    normalized_tuple_pass: true,
+                    evidence_validation_pass: true,
+                    failure_class: undefined,
+                    semantic_tuple_pass: true,
+                    tool_calls_to_completion: 1,
+                    tokens_to_completion: 1,
+                    stop_reason: 'semantic_tuple_satisfied',
+                    prompt: 'Use only telemetry-tool.js\nFinal JSON schema:',
+                    prompt_path: '/tmp/prompt.txt',
+                    result_path: '/tmp/result.json',
+                    telemetry_path: '/tmp/telemetry.jsonl',
+                    final_result: {},
+                },
+                reload: {
+                    steps: [],
+                    semantic_tuple: {
+                        resource_anchor: 'Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset',
+                        symbol_anchor: 'ReloadBase',
+                        proof_edge: 'ReloadBase.GetValue -> ReloadBase.CheckReload',
+                        closure_status: 'not_verified_full',
+                    },
+                    normalized_tuple_pass: true,
+                    evidence_validation_pass: true,
+                    failure_class: undefined,
+                    semantic_tuple_pass: true,
+                    tool_calls_to_completion: 1,
+                    tokens_to_completion: 1,
+                    stop_reason: 'semantic_tuple_satisfied',
+                    prompt: 'Use only telemetry-tool.js\nFinal JSON schema:',
+                    prompt_path: '/tmp/prompt.txt',
+                    result_path: '/tmp/result.json',
+                    telemetry_path: '/tmp/telemetry.jsonl',
+                    final_result: {},
+                },
+            };
+            return {
+                generatedAt: '2026-04-08T00:00:00.000Z',
+                workflow_replay_full: workflowReplayCases,
+                workflow_replay_slim: workflowReplayCases,
+                same_script_full: sameScriptCases,
+                same_script_slim: sameScriptCases,
+                cases: subagentLive,
+                same_script: {
+                    tool_plan: { weapon_powerup: [], reload: [] },
+                    cases: sameScriptCases,
+                },
+                subagent_live: subagentLive,
+                acceptance: { pass: true, cases: { weapon_powerup: true, reload: true } },
+                pass: true,
+                semantic_equivalence: { pass: false, cases: { weapon_powerup: false, reload: false } },
+                token_summary: {
+                    weapon_powerup: { before: 1, after: 1, saved: 0, reduction: 0 },
+                    reload: { before: 1, after: 1, saved: 0, reduction: 0 },
+                },
+                call_summary: {
+                    weapon_powerup: { before: 1, after: 1, saved: 0 },
+                    reload: { before: 1, after: 1, saved: 0 },
+                },
+            };
+        },
+        writeReports: async () => { },
+        writeLine: (line) => output.push(line),
+        analyze: async () => ({ stdout: '', stderr: '' }),
+    });
+    assert.equal(calls[0].repo, 'neonspark-core');
+    assert.ok(output.some((line) => line.includes('PASS')));
+    assert.ok(output.some((line) => line.includes('weapon_powerup: guid_invariance_pass=true, live_tool_evidence_pass=true, freeze_ready')));
+    assert.ok(output.some((line) => line.includes('Report:')));
+    assert.equal(report.workflow_replay_slim.weapon_powerup.placeholder_leak_detected, false);
+    assert.equal(report.workflow_replay_slim.weapon_powerup.heuristic_top_summary_detected, false);
+});
+test('runtime retrieval contract docs remove heuristic mode and pin full as debug-only', async () => {
+    const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+    const docPaths = [
+        'gitnexus/src/mcp/tools.ts',
+    ].map((relativePath) => path.join(repoRoot, relativePath));
+    const text = (await Promise.all(docPaths.map((filePath) => fs.readFile(filePath, 'utf-8')))).join('\n');
+    assert.ok(text.includes('discovery -> seed narrowing -> closure verification'));
+    assert.ok(!text.includes('resource_heuristic'));
+    assert.ok(text.includes('response_profile=slim is the default and sufficient'));
+    assert.ok(text.includes('response_profile=full is for debugging'));
+    assert.ok(text.includes('strong graph hops can coexist with failed closure'));
+});

package/dist/cli/benchmark.d.ts

@@ -0,0 +1,29 @@
+export interface BenchmarkCommandOptions {
+    repo?: string;
+    reportDir?: string;
+    recordsPath?: string;
+    casesPath?: string;
+}
+export declare function benchmarkCommand(suite: string, options?: BenchmarkCommandOptions): Promise<{
+    artifactPath?: string;
+    indexPath?: string;
+    sha256?: string;
+    comparisonPath?: string;
+    summaryPath?: string;
+    provenanceArtifactPath?: string;
+    provenanceIndexPath?: string;
+}>;
+export declare function benchmarkSuiteCommand(suite: string, options: {
+    repo?: string;
+    reportDir?: string;
+    recordsPath?: string;
+    casesPath?: string;
+}): Promise<{
+    artifactPath?: string;
+    indexPath?: string;
+    sha256?: string;
+    comparisonPath?: string;
+    summaryPath?: string;
+    provenanceArtifactPath?: string;
+    provenanceIndexPath?: string;
+}>;