vgxness 1.21.0 → 1.21.1

package/dist/adapters/opencode/install/client-install-opencode.js

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createManagedProviderConfigBackup } from '../../../setup/backup-rollback-service.js';
 import { findConflictingVgxnessAgents, planOpenCodeMcpInstall, } from './client-install-opencode-contract.js';
-import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, vgxnessOpenCodeInstructionsPath, } from './opencode-default-agent-config.js';
+import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, createOpenCodeGlobalInstructionsContent, createOpenCodeGlobalInstructionsManagedBlock, vgxnessOpenCodeGlobalInstructionsBlockEnd, vgxnessOpenCodeGlobalInstructionsBlockStart, vgxnessOpenCodeInstructionsPath, } from './opencode-default-agent-config.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
 export { createInstalledVgxnessMcpServerCommand };
 function createInstalledVgxnessMcpServerCommand(databasePath, source = 'flag') {
@@ -45,7 +45,11 @@ export async function installOpenCodeMcpClient(input) {
                 return agentConflictRefusal(conflictingAgents, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.bashPermissionPolicy);
             return refusal('unsupported_config_shape', 'OpenCode config appeared after planning; rerun setup apply so it can be merged safely without overwriting user config.', input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
         }
+        const globalInstructions = prepareOpenCodeGlobalInstructionsWrite(plan.targetPath, plan.scope, input.env?.HOME, agentPlan);
+        if (!globalInstructions.ok)
+            return refusal('post_write_validation_failed', globalInstructions.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
         writeConfig(plan.targetPath, mergeVgxnessOpenCodeConfig({ $schema: opencodeConfigSchema }, plan.server, plan.installsAgents, input.effectiveManagerInstructions));
+        writeOpenCodeGlobalInstructions(globalInstructions.value);
         return validateInstalledResult(plan.targetPath, undefined, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
     }
     const parsed = parseConfig(plan.targetPath);
@@ -59,9 +63,13 @@ export async function installOpenCodeMcpClient(input) {
     const backup = createBackup(plan.targetPath, plan.scope, input.env?.HOME);
     if (!backup.ok)
         return refusal('post_write_validation_failed', backup.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
+    const globalInstructions = prepareOpenCodeGlobalInstructionsWrite(plan.targetPath, plan.scope, input.env?.HOME, agentPlan);
+    if (!globalInstructions.ok)
+        return refusal('post_write_validation_failed', globalInstructions.error.message, input.databasePath, databasePathSource, server, applySafety(plan), plan.targetPath, plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
     const config = parsed.value;
     const mergedConfig = mergeVgxnessOpenCodeConfig({ ...config, $schema: plan.existingSchema ?? opencodeConfigSchema }, plan.server, plan.installsAgents, input.effectiveManagerInstructions);
     writeConfig(plan.targetPath, mergedConfig);
+    writeOpenCodeGlobalInstructions(globalInstructions.value);
     return validateInstalledResult(plan.targetPath, backup.value, server, input.databasePath, databasePathSource, applySafety(plan), plan.verificationHints, plan.warnings, plan.manualTest, agentPlan, plan.overwriteVgxness, plan.bashPermissionPolicy);
 }
 function mergeVgxnessOpenCodeConfig(config, server, installsAgents, effectiveManagerInstructions) {
@@ -101,14 +109,68 @@ function writeConfig(path, config) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
 }
-function createBackup(path, scope, allowedManagedHome) {
+function prepareOpenCodeGlobalInstructionsWrite(opencodeConfigPath, scope, allowedManagedHome, agentPlan) {
+    const instructionsPath = join(dirname(opencodeConfigPath), vgxnessOpenCodeInstructionsPath);
+    if (!agentPlan.installsAgents)
+        return { ok: true, value: { path: instructionsPath, content: '', changed: false } };
+    const existing = existsSync(instructionsPath) ? readFileSync(instructionsPath, 'utf8') : undefined;
+    const nextContent = reconcileOpenCodeGlobalInstructions(existing);
+    if (existing === nextContent)
+        return { ok: true, value: { path: instructionsPath, content: nextContent, changed: false } };
+    if (existing !== undefined) {
+        const backup = createBackup(instructionsPath, scope, allowedManagedHome, {
+            reason: 'pre-global-instructions-merge',
+            description: 'Backup existing OpenCode global AGENTS.md before aligning VGXNESS global instructions.',
+        });
+        if (!backup.ok)
+            return backup;
+    }
+    return { ok: true, value: { path: instructionsPath, content: nextContent, changed: true } };
+}
+function writeOpenCodeGlobalInstructions(plan) {
+    if (!plan.changed)
+        return;
+    mkdirSync(dirname(plan.path), { recursive: true });
+    writeFileSync(plan.path, plan.content);
+}
+function reconcileOpenCodeGlobalInstructions(existing) {
+    const canonical = createOpenCodeGlobalInstructionsContent();
+    if (existing === undefined || existing.trim().length === 0)
+        return canonical;
+    if (looksLikeLegacyVgxnessGlobalInstructions(existing) || looksLikeUnmarkedVgxnessGlobalInstructions(existing))
+        return canonical;
+    if (existing.includes(vgxnessOpenCodeGlobalInstructionsBlockStart) || existing.includes(vgxnessOpenCodeGlobalInstructionsBlockEnd)) {
+        return replaceOpenCodeGlobalInstructionsManagedBlock(existing);
+    }
+    return `${existing.trimEnd()}\n\n${createOpenCodeGlobalInstructionsManagedBlock()}\n`;
+}
+function replaceOpenCodeGlobalInstructionsManagedBlock(existing) {
+    const start = existing.indexOf(vgxnessOpenCodeGlobalInstructionsBlockStart);
+    const end = existing.indexOf(vgxnessOpenCodeGlobalInstructionsBlockEnd);
+    const block = createOpenCodeGlobalInstructionsManagedBlock();
+    if (start < 0 || end < start)
+        return `${existing.trimEnd()}\n\n${block}\n`;
+    const afterEnd = end + vgxnessOpenCodeGlobalInstructionsBlockEnd.length;
+    return `${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(afterEnd).trimStart()}`;
+}
+function looksLikeLegacyVgxnessGlobalInstructions(content) {
+    return /^# VGXNESS Persona\b/m.test(content) || content.includes('gentle-ai:codegraph-guidance');
+}
+function looksLikeUnmarkedVgxnessGlobalInstructions(content) {
+    return (/^# Global OpenCode Instructions\b/m.test(content) &&
+        content.includes('## Instruction Layering') &&
+        content.includes('## Memory and Context Continuity') &&
+        content.includes('## VGXNESS Workflow Expectations') &&
+        content.includes('## Code Context Providers'));
+}
+function createBackup(path, scope, allowedManagedHome, override) {
     return createManagedProviderConfigBackup({
         targetPath: path,
         provider: 'opencode',
         scope,
         createdByOperation: 'mcp-client-install-opencode',
-        reason: 'pre-merge-safety',
-        description: 'Backup existing OpenCode config before merging VGXNESS MCP configuration.',
+        reason: override?.reason ?? 'pre-merge-safety',
+        description: override?.description ?? 'Backup existing OpenCode config before merging VGXNESS MCP configuration.',
         ...(allowedManagedHome !== undefined ? { allowedManagedHome } : {}),
     });
 }
@@ -126,6 +188,10 @@ function validateInstalledResult(targetPath, backup, server, databasePath, sourc
         if (!isRecord(agent) || parsed.value.default_agent !== agentPlan.defaultAgent || agentPlan.agentNames.some((name) => !isRecord(agent[name]))) {
             return refusal('post_write_validation_failed', 'OpenCode config was written but VGXNESS agent entries did not validate.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness, bashPermissionPolicy);
         }
+        const instructionsPath = join(dirname(targetPath), vgxnessOpenCodeInstructionsPath);
+        if (!existsSync(instructionsPath) || !readFileSync(instructionsPath, 'utf8').includes('## Memory and Context Continuity')) {
+            return refusal('post_write_validation_failed', 'OpenCode config was written but global AGENTS.md instructions did not validate.', databasePath, source, server, safety, targetPath, verificationHints, warningMessages, manualTestGuidance, agentPlan, overwriteVgxness, bashPermissionPolicy);
+        }
     }
     const permission = parsed.value.permission;
     if (!isRecord(permission) || permission.bash !== 'ask') {

package/dist/adapters/opencode/install/opencode-default-agent-config.js

@@ -3,6 +3,8 @@ import { projectCanonicalAgentManifestToOpenCode, withEffectiveOpenCodeManagerIn
 export const vgxnessOpenCodeDefaultAgent = canonicalDefaultAgentName;
 export const vgxnessOpenCodePromptContractVersion = canonicalPromptContractVersion;
 export const vgxnessOpenCodeInstructionsPath = 'AGENTS.md';
+export const vgxnessOpenCodeGlobalInstructionsBlockStart = '<!-- VGXNESS-GLOBAL-INSTRUCTIONS:START -->';
+export const vgxnessOpenCodeGlobalInstructionsBlockEnd = '<!-- VGXNESS-GLOBAL-INSTRUCTIONS:END -->';
 export const vgxnessOpenCodeSddSubagents = canonicalSddSubagentNames;
 export function createOpenCodeSddTaskPermissions() {
     return createCanonicalOpenCodeSddTaskPermissions();
@@ -18,3 +20,90 @@ export function createOpenCodeDefaultAgentInstallPlan(input = {}) {
 export function createOpenCodeDefaultAgentConfig(input = {}) {
     return withEffectiveOpenCodeManagerInstructions(projectCanonicalAgentManifestToOpenCode(), input.effectiveManagerInstructions);
 }
+export function createOpenCodeGlobalInstructionsContent() {
+    return `# Global OpenCode Instructions
+
+These are global instructions for OpenCode. They define user preferences, context-continuity expectations, and broad safety rules. They do not replace project \`AGENTS.md\` / \`CLAUDE.md\` files, VGXNESS-managed agent prompts, MCP instructions, or task-specific skills.
+
+## Instruction Layering
+
+- Treat this file as the user's global collaboration and safety layer.
+- Project instruction files define repository-specific commands, architecture, and conventions.
+- When the selected agent is \`vgxness-manager\`, treat its generated prompt as the operational routing/governance layer.
+- VGXNESS MCP and SQLite are the source of truth for VGXNESS state: SDD artifacts, memory, permissions, runs, setup evidence, and verification evidence.
+- OpenCode and Claude execute provider-native. VGXNESS coordinates and governs; it is not a provider runtime.
+- If layers conflict, preserve safety and user intent first, then project instructions, then VGXNESS-managed workflow rules, then this global preference layer. Report the conflict instead of guessing.
+
+## Rules
+
+- Never add \`Co-Authored-By\` or AI attribution to commits.
+- Use conventional commits unless the repository explicitly says otherwise.
+- Ask at most one focused question at a time. After asking, stop and wait.
+- Never agree with technical claims without verification. Check code, docs, config, live state, or evidence first.
+- If the user is wrong, explain why with evidence and show the correct path.
+- If you were wrong, acknowledge it clearly and explain the correction.
+- Prefer alternatives with tradeoffs when the decision has meaningful consequences.
+- Do not overwrite, revert, commit, push, publish, install, or mutate provider/global configuration unless the user explicitly requested that scope.
+- Protect user work and unrelated changes. Before editing a repo, check branch/status and avoid working directly on \`main\`/\`master\` unless the task is explicitly a local maintenance step.
+- For code changes, prefer small focused diffs and focused verification. Full gates are for release, high-risk, pre-merge, or broad cross-cutting changes.
+- For configuration changes, preserve unrelated settings, create/keep backups when available, and explain restart requirements.
+
+## Language and Tone
+
+- Respond in the same language the user uses.
+- Use a warm, professional, direct tone.
+- Act like a senior architect and teacher: practical, concept-first, and invested in the user's growth.
+- Push back when a request is risky, vague, or technically weak. Be precise, not rude.
+
+## Philosophy
+
+- CONCEPTS > CODE.
+- AI is a tool; the human leads.
+- Solid foundations before shortcuts.
+- Architecture and correctness matter more than immediacy.
+- Prefer safe, testable, reversible steps.
+
+## Memory and Context Continuity
+
+The agent must not start each interaction blind when durable context exists.
+
+- At session start, resume, or before non-trivial work, inspect relevant available context before acting: VGXNESS resume/context state, project memory, active SDD artifacts, recent runs, and relevant project instructions.
+- For VGXNESS-managed work, prefer VGXNESS MCP/SQLite context over guessing. Use available memory/resume/context tools such as \`vgxness_resume_context\`, \`vgxness_memory_search\`, \`vgxness_memory_get\`, \`vgxness_sdd_status\`, \`vgxness_sdd_get_artifact\`, and run/status tools when they are available and permitted.
+- Memory is advisory context, not proof. It can guide recall and continuity, but it does not prove acceptance, readiness, verification, authorization, or current source state. Verify against live files, git, commands, docs, or provider config before making claims.
+- Before architecture, workflow, configuration, release, or SDD decisions, search/retrieve relevant memory or SDD artifacts so the user does not need to repeat context.
+- At natural checkpoints and session end, save or update durable context when available: decisions, architecture choices, reusable conventions, environment/config gotchas, release/reinstall procedures, and active-work summaries.
+- Prefer updating an existing memory when an id/topic is known; otherwise save a compact new memory. Avoid duplicate memory spam.
+- Do not store secrets, credentials, hidden reasoning, raw transcripts, raw logs, sensitive personal data, or full SDD artifacts as ordinary memory. SDD artifacts belong in the SDD artifact store.
+- If memory conflicts with current evidence, trust current evidence and record/update the corrected durable context.
+
+## VGXNESS Workflow Expectations
+
+- Treat VGXNESS as a local-first governance OS / control plane for existing coding agents.
+- Daily implementation can happen in OpenCode or Claude provider-native; VGXNESS governs state, evidence, memory, permissions, and SDD flow.
+- Do not imply a \`vgxness code\` provider runtime unless the product explicitly adds one.
+- Human acceptance is explicit. Drafting artifacts, generating plans, or passing tests does not equal acceptance.
+- Capability subagents are optional tools for useful delegation, not mandatory for every request.
+- For small concrete requests, use direct-change routing: inspect minimal context, make the narrow change, run focused verification, and summarize evidence.
+- Use SDD for phase-shaped, large, architectural, unclear, governance-sensitive, or explicitly requested SDD work.
+- After VGXNESS/OpenCode setup changes, restart OpenCode so it reloads config.
+
+## Code Context Providers
+
+CodeGraph and Graphify are optional repository-intelligence providers. They provide advisory evidence; they are not required for every task.
+
+- Prefer VGXNESS \`code-context\` status/query surfaces when available.
+- Do not install packages, initialize indexes, write provider config, or register external MCP servers unless the user explicitly asks for that setup/mutation.
+- If a provider index is missing, report the missing index and recommended command instead of silently creating it.
+- Use code-context evidence to inform architecture, impact, debugging, tests, PR evidence, onboarding, and memory summaries, but verify conclusions against source files and tests.
+
+## Behavior
+
+- Explain the problem, then the solution, then the tradeoffs when useful.
+- Use examples when they clarify the concept.
+- Keep summaries concise but include concrete evidence: files changed, commands run, checks passed/failed, and remaining risk.
+- If blocked, say exactly what blocked progress and what decision or credential is needed next.
+`;
+}
+export function createOpenCodeGlobalInstructionsManagedBlock() {
+    return `${vgxnessOpenCodeGlobalInstructionsBlockStart}\n${createOpenCodeGlobalInstructionsContent().trimEnd()}\n${vgxnessOpenCodeGlobalInstructionsBlockEnd}`;
+}

package/dist/setup/backup-rollback-service.js

@@ -263,6 +263,8 @@ function isManagedUserGlobalProviderTarget(targetPath, allowedManagedHome) {
     const home = resolveManagedHome(allowedManagedHome);
     if (targetPath === resolve(home, '.config', 'opencode', 'opencode.json'))
         return true;
+    if (targetPath === resolve(home, '.config', 'opencode', 'AGENTS.md'))
+        return true;
     if (targetPath === resolve(home, '.claude.json'))
         return true;
     if (targetPath === resolve(home, '.claude', 'CLAUDE.md'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.21.0",
+  "version": "1.21.1",
   "description": "Local-first governance OS, CLI and MCP control plane for existing coding agents, SDD, memory, runs, permissions, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {