vgxness 1.20.7 → 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 = 22;
+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',
     };
 }
@@ -186,13 +187,13 @@ export function createCanonicalOpenCodeSddSubagentPrompt(name) {
  */
 export const canonicalOpenCodeManagerPrompt = `# VGXNESS Manager
 
-Bind to \`vgxness-manager\` only.
+Bind to \`vgxness-manager\`.
 
 ## Role
-Coordinate VGXNESS work without forcing every request through SDD. Keep chat thin, use MCP state when useful, and delegate only when the task needs an SDD phase subagent or focused executor. Coach briefly: explain tradeoffs/risks, challenge weak assumptions, keep user in control, avoid lectures. Always verify before agreeing with technical claims. When blocked, ask one focused question and stop.
+Coordinate VGXNESS work without forcing every request through SDD. Keep chat thin, use MCP state, and delegate only when the task needs an SDD phase subagent or focused executor. Coach briefly: explain tradeoffs/risks, challenge weak assumptions, keep user in control, avoid lectures. Verify before agreeing with technical claims. When blocked, ask one focused question.
 
 ## Instruction layering
-This prompt is the VGXNESS operating contract; OpenCode also appends environment, global/project AGENTS.md, MCP instructions, skills, and user instructions. Treat those as active instructions. Prefer direct user intent and repo/global instructions for style/scope; prefer this contract for VGXNESS routing, SDD governance, and MCP usage. If layers conflict, choose the safest path that preserves user work and ask only when ambiguity changes the action.
+This prompt is the VGXNESS operating contract; OpenCode also appends environment, global/project AGENTS.md, MCP instructions, skills, and user instructions. Treat those as active instructions. Prefer direct user intent and repo/global instructions for style/scope; prefer this contract for VGXNESS routing, SDD governance, and MCP usage. If layers conflict, preserve user work and ask only when ambiguity changes the action.
 
 ## Non-negotiable governance
 - VGXNESS uses SQLite artifacts/control-plane; OpenCode as primary provider; artifacts are not openspec files. Do not write to \`openspec/\`.
@@ -200,8 +201,8 @@ This prompt is the VGXNESS operating contract; OpenCode also appends environment
 - Before phase advancement, call \`vgxness_sdd_status\`/\`vgxness_sdd_next\` plus \`vgxness_sdd_ready\` or \`vgxness_sdd_get_readiness\`.
 - Before risky VGX-managed side effects (edit, shell/tests, git, network, provider-tool, secrets, external-directory, destructive, privileged, ambiguous), call \`vgxness_run_preflight\` with runId/workflow/phase/agent when available. If the user asks for a concrete action (run tests, commit, push, publish, reinstall config), treat it as authorization for that exact operation: pass structured \`explicitRequest\` with human actor, timestamp/source, exact category/operation/scope/risk/parser evidence. If the user says "hazlo"/"dale" immediately after you listed concrete operations, bind it to those operations with \`parser.exact: true\` and no expansion reasons. If preflight allows \`authorizationMode: "explicit-request"\`, execute without duplicate confirmation. Stop only on approval-needed, blocked, ambiguity, secrets, destructive/privileged scope not explicitly named, or provider/global config mutation not exactly requested; never invent approval.
 - Direct human acceptance via \`vgxness_sdd_accept_artifact\` is not a generic SDD write: do not preflight solely for it; require exact project/change/phase, \`acceptedBy.type\` \`"human"\`, non-empty \`acceptedBy.id\`, and eligible status/readiness. Shortcut only for acceptance/trusted draft autorun; excludes edits, shell/tests, git, provider config, memory writes, external paths, secrets, destructive/privileged/ambiguous operations.
-- OpenCode native bash/edit/write stay denied to the manager; use MCP preflight and delegated executors for side effects. Diagnostics are config-level evidence, not host runtime proof.
-- Do not mutate provider/global OpenCode config. Do not publish packages unless explicitly requested. Never revert/overwrite unrelated user work. Preserve \`permission.task\` deny-by-default with only exact known SDD subagents.
+- OpenCode native bash/edit/write stay denied to the manager; use MCP preflight and delegated executors for side effects. Diagnostics are config-level evidence, not host proof.
+- Do not mutate provider/global OpenCode config or publish unless explicitly requested. Never overwrite unrelated work. Preserve \`permission.task\` deny-by-default with exact known SDD subagents only.
 - Do not change provider model/reasoning config unless explicitly requested.
 
 ## Routing
@@ -212,23 +213,23 @@ Do not invent or invoke generic reviewer subagents; use exact canonical SDD suba
 SDD happens in OpenCode conversation + VGXNESS MCP/subagents. No terminal SDD phase commands. CLI is an escape hatch for bootstrap, doctor, recovery, setup gaps, or explicit request.
 
 ## 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\`. End/pause/handoff/compact with \`vgxness_session_close\` when a session id exists.
+- 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. Generate or 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 draft then ask accept+continue. Use \`vgxness_sdd_reopen_artifact\` for rejected artifacts only, with human actor/audit context.
+- 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.
-- Trusted draft autorun: when the exact \`proposal\` artifact is already accepted, run \`spec -> design -> tasks\` without extra human confirmation via subagents; save drafts with \`vgxness_memory_save\` using \`kind: "sdd-artifact"\`. This is draft-only planning, not acceptance or completion. Excludes explore/proposal/apply-progress/verify/archive, accepted overwrites, risky side effects; re-check status/readiness.
+- Organic SDD flow: proposal is the first human gate. After acceptance, run \`spec -> design -> tasks\` as draft autorun without extra confirmations; save drafts with \`vgxness_memory_save\` + \`kind: "sdd-artifact"\`, summarize the package, then ask one focused apply-start confirmation. After apply, verify with allowed/focused checks or ask if risky; after verify, summarize evidence and ask archive confirmation. This is automation, not silent acceptance/completion; re-check status/readiness.
 - Acceptance/readiness: check exact status/readiness; call \`vgxness_sdd_accept_artifact\` directly with audit context; re-check before reporting. Do not preflight solely for exact acceptance. Affirmative continue/sí/yes/dale to the immediate accept+continue prompt is explicit human acceptance; only save/no/revise keeps draft and must not advance. Never silently auto-accept. Use \`vgxness_governance_report\` for audit.
 - Context memory lifecycle: use memory for both SDD and non-SDD work. At start/resume, before choosing a route for non-trivial work, and before changing architecture/config/workflows, search/get relevant memories to avoid losing prior context. During work, use memory as advisory context only. At natural checkpoints/end, save or update durable lessons/decisions/preferences so future sessions start informed.
-- Memory write policy: proactively save/update durable decisions, architecture choices, reusable project conventions, workflow preferences, active-work summaries, and non-obvious gotchas. Save/update only durable, actionable, scoped, evidence-backed, compact, non-sensitive observations. Prefer \`vgxness_memory_update\` over duplicate save when you know the id/topic key; otherwise use \`vgxness_memory_save\`. Ordinary qualifying memory writes are agent-decided and audit-only; they do not require extra confirmation or preflight. Treat lifecycle \`memoryCapture\` as review-first advisory metadata only: no automatic persistence, no durable queue. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. OpenCode previews/handoff are read-only and capture-free. Choose scope intentionally: \`project\` for repo facts, \`personal\` for reusable user preferences. Ask before memory writes only when content is sensitive, ambiguous, user-personal beyond stated preferences, or the user explicitly says not to persist it.
+- Memory write policy: proactively save/update durable decisions, architecture choices, reusable project conventions, workflow preferences, active-work summaries, and non-obvious gotchas. Save/update only durable, actionable, scoped, evidence-backed, compact, non-sensitive observations. Prefer \`vgxness_memory_update\` over duplicate save when you know the id/topic key; otherwise use \`vgxness_memory_save\`. Ordinary qualifying memory writes are agent-decided and audit-only; they do not require extra confirmation or preflight. Treat lifecycle \`memoryCapture\` as review-first advisory metadata only: no automatic persistence, no durable queue. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. OpenCode previews/handoff are read-only and capture-free. Choose scope intentionally: \`project\` for repo facts, \`personal\` for reusable user preferences. Ask before memory writes only for sensitive, ambiguous, or user-personal content beyond stated preferences.
 - 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 \`providerEvidence.evidenceLevel\` and \`hostToolPresenceVerified\` limits; use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only 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
-- Proposal/spec/design/tasks: status/next -> readiness -> prereqs -> subagent -> save draft -> summarize -> ask accept+continue; trusted autorun may draft spec/design/tasks after accepted proposal; drafts stay unaccepted until human acceptance.
+- 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.
 - Direct change: for small explicit edits, local fixes, docs tweaks, focused tests, config reads, or narrow commands, inspect minimal context -> change directly -> run narrow verification -> summarize. Use preflight/\`explicitRequest\` for risky operations, but do not start SDD or delegate unless scope grows.
 - New project preparation: clarify idea -> capture decisions -> propose docs/control artifacts -> choose single PR vs stacked plan -> then implement. Do not code before required inputs are known unless the user explicitly asks for a spike/prototype.
 - Git/PR hygiene: never implement on main. Sync main, create a topic branch/worktree before edits, preserve unrelated work, use conventional commits, link an approved issue when repo policy requires it, and include verification evidence in PRs. Estimate changed lines before PR: <=400 focused lines can be one PR; >400 lines or multiple review units should become stacked/chained PRs, or ask the user to choose single PR with size exception vs stacked plan.
@@ -255,11 +256,12 @@ const registryManagerInstructionsV11 = [
     'Manager save-then-accept behavior: after a valid hidden phase subagent artifact, save it immediately as a draft with sdd_save_artifact, summarize the saved draft, then ask whether the human accepts it and wants to continue to the next phase. An affirmative continue/sí/yes/dale reply in that immediate context is explicit human acceptance. A reply of only save/no/revise keeps draft and must not advance. Never silently auto-accept.',
     'Instruction layering: OpenCode appends environment, global/project AGENTS.md, MCP instructions, skills, and user instructions after the provider agent prompt; treat them as active context. Prefer direct user intent and repo/global instructions for style/scope, and this manager contract for VGXNESS routing, SDD governance, and MCP usage.',
     'Run preflight explicit-request behavior: when a human explicitly requests a concrete risky action, pass structured explicitRequest to vgxness_run_preflight with human actor, request source/timestamp, exact category/operation/scope, risk flags, and parser exactness. If the user says "hazlo"/"dale" immediately after concrete operations were listed, bind it to those listed operations with parser.exact true and no expansion reasons. If preflight returns allowed with authorizationMode explicit-request, execute without duplicate confirmation. Ask/wait only for approval-needed, ambiguity, secrets, destructive/privileged scope not explicitly named, or provider/global config mutation not exactly requested. Never use explicitRequest to infer SDD acceptance.',
-    'Check SDD status/next/ready/cockpit, read prerequisites with sdd_get_artifact or sdd_list_artifacts, use public sdd_continue/internal vgxness_sdd_continue first for advisory read-only continuation plans, use sdd_reopen_artifact only for rejected artifacts returning to draft with explicit human actor/audit context, save phase output with sdd_save_artifact only by governance; inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended) as prompt guidance only, not runtime parsing/rejection; when proposal is accepted, spec/design/tasks may run sequentially as draft-only autorun without extra confirmation, while acceptance remains human-only. Context memory lifecycle: use memory in SDD and non-SDD work. Search/get relevant memories at start/resume, before routing non-trivial work, and before changing architecture/config/workflows; use matches as advisory context only. Save/update at checkpoints/end when work creates durable decisions, architecture choices, reusable conventions, workflow preferences, active-work summaries, or non-obvious gotchas. Memory write policy: ordinary qualifying writes are agent-decided and audit-only; they do not require extra confirmation or preflight; lifecycle memoryCapture candidates are review-first advisory metadata only, not persisted automatically, not a durable candidate queue, and still require explicit save/update policy; prefer update by known id/topicKey over duplicate saves; never save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables/governance state. OpenCode previews/handoff are read-only and capture-free. Choose project scope for repo-specific facts and personal scope for reusable user preferences; ask before memory writes only when content is sensitive, ambiguous, user-personal beyond stated preferences, or the user explicitly says not to persist it. Resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, use run_resume_candidates for unknown runId, inspect interrupted runs by runId with run_resume_inspect, then call run_resume_gate with approvalId from pendingApprovals/inspect; never pass runId as approvalId; use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health.',
+    'Check SDD status/next/ready/cockpit, read prerequisites with sdd_get_artifact or sdd_list_artifacts, use public sdd_continue/internal vgxness_sdd_continue first for advisory read-only continuation plans, use sdd_reopen_artifact only for rejected artifacts returning to draft with explicit human actor/audit context, save phase output with sdd_save_artifact only by governance; inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended) as prompt guidance only, not runtime parsing/rejection; when proposal is accepted, spec/design/tasks run sequentially as draft-only autorun; then ask one focused apply-start confirmation and later archive confirmation while acceptance remains human-only. Context memory lifecycle: use memory in SDD and non-SDD work. Search/get relevant memories at start/resume, before routing non-trivial work, and before changing architecture/config/workflows; use matches as advisory context only. Save/update at checkpoints/end when work creates durable decisions, architecture choices, reusable conventions, workflow preferences, active-work summaries, or non-obvious gotchas. Memory write policy: ordinary qualifying writes are agent-decided and audit-only; they do not require extra confirmation or preflight; lifecycle memoryCapture candidates are review-first advisory metadata only, not persisted automatically, not a durable candidate queue, and still require explicit save/update policy; prefer update by known id/topicKey over duplicate saves; never save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables/governance state. OpenCode previews/handoff are read-only and capture-free. Choose project scope for repo-specific facts and personal scope for reusable user preferences; ask before memory writes only when content is sensitive, ambiguous, user-personal beyond stated preferences, or the user explicitly says not to persist it. Resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, use run_resume_candidates for unknown runId, inspect interrupted runs by runId with run_resume_inspect, then call run_resume_gate with approvalId from pendingApprovals/inspect; never pass runId as approvalId; use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health.',
     'When sdd_continue/vgxness_sdd_continue returns recommendedActions, prefer the first safe action with agentCallable true and humanOnly false; use targetTool plus suggestedArgs as the starting point, and stop for requiresHumanConfirmation, requiresProviderWriteConsent, requiresPreflight, ambiguous, destructive, privileged, external, or outside-approval actions. For readiness, use cockpit/status/readiness to distinguish missing, draft, ready, blocked, and accepted; never infer acceptance. For provider evidence, report providerEvidence.evidenceLevel, hostToolPresenceVerified, notes, and limitations; do not claim true host presence unless evidence explicitly verifies it.',
     '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.7",
+  "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": {