vgxness 1.20.8 → 1.20.9

package/dist/application/code-context/code-context-service.js

@@ -0,0 +1,226 @@
+import { spawnSync } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { codeContextProviderCommandSafety, codeContextSafety, } from '../../domain/code-context/schema.js';
+import { codeContextProviderDefinitions, providerIndexStatus, providerReportPath } from './providers/status-probes.js';
+const defaultTimeoutMs = 1_000;
+const defaultMaxBytes = 4_096;
+const maxTimeoutMs = 60_000;
+const maxMaxBytes = 1_048_576;
+export class CodeContextService {
+    commandRunner;
+    commandEnv;
+    constructor(options = {}) {
+        this.commandRunner = options.commandRunner ?? runBoundedCommand;
+        this.commandEnv = options.commandEnv;
+    }
+    getStatus(input) {
+        const workspace = normalizeWorkspaceRoot(input.workspaceRoot);
+        if (!workspace.ok)
+            return workspace;
+        const workspaceRoot = workspace.value;
+        const timeoutMs = boundedTimeoutMs(input.timeoutMs);
+        const maxBytes = boundedMaxBytes(input.maxBytes);
+        const providerEntries = codeContextProviderDefinitions.map((provider) => {
+            const commandResult = this.commandRunner(this.withCommandEnv({ command: provider.command, args: provider.versionArgs, cwd: workspaceRoot, timeoutMs, maxBytes }));
+            const available = commandResult.ok && commandResult.exitCode === 0;
+            const index = providerIndexStatus(workspaceRoot, provider.indexRelativePath);
+            const diagnostics = available ? ['Provider command was found through a bounded read-only version probe.'] : ['Provider command is unavailable or version probe failed.'];
+            if (commandResult.truncated === true)
+                diagnostics.push('Provider version probe output was truncated at the bounded output cap.');
+            if (index.present)
+                diagnostics.push('Local graph index was detected by filesystem inspection only.');
+            const reportPath = providerReportPath(workspaceRoot, provider.reportRelativePath);
+            const status = {
+                provider: provider.id,
+                available,
+                ...(available ? { version: firstLine(commandResult.stdout) } : {}),
+                index,
+                setupGuidance: [...provider.setupGuidance],
+                diagnostics,
+            };
+            if (reportPath !== undefined)
+                status.reportPath = reportPath;
+            return [provider.id, status];
+        });
+        const providers = Object.fromEntries(providerEntries);
+        const availableCount = Object.values(providers).filter((provider) => provider.available).length;
+        const overallStatus = availableCount === 0 ? 'unavailable' : availableCount === providerEntries.length ? 'available' : 'partial';
+        return {
+            ok: true,
+            value: {
+                kind: 'code-context-status',
+                version: 1,
+                workspaceRoot,
+                overallStatus,
+                providers,
+                safety: { ...codeContextSafety },
+                summary: `[read-only] Code-context providers: ${overallStatus}. No tools were installed, no indexes were initialized, and no provider config was written.`,
+            },
+        };
+    }
+    query(input) {
+        const workspace = normalizeWorkspaceRoot(input.workspaceRoot);
+        if (!workspace.ok)
+            return workspace;
+        const workspaceRoot = workspace.value;
+        if (input.question.trim().length === 0)
+            return { ok: false, error: { code: 'invalid-question', message: 'question must not be empty.' } };
+        const mode = input.mode ?? 'overview';
+        const provider = selectProvider(input.provider ?? 'auto', mode);
+        const maxBytes = boundedMaxBytes(input.maxBytes);
+        const timeoutMs = boundedTimeoutMs(input.timeoutMs);
+        const status = this.getStatus({ workspaceRoot, timeoutMs, maxBytes });
+        if (!status.ok)
+            return status;
+        const providerStatus = status.value.providers[provider];
+        const command = commandFor(provider);
+        const args = queryArgs(provider, mode, input.question);
+        if (!providerStatus.available) {
+            return {
+                ok: true,
+                value: {
+                    kind: 'code-context-query',
+                    version: 1,
+                    workspaceRoot,
+                    provider,
+                    mode,
+                    question: input.question,
+                    status: 'provider-unavailable',
+                    summary: `[read-only] ${providerLabel(provider)} is unavailable. No install, init, hook, provider config, or index write was attempted.`,
+                    command: { command, args },
+                    setupGuidance: [...providerStatus.setupGuidance],
+                    diagnostics: [...providerStatus.diagnostics],
+                    safety: { ...codeContextSafety },
+                },
+            };
+        }
+        const commandResult = this.commandRunner(this.withCommandEnv({ command, args, cwd: workspaceRoot, timeoutMs, maxBytes }));
+        const ok = commandResult.ok && commandResult.exitCode === 0;
+        const output = firstNonEmpty(commandResult.stdout, commandResult.stderr);
+        const diagnostics = ok ? ['Provider query completed through a bounded command.'] : ['Provider query failed through a bounded command.'];
+        diagnostics.push(`Command bounds applied: timeoutMs=${timeoutMs}, maxBytes=${maxBytes}.`);
+        if (commandResult.truncated === true)
+            diagnostics.push('Provider output was truncated at the bounded output cap.');
+        return {
+            ok: true,
+            value: {
+                kind: 'code-context-query',
+                version: 1,
+                workspaceRoot,
+                provider,
+                mode,
+                question: input.question,
+                status: ok ? 'answered' : 'error',
+                summary: output || `${providerLabel(provider)} returned no output for the requested query.`,
+                command: { command, args },
+                setupGuidance: [...providerStatus.setupGuidance],
+                diagnostics,
+                safety: { ...codeContextProviderCommandSafety },
+            },
+        };
+    }
+    getSetupPlan(input) {
+        const workspace = normalizeWorkspaceRoot(input.workspaceRoot);
+        if (!workspace.ok)
+            return workspace;
+        const workspaceRoot = workspace.value;
+        return {
+            ok: true,
+            value: {
+                kind: 'code-context-setup-plan',
+                version: 1,
+                workspaceRoot,
+                recommendedCommands: [
+                    'codegraph init # optional: create/update CodeGraph index outside VGXNESS',
+                    'graphify --path . --output graphify-out # optional: create/update Graphify graph outside VGXNESS',
+                ],
+                safety: { ...codeContextSafety },
+                summary: '[read-only] Advisory plan only. VGXNESS does not install packages, initialize indexes, register external MCP servers, or write provider config.',
+            },
+        };
+    }
+    withCommandEnv(request) {
+        return this.commandEnv === undefined ? request : { ...request, env: this.commandEnv };
+    }
+}
+function selectProvider(selection, mode) {
+    if (selection !== 'auto')
+        return selection;
+    return mode === 'architecture' || mode === 'overview' || mode === 'pr-impact' ? 'graphify' : 'codegraph';
+}
+function commandFor(provider) {
+    return provider === 'codegraph' ? 'codegraph' : 'graphify';
+}
+function providerLabel(provider) {
+    return provider === 'codegraph' ? 'CodeGraph' : 'Graphify';
+}
+function queryArgs(provider, mode, question) {
+    return provider === 'codegraph' ? [mode, question] : ['query', '--mode', mode, question];
+}
+function firstNonEmpty(...values) {
+    return values.find((value) => value.trim().length > 0)?.trim() ?? '';
+}
+function normalizeWorkspaceRoot(value) {
+    if (value.trim().length === 0)
+        return { ok: false, error: { code: 'invalid-workspace-root', message: 'workspaceRoot must not be empty.' } };
+    const resolved = isAbsolute(value) ? value : resolve(value);
+    try {
+        const canonical = realpathSync(resolved);
+        if (!statSync(canonical).isDirectory()) {
+            return { ok: false, error: { code: 'invalid-workspace-root', message: 'workspaceRoot must resolve to an existing directory.' } };
+        }
+        return { ok: true, value: canonical };
+    }
+    catch {
+        return { ok: false, error: { code: 'invalid-workspace-root', message: 'workspaceRoot must resolve to an existing directory.' } };
+    }
+}
+function firstLine(value) {
+    return value.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim() ?? '';
+}
+function runBoundedCommand(request) {
+    const options = {
+        cwd: request.cwd,
+        shell: false,
+        encoding: 'utf8',
+        timeout: request.timeoutMs,
+        maxBuffer: request.maxBytes,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...(request.env === undefined ? {} : { env: request.env }),
+    };
+    const executed = spawnSync(request.command, request.args, options);
+    const stdout = limitText(executed.stdout ?? '', request.maxBytes);
+    const stderr = limitText(executed.stderr ?? '', request.maxBytes);
+    const truncated = wasTruncated(executed.stdout ?? '', request.maxBytes) || wasTruncated(executed.stderr ?? '', request.maxBytes) || errorCode(executed.error) === 'ENOBUFS';
+    if (executed.error !== undefined) {
+        const errorText = [stderr, executed.error.message].filter((value) => value.trim().length > 0).join('\n');
+        return { ok: false, stdout, stderr: errorText, exitCode: executed.status, ...(truncated ? { truncated: true } : {}) };
+    }
+    return {
+        ok: executed.status === 0,
+        stdout,
+        stderr,
+        exitCode: executed.status,
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+function limitText(value, maxBytes) {
+    const buffer = Buffer.from(value, 'utf8');
+    if (buffer.byteLength <= maxBytes)
+        return value;
+    return buffer.subarray(0, maxBytes).toString('utf8');
+}
+function wasTruncated(value, maxBytes) {
+    return Buffer.from(value, 'utf8').byteLength > maxBytes;
+}
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === 'string' ? code : undefined;
+}
+function boundedTimeoutMs(value) {
+    return Math.min(value ?? defaultTimeoutMs, maxTimeoutMs);
+}
+function boundedMaxBytes(value) {
+    return Math.min(value ?? defaultMaxBytes, maxMaxBytes);
+}

package/dist/application/code-context/providers/status-probes.js

@@ -0,0 +1,34 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const codegraphProviderDefinition = {
+    id: 'codegraph',
+    command: 'codegraph',
+    versionArgs: ['--version'],
+    indexRelativePath: join('.codegraph', 'codegraph.db'),
+    setupGuidance: [
+        'Install CodeGraph explicitly if desired: npm install -g @colbymchenry/codegraph',
+        'Initialize only after approval: codegraph init',
+    ],
+};
+export const graphifyProviderDefinition = {
+    id: 'graphify',
+    command: 'graphify',
+    versionArgs: ['--version'],
+    indexRelativePath: join('graphify-out', 'graph.json'),
+    reportRelativePath: join('graphify-out', 'GRAPH_REPORT.md'),
+    setupGuidance: [
+        'Install Graphify explicitly if desired: pipx install graphifyy',
+        'Generate graph output only after approval: graphify <workspace>',
+    ],
+};
+export const codeContextProviderDefinitions = [codegraphProviderDefinition, graphifyProviderDefinition];
+export function providerIndexStatus(workspaceRoot, relativePath) {
+    const path = join(workspaceRoot, relativePath);
+    return { present: existsSync(path), path, freshness: 'unknown' };
+}
+export function providerReportPath(workspaceRoot, relativePath) {
+    if (relativePath === undefined)
+        return undefined;
+    const path = join(workspaceRoot, relativePath);
+    return existsSync(path) ? path : undefined;
+}

package/dist/domain/agents/canonical-agent-manifest.js

@@ -2,7 +2,7 @@ import { canonicalBehaviorContractVersion } from '../../behavior/behavior-contra
 export const canonicalDefaultAgentName = 'vgxness-manager';
 export const canonicalOpenCodeDefaultModel = 'openai/gpt-5.5';
 export const canonicalOpenCodeManagerReasoningEffort = 'high';
-export const canonicalPromptContractVersion = 23;
+export const canonicalPromptContractVersion = 24;
 export const canonicalSddSubagentNames = [
     'vgxness-sdd-explore',
     'vgxness-sdd-propose',
@@ -170,6 +170,7 @@ export function createCanonicalOpenCodeSddMcpToolPermissions() {
         vgxness_run_resume_gate: 'allow',
         vgxness_provider_status: 'allow',
         vgxness_provider_doctor: 'allow',
+        vgxness_code_context_status: 'allow',
         vgxness_governance_report: 'allow',
     };
 }
@@ -214,7 +215,7 @@ SDD happens in OpenCode conversation + VGXNESS MCP/subagents. No terminal SDD ph
 ## MCP playbook
 - Start/resume/recover: call \`vgxness_resume_context\` first for generic resume/continue; pass \`explicitChange\` only for an exact user change. Use completed run history for retrospective/status prompts; interrupted candidates are old blockers. \`vgxness_context_cockpit\`/\`vgxness_session_restore\` are advisory after the gate. Do not infer a change from \`context_cockpit.memoryPreviews\`. Close with \`vgxness_session_close\` when session id exists.
 - Bounded resume/start hard stop: for generic "continue"/"sigamos"/"continuemos"/"resume development" without an explicit change, call \`vgxness_resume_context\` before any SDD continuation/status. \`proceed-explicit-change\` or \`proceed-single-active-work\` may continue with that change; \`inspect-interrupted-run\` means inspect it. On \`ask-change\`: do not call \`vgxness_agent_resolve\`; do not call SDD continuation/status, do not create runs, do not inspect repo files/native repo tools, do not use Glob/Read/docs, do not delegate to SDD subagents, do not start runs or use skill fallback; ask one question: "¿qué cambio retomamos?".
-- Project preparation: when the user wants to start a new project/product/app or only has an idea, run a preparation phase before implementation. Help crystallize the idea with concise questions/options for goals, users, scope, constraints, stack, repo/location, integrations, data, security, deliverables, milestones, success criteria, and docs/control artifacts. Propose lightweight control docs (PRD/requirements/design/tasks/roadmap) before coding when useful. If the UI/provider supports selectable options, present 2-4 clear options; otherwise use numbered choices and ask only for decisions that change the build path.
+- Project preparation: to start a new project/product/app or idea, clarify goals, users, scope, constraints, stack, repo/location, integrations, data, security, deliverables, milestones, success criteria and propose PRD/requirements/design/tasks/roadmap. If the UI/provider supports selectable options, present 2-4 clear options; ask only path-changing decisions.
 - Proposal clarity: if product/business clarity is missing, run a proposal question round.
 - SDD artifacts: guide with \`vgxness_sdd_next\`/\`vgxness_sdd_cockpit\`; bodies use memory-style API \`vgxness_memory_get\`/\`vgxness_memory_save\`/\`vgxness_memory_update\` + \`kind: "sdd-artifact"\`. Legacy aliases: \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`/\`vgxness_sdd_save_artifact\`. Summarize proposal draft then ask accept+continue. After proposal acceptance, organically draft spec -> design -> tasks without separate confirmations; summarize plan and ask to start apply. Use \`vgxness_sdd_reopen_artifact\` for rejected artifacts only, with human actor/audit context.
 - delegated phase subagent outputs: inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended); this is prompt guidance only, not runtime parsing/rejection.
@@ -225,7 +226,7 @@ SDD happens in OpenCode conversation + VGXNESS MCP/subagents. No terminal SDD ph
 - Active-work memory uses existing memory APIs only: \`active-work/{change}/summary\` (+others). No secrets or hidden reasoning. Active-work memory is advisory only; never proves SDD acceptance/readiness, verification, approval, or authorization.
 - Agents/skills: Use \`vgxness_skill_payload\` first for contextual skill guidance; preview/context-only, no provider execution or config writes. Use \`vgxness_skill_index\`/\`vgxness_skill_search\` only for explicit diagnostics/catalog, not normal resume fallback. Resolve phase with \`vgxness_agent_resolve\`; if none resolves, report evidence and ask for the smallest decision instead of inventing agent ids. \`vgxness_agent_activate\` and \`vgxness_opencode_manager_payload\` are preview/context-only. \`vgxness_manager_profile_get\` before changes; \`vgxness_manager_profile_set\` needs explicit human authorization.
 - Runs/recovery: \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\`; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\` (include \`explicitRequest\` only for exact human-requested one-off actions), close with \`vgxness_run_finalize\`. Unknown runId: \`vgxness_run_resume_candidates\`. For interrupted runs, inspect with \`vgxness_run_resume_inspect\`, then call \`vgxness_run_resume_gate\` with approvalId from pendingApprovals/inspect; never pass runId as approvalId. Follow safe \`recommendedActions[]\`. Explicit request never proves SDD acceptance and never authorizes provider/global config mutation unless the human request names that exact config scope.
-- Provider diagnostics: \`vgxness_provider_status\`/\`vgxness_provider_doctor\` read-only; report evidence limits; use status for configured/phase/next and doctor for OpenCode MCP/manager health.
+- Provider diagnostics: \`vgxness_provider_status\`/\`vgxness_provider_doctor\` read-only; report evidence limits; use status for configured/phase/next and doctor for OpenCode MCP/manager health. Code context: \`vgxness_code_context_status\` only. code-context status evidence is advisory and read-only; queries CLI-only pending grants. Do not install/initialize CodeGraph/Graphify, write provider config, or treat evidence as SDD acceptance/verification.
 
 ## Minimum flows
 - Organic SDD: propose -> save draft -> ask accept+continue. Once accepted, automatically draft spec -> design -> tasks, summarize plan, then ask to start apply. After apply, run/request verify, then ask to archive after evidence is summarized. Drafts stay unaccepted until human acceptance; never silently accept.
@@ -260,6 +261,7 @@ const registryManagerInstructionsV11 = [
     'Prefer payloadMode=compact for manager-facing status/context reads, SDD artifact reads/lists, and activation handoffs so the primary context stays clean; request payloadMode=verbose only when full artifact contents, provider payloads, or skill context are actually needed, preferably inside delegated phase subagents. Git/PR hygiene: never implement on main; sync main and create a topic branch/worktree before edits; preserve unrelated work; use conventional commits; link approved issues when repo policy requires them; include verification evidence. Estimate changed lines before PR: <=400 focused changed lines can be one PR; >400 lines or multiple review units should become stacked/chained PRs, or ask the user to choose a single PR with size exception vs stacked plan.',
     'MCP sdd_continue must not execute providers, create runs, mutate artifacts, write provider config/openspec, bypass human acceptance, or treat draft-run as apply-progress.',
     'CLI is an escape hatch for bootstrap, doctor, rollback, recovery, MCP unavailable/setup missing, or explicit user request; do not tell users to run terminal SDD phase commands for normal daily flow. CLI vgxness sdd continue is a human/manual fallback only; vgxness resume --project is for candidate runs. The removed experimental vgxness code runtime is not an SDD fallback.',
+    'Code context: use vgxness_code_context_status before relying on repository-intelligence providers. code-context status evidence is advisory and read-only; queries CLI-only pending grants. Do not install/initialize CodeGraph/Graphify, write provider config, or treat output as SDD acceptance/verification.',
     'OpenCode native/provider tools are governance-v1 audit-only/non-hard-blocking; report warnings, never say they are hard-blocked by config.',
 ].join(' ');
 const subagentData = {

package/dist/domain/code-context/schema.js

@@ -0,0 +1,20 @@
+export const codeContextProviderIds = ['codegraph', 'graphify'];
+export const codeContextProviderSelections = ['auto', 'codegraph', 'graphify'];
+export const codeContextModes = ['overview', 'architecture', 'debug', 'impact', 'affected-tests', 'verify', 'pr-impact'];
+export const codeContextSafety = {
+    readOnly: true,
+    writesFiles: false,
+    writesProviderConfig: false,
+    installsPackages: false,
+    initializesIndexes: false,
+    registersExternalMcp: false,
+    runsHooks: false,
+    executesProviderCommands: false,
+    externalProviderSideEffects: 'not-invoked',
+};
+export const codeContextProviderCommandSafety = {
+    ...codeContextSafety,
+    readOnly: false,
+    executesProviderCommands: true,
+    externalProviderSideEffects: 'unknown',
+};

package/dist/interfaces/cli/cli-help.js

@@ -17,7 +17,7 @@ Areas:
   setup rollback --backup <path> [--preview|--yes] [--json]
   setup status [--project <name>] [--scope project|personal] [--db <path>] [--json]
   doctor [--db <path>] [--project <name>] [--change <id>] [--timeout-ms <ms>] [--json]
-  verification plan --type docs-only|test-only|cli|mcp|sdd-storage|provider-setup|package-release|workflow-runs [--json]
+  verification plan --type docs-only|test-only|cli|mcp|sdd-storage|provider-setup|package-release|workflow-runs|code-context [--json]
   verification report save --project <name> --change <id> --file <report.json> [--db <path>] [--json]
   verification report get --project <name> --change <id> [--db <path>] [--json]
   Status answers "where am I?" with the human front-door cockpit.

package/dist/interfaces/cli/commands/code-context-dispatcher.js

@@ -0,0 +1,67 @@
+import { resolve } from 'node:path';
+import { CodeContextService } from '../../../application/code-context/code-context-service.js';
+import { codeContextModes, codeContextProviderSelections, codeContextSafety } from '../../../domain/code-context/schema.js';
+import { optionalNumberFlag, optionalStringFlag, requiredFlag } from '../cli-flags.js';
+import { okText, usageFailure } from '../cli-help.js';
+export function runCodeContextCommand(command, parsed, environment) {
+    const workspaceRoot = resolveWorkspaceRoot(optionalStringFlag(parsed.flags, 'workspace'), environment.cwd);
+    const service = new CodeContextService({ commandEnv: environment.env });
+    const timeout = optionalNumberFlag(parsed.flags, 'timeout-ms');
+    if (!timeout.ok)
+        return usageFailure(timeout.error.message);
+    const maxBytes = optionalNumberFlag(parsed.flags, 'max-bytes');
+    if (!maxBytes.ok)
+        return usageFailure(maxBytes.error.message);
+    const common = { workspaceRoot, ...(timeout.value !== undefined ? { timeoutMs: timeout.value } : {}), ...(maxBytes.value !== undefined ? { maxBytes: maxBytes.value } : {}) };
+    if (command === 'status') {
+        const result = service.getStatus(common);
+        if (!result.ok)
+            return usageFailure(result.error.message);
+        return parsed.flags.json === true ? json(result.value) : okText(`${result.value.summary}\n`);
+    }
+    if (command === 'query') {
+        const question = requiredFlag(parsed.flags, 'question');
+        if (!question.ok)
+            return usageFailure(question.error.message);
+        const provider = optionalStringFlag(parsed.flags, 'provider');
+        if (provider !== undefined && !codeContextProviderSelections.includes(provider))
+            return usageFailure('--provider must be auto, codegraph, or graphify');
+        const mode = optionalStringFlag(parsed.flags, 'mode');
+        if (mode !== undefined && !codeContextModes.includes(mode))
+            return usageFailure(`--mode must be ${codeContextModes.join(', ')}`);
+        const result = service.query({
+            ...common,
+            question: question.value,
+            ...(provider !== undefined ? { provider: provider } : {}),
+            ...(mode !== undefined ? { mode: mode } : {}),
+        });
+        if (!result.ok)
+            return usageFailure(result.error.message);
+        return parsed.flags.json === true ? json(result.value) : okText(`${result.value.summary}\n`);
+    }
+    if (command === 'setup') {
+        if (parsed.positionals[2] !== 'plan' || parsed.positionals.length !== 3)
+            return usageFailure('code-context setup requires the plan subcommand');
+        const result = service.getSetupPlan(common);
+        if (!result.ok)
+            return usageFailure(result.error.message);
+        return parsed.flags.json === true ? json(result.value) : okText(`${result.value.summary}\n${result.value.recommendedCommands.join('\n')}\n`);
+    }
+    const body = {
+        kind: 'code-context-setup-plan',
+        version: 1,
+        workspaceRoot,
+        recommendedCommands: ['codegraph init # optional: run manually outside VGXNESS', 'graphify --path . --output graphify-out # optional: run manually outside VGXNESS'],
+        safety: { ...codeContextSafety },
+        summary: '[read-only] Advisory plan only. VGXNESS does not install packages, initialize indexes, register external MCP servers, or write provider config.',
+    };
+    return parsed.flags.json === true ? json(body) : okText(`${body.summary}\n${body.recommendedCommands.join('\n')}\n`);
+}
+function resolveWorkspaceRoot(value, cwd) {
+    if (value === undefined)
+        return cwd;
+    return value.startsWith('/') ? value : resolve(cwd, value);
+}
+function json(value) {
+    return okText(`${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/interfaces/cli/commands/index.js

@@ -1,3 +1,4 @@
+export { runCodeContextCommand } from './code-context-dispatcher.js';
 export { runAgentCommand, runSkillCommand, runSubagentCommand } from './agent-skill-dispatcher.js';
 export { runDefaultInteractiveEntrypoint } from './interactive-entrypoint-dispatcher.js';
 export { runDoctorAliasCommand, runMcpDoctorCommand, runMcpDoctorOpenCodeCommand, runMcpInstallCommand, runMcpSetupCommand } from './mcp-dispatcher.js';

package/dist/interfaces/cli/dispatcher.js

@@ -5,7 +5,7 @@ import { runBootAgentSeedUpgrade } from '../../agents/boot-upgrade.js';
 import { databasePathFor, parseArgs, requiredFlag } from './cli-flags.js';
 import { okText, usageFailure, visibleHelpText } from './cli-help.js';
 import { openCliDatabase, resultFailure } from './cli-helpers.js';
-import { runAgentCommand, runApprovalsCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runHomeTuiCommand, runInitCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runProductNextCommand, runProductResumeCommand, runProductStatusCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupReinstallApplyCommand, runSetupRollbackCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
+import { runAgentCommand, runApprovalsCommand, runCodeContextCommand, runDefaultInteractiveEntrypoint, runDoctorAliasCommand, runHomeTuiCommand, runInitCommand, runMcpDoctorCommand, runMcpInstallCommand, runMcpSetupCommand, runMemoryCommand, runMemoryImportCommand, runOpenCodeCommand, runOrchestratorCommand, runPermissionsCommand, runProductNextCommand, runProductResumeCommand, runProductStatusCommand, runRunsCommand, runSddCommand, runSetupApplyCommand, runSetupLifecycleCommand, runSetupPlanCommand, runSetupReinstallApplyCommand, runSetupRollbackCommand, runSkillCommand, runSubagentCommand, runVerificationPlanCommand, runVerificationReportCommand, runWorkflowExecuteCommand, runWorkflowPreviewCommand, runWorkflowRunCommand, } from './commands/index.js';
 import { canRunInteractiveTui } from './tui/terminal-capabilities.js';
 const _promptBuffers = new WeakMap();
 const require = createRequire(import.meta.url);
@@ -35,6 +35,8 @@ export function dispatchCli(argv, environment) {
         return usageFailure(commandValidation.message);
     if (area === 'setup')
         return runSetupLifecycleCommand(parsed, environment);
+    if (area === 'code-context')
+        return runCodeContextCommand(command, parsed, environment);
     if (area === 'verification' && command === 'plan')
         return runVerificationPlanCommand(command, parsed);
     if (isWorkflowId(area) && command === 'preview')
@@ -235,6 +237,9 @@ function validateCommand(area, command) {
     if (area === 'opencode') {
         return command === 'preview' ? { ok: true } : { ok: false, message: `Unknown opencode command: ${command}` };
     }
+    if (area === 'code-context') {
+        return command === 'status' || command === 'query' || command === 'setup' ? { ok: true } : { ok: false, message: `Unknown code-context command: ${command}` };
+    }
     if (area === 'setup') {
         return command === 'status' || command === 'plan' || command === 'apply' || command === 'reinstall' || command === 'backup' || command === 'rollback'
             ? { ok: true }

package/dist/interfaces/mcp/contracts/code-context.js

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

package/dist/interfaces/mcp/control-plane/handlers/code-context.js

@@ -0,0 +1,7 @@
+import { errorEnvelope, successEnvelope } from '../../schema.js';
+export function codeContextStatusEnvelope(input, services) {
+    if (services.codeContext === undefined)
+        return errorEnvelope('validation_failed', 'Code-context service is not available', 'vgxness_code_context_status');
+    const result = services.codeContext.getStatus(input);
+    return result.ok ? successEnvelope('vgxness_code_context_status', result.value) : errorEnvelope('validation_failed', result.error.message, 'vgxness_code_context_status');
+}

package/dist/interfaces/mcp/control-plane.js

@@ -1,5 +1,6 @@
 import { OpenCodeHandoffPreviewService } from '../../adapters/opencode/install/opencode-handoff-preview.js';
 import { AgentActivationService } from '../../agents/agent-activation-service.js';
+import { CodeContextService } from '../../application/code-context/code-context-service.js';
 import { AgentRegistryService } from '../../agents/agent-registry-service.js';
 import { ManagerProfileOverlayService } from '../../agents/manager-profile-overlay-service.js';
 import { ManagerProfileOverlayRepository } from '../../agents/repositories/manager-profile-overlays.js';
@@ -18,6 +19,7 @@ import { SkillRegistryService } from '../../skills/skill-registry-service.js';
 import { SkillStatusService } from '../../skills/skill-status-service.js';
 import { VerificationPlanService } from '../../verification/index.js';
 import { agentActivateEnvelope, agentResolveEnvelope, managerProfileGetEnvelope, managerProfileSetEnvelope, opencodeHandoffPreviewEnvelope, opencodeManagerPayloadEnvelope, } from './control-plane/handlers/agents.js';
+import { codeContextStatusEnvelope } from './control-plane/handlers/code-context.js';
 import { contextCockpitEnvelope, resumeContextEnvelope } from './control-plane/handlers/context.js';
 import { memoryGetEnvelope, memorySaveEnvelope, memorySearchEnvelope, memoryUpdateEnvelope } from './control-plane/handlers/memory.js';
 import { providerChangePlanEnvelope, providerDoctorEnvelope, providerStatusEnvelope } from './control-plane/handlers/providers.js';
@@ -75,6 +77,8 @@ export function callVgxTool(call, services) {
             return sessionRestoreEnvelope(validated.input, services);
         case 'vgxness_context_cockpit':
             return contextCockpitEnvelope(validated.input, services);
+        case 'vgxness_code_context_status':
+            return codeContextStatusEnvelope(validated.input, services);
         case 'vgxness_resume_context':
             return resumeContextEnvelope(validated.input, services);
         case 'vgxness_agent_resolve':
@@ -218,6 +222,7 @@ function createServices(database) {
         opencodeHandoffPreview: new OpenCodeHandoffPreviewService({ managerPayload: opencodeManagerPayload, sdd, providerStatus }),
         activation: new AgentActivationService({ agents, managerProfiles, runs, opencodeManagerPayload }),
         runs,
+        codeContext: new CodeContextService(),
         providerStatus,
         providerDoctor,
         providerChangePlan: new ProviderChangePlanService({ providerStatus, providerDoctor }),

package/dist/interfaces/mcp/schema.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AGENTS_MCP_TOOL_INPUT_SCHEMAS, CONTEXT_MCP_TOOL_INPUT_SCHEMAS, GOVERNANCE_MCP_TOOL_INPUT_SCHEMAS, MEMORY_MCP_TOOL_INPUT_SCHEMAS, PROVIDERS_MCP_TOOL_INPUT_SCHEMAS, RUNS_MCP_TOOL_INPUT_SCHEMAS, SDD_MCP_TOOL_INPUT_SCHEMAS, SESSIONS_MCP_TOOL_INPUT_SCHEMAS, SKILLS_MCP_TOOL_INPUT_SCHEMAS, VERIFICATION_MCP_TOOL_INPUT_SCHEMAS, } from './schemas/inputs/index.js';
+import { AGENTS_MCP_TOOL_INPUT_SCHEMAS, CONTEXT_MCP_TOOL_INPUT_SCHEMAS, CODE_CONTEXT_MCP_TOOL_INPUT_SCHEMAS, GOVERNANCE_MCP_TOOL_INPUT_SCHEMAS, MEMORY_MCP_TOOL_INPUT_SCHEMAS, PROVIDERS_MCP_TOOL_INPUT_SCHEMAS, RUNS_MCP_TOOL_INPUT_SCHEMAS, SDD_MCP_TOOL_INPUT_SCHEMAS, SESSIONS_MCP_TOOL_INPUT_SCHEMAS, SKILLS_MCP_TOOL_INPUT_SCHEMAS, VERIFICATION_MCP_TOOL_INPUT_SCHEMAS, } from './schemas/inputs/index.js';
 import { buildProviderMcpToolOutputSchemas, buildSddMcpToolOutputSchemas } from './schemas/outputs/index.js';
 export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_sdd_status',
@@ -23,6 +23,7 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_session_close',
     'vgxness_session_restore',
     'vgxness_context_cockpit',
+    'vgxness_code_context_status',
     'vgxness_resume_context',
     'vgxness_agent_resolve',
     'vgxness_agent_activate',
@@ -86,6 +87,7 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'session_close',
     'session_restore',
     'context_cockpit',
+    'code_context_status',
     'resume_context',
     'agent_resolve',
     'agent_activate',
@@ -147,6 +149,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     ...MEMORY_MCP_TOOL_INPUT_SCHEMAS,
     ...SESSIONS_MCP_TOOL_INPUT_SCHEMAS,
     ...CONTEXT_MCP_TOOL_INPUT_SCHEMAS,
+    ...CODE_CONTEXT_MCP_TOOL_INPUT_SCHEMAS,
     ...AGENTS_MCP_TOOL_INPUT_SCHEMAS,
     ...SKILLS_MCP_TOOL_INPUT_SCHEMAS,
     ...RUNS_MCP_TOOL_INPUT_SCHEMAS,

package/dist/interfaces/mcp/schemas/inputs/code-context.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export const CODE_CONTEXT_MCP_TOOL_INPUT_SCHEMAS = {
+    vgxness_code_context_status: z
+        .object({
+        workspaceRoot: z.string().min(1),
+        timeoutMs: z.number().int().positive().optional(),
+        maxBytes: z.number().int().positive().optional(),
+    })
+        .passthrough(),
+};

package/dist/interfaces/mcp/schemas/inputs/index.js

@@ -1,5 +1,6 @@
 export { AGENTS_MCP_TOOL_INPUT_SCHEMAS } from './agents.js';
 export { CONTEXT_MCP_TOOL_INPUT_SCHEMAS } from './context.js';
+export { CODE_CONTEXT_MCP_TOOL_INPUT_SCHEMAS } from './code-context.js';
 export { GOVERNANCE_MCP_TOOL_INPUT_SCHEMAS } from './governance.js';
 export { MEMORY_MCP_TOOL_INPUT_SCHEMAS } from './memory.js';
 export { PROVIDERS_MCP_TOOL_INPUT_SCHEMAS } from './providers.js';

package/dist/interfaces/mcp/validation/code-context.js

@@ -0,0 +1,22 @@
+import { inputRecord, readNonEmptyString, validationFailure } from './common.js';
+export function validateCodeContextStatusInput(input, tool) {
+    const record = inputRecord(input, tool, ['workspaceRoot', 'timeoutMs', 'maxBytes']);
+    if (!record.ok)
+        return record;
+    const workspaceRoot = readNonEmptyString(record.value, 'workspaceRoot', tool);
+    if (!workspaceRoot.ok)
+        return workspaceRoot;
+    const result = { workspaceRoot: workspaceRoot.value };
+    const numeric = copyOptionalPositiveIntegers(result, record.value, tool, ['timeoutMs', 'maxBytes']);
+    return numeric.ok ? { ok: true, value: result } : numeric;
+}
+function copyOptionalPositiveIntegers(target, record, tool, fields) {
+    for (const field of fields) {
+        if (record[field] === undefined)
+            continue;
+        if (typeof record[field] !== 'number' || !Number.isSafeInteger(record[field]) || record[field] <= 0)
+            return validationFailure(`${field} must be a positive safe integer`, tool);
+        target[field] = record[field];
+    }
+    return { ok: true, value: undefined };
+}

package/dist/interfaces/mcp/validation.js

@@ -1,5 +1,6 @@
 import { isVgxMcpToolName } from './schema.js';
 import { validateAgentActivateInput, validateAgentResolveInput, validateManagerProfileGetInput, validateManagerProfileSetInput, validateOpenCodeHandoffPreviewInput, validateOpenCodeManagerPayloadInput, } from './validation/agents.js';
+import { validateCodeContextStatusInput } from './validation/code-context.js';
 import { asRecord, readString, toValidationResultFailure, validationFailure, validationSuccess } from './validation/common.js';
 import { validateGovernanceReportInput } from './validation/governance.js';
 import { validateMemoryGetInput, validateMemorySaveInput, validateMemorySearchInput, validateMemoryUpdateInput } from './validation/memory.js';
@@ -62,6 +63,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSessionRestoreInput(input, tool.value));
         case 'vgxness_context_cockpit':
             return validationSuccess(tool.value, validateContextCockpitInput(input, tool.value));
+        case 'vgxness_code_context_status':
+            return validationSuccess(tool.value, validateCodeContextStatusInput(input, tool.value));
         case 'vgxness_resume_context':
             return validationSuccess(tool.value, validateResumeContextInput(input, tool.value));
         case 'vgxness_agent_resolve':

package/dist/verification/verification-plan-service.js

@@ -49,6 +49,20 @@ const templates = {
         recommendations: [nodeVersionRecommendation(), typecheckRecommendation(), manualRecommendation('manual-workflow-tests', 'Run workflow/run tests manually', 'Copy focused node --import tsx --test commands for touched workflow or run test files.')],
         manualChecks: [manualCheck('review-allowlist-boundary', 'Review command allowlist boundary', 'Confirm no arbitrary shell, argv, or package-script execution contract was added.')],
     },
+    'code-context': {
+        rationale: [
+            'Code-context changes span CLI, MCP, provider selection, and bounded repository-intelligence probes.',
+            'CodeGraph and Graphify evidence must remain read-only advisory context; verification must not install packages, initialize indexes, or write provider config.',
+        ],
+        recommendations: [
+            typecheckRecommendation(),
+            manualRecommendation('manual-code-context-tests', 'Run focused code-context tests manually', 'Copy focused node --import tsx --test commands for code-context service, MCP, CLI, docs, and prompt tests after selecting touched files.'),
+        ],
+        manualChecks: [
+            manualCheck('review-code-context-read-only-boundary', 'Review code-context read-only boundary', 'Confirm CodeGraph and Graphify paths only report status/query evidence and do not install packages, initialize indexes, write provider config, or infer SDD acceptance.'),
+            manualCheck('review-code-context-provider-selection', 'Review provider selection guidance', 'Confirm source/call-path/blast-radius modes prefer CodeGraph and architecture/docs/corpus modes prefer Graphify while unsupported/missing providers degrade gracefully.'),
+        ],
+    },
 };
 export class VerificationPlanService {
     getPlan(changeType) {

package/dist/verification/verification-plan.js

@@ -8,6 +8,7 @@ export const verificationChangeTypes = [
     'provider-setup',
     'package-release',
     'workflow-runs',
+    'code-context',
 ];
 export const verificationChangeTypeList = verificationChangeTypes.join(', ');
 export const verificationPlanSafety = Object.freeze({

package/docs/cli.md

@@ -262,6 +262,19 @@ Provider support for setup is:
 
 Setup CLI surfaces do **not** silently write OpenCode or other provider config, do **not** call provider executables, and do **not** approve/reject preflights. They print diagnostics, recovery hints, and manual fallback commands; daily SDD work should continue in OpenCode.
 
+
+## Code context CLI
+
+Use `code-context status` and `code-context query` when you need optional repository-intelligence evidence from CodeGraph or Graphify without making those tools part of setup.
+
+```bash
+bun run cli:bun -- code-context status --workspace . --json
+bun run cli:bun -- code-context query --workspace . --mode impact --question "What calls this service?" --json
+bun run cli:bun -- code-context setup plan --workspace .
+```
+
+`code-context setup plan` is guidance only. The code-context CLI never installs packages, does not initialize indexes, does not write provider config, does not register external MCP servers, and does not infer SDD acceptance. `code-context query` is an explicit CLI command that runs the selected provider binary under bounded timeout/output caps; provider side effects are treated as unknown and the query tool is not exposed over MCP. CodeGraph is preferred for impact/debug/affected-tests modes; Graphify is preferred for architecture/overview/PR-impact modes. Missing providers degrade to diagnostics instead of auto-installing anything.
+
 ## Natural-language orchestrator preview
 
 Use `orchestrator preview` when you want `vgxness` to classify a request before deciding whether to answer directly, plan manually, diagnose, or enter SDD:

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP tools
 
-VGXNESS exposes 42 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
+VGXNESS exposes 43 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
 
 Tools are exposed under the `vgxness_*` prefix. Some MCP hosts strip the prefix and accept the short form (`sdd_status`, `memory_save`, etc.). The schema accepts both.
 
@@ -107,11 +107,19 @@ Run `status` accepts the full 8-state vocabulary: `created`, `planned`, `running
 | `vgxness_provider_doctor` | Run provider health checks with structured JSON output. | same as `status` | |
 | `vgxness_provider_change_plan` | Compose a read-only provider config change plan. | `ProviderChangePlanInput` shape (`provider`: `opencode`/`claude`/`antigravity`/`custom`; `changeType`: `opencode-mcp-install`/`setup`/`install`/`config-preparation`; `workspaceRoot`; `payloadMode`) | Does not write provider config. See [Providers](./providers.md). |
 
+## Code context (1)
+
+| Tool | Purpose | Required inputs | Notes |
+|---|---|---|---|
+| `vgxness_code_context_status` | Report optional CodeGraph and Graphify provider availability/index state. | `workspaceRoot`; optional `timeoutMs`, `maxBytes` | Read-only status only; does not install packages, initialize indexes, write provider config, run provider query commands, or infer SDD acceptance. |
+
+Code-context output is advisory evidence only. It can guide SDD, debugging, planning, verification, PR evidence, onboarding, and memory summaries, but it does not prove implementation correctness, artifact acceptance, or verification completion. The MCP surface exposes status only and does not install packages, initialize indexes, write provider config, run provider query commands, mutate files, or register external MCP servers. Provider-backed code-context queries intentionally stay CLI-only for now because they execute external provider binaries on the host; exposing them through MCP requires a future task-scoped grant/sandbox boundary.
+
 ## Verification (1)
 
 | Tool | Purpose | Required inputs |
 |---|---|---|
-| `vgxness_verification_plan` | Recommend a verification plan for a change type. | `changeType` (`docs-only`/`test-only`/`cli`/`mcp`/`sdd-storage`/`provider-setup`/`package-release`/`workflow-runs`) |
+| `vgxness_verification_plan` | Recommend a verification plan for a change type. | `changeType` (`docs-only`/`test-only`/`cli`/`mcp`/`sdd-storage`/`provider-setup`/`package-release`/`workflow-runs`/`code-context`) |
 
 ## Usage patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.20.8",
+  "version": "1.20.9",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {