vgxness 1.20.15 → 1.21.1

package/README.md

@@ -1,14 +1,14 @@
 # VGXNESS
 
-VGXNESS is an installable CLI and MCP control plane for guided AI-agent workflows, SDD artifacts, local memory, and OpenCode integration.
+VGXNESS is an installable, local-first governance OS and MCP/CLI control plane for existing coding agents. It governs SDD artifacts, local memory, runs, permissions, skills, provider setup, and verification evidence while OpenCode, Claude Code, and future adapters keep executing provider-native.
 
 ## Release status and license
 
 This package is proprietary software. The npm package ships inspectable JavaScript (`dist/`) so Node can run it, but it is **not open-source licensed** and may not be redistributed unless you have written permission. See [LICENSE](./LICENSE).
 
-OpenCode is the primary supported provider. Claude setup support is secondary. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
+OpenCode is the primary supported provider. Claude Code setup support is secondary/preview guidance. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.
 
-VGXNESS is currently versioned from `package.json` (`1.20.0`). The latest full project health audit is the historical [v1.14.x snapshot](./docs/project-health-audit-v1.14.x.md), which documents the implemented CLI/MCP/SDD control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
+VGXNESS is versioned from `package.json`. The latest full project health audit is the historical [v1.14.x snapshot](./docs/project-health-audit-v1.14.x.md), which documents the implemented CLI/MCP/SDD governance control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. [v1.10.x](./docs/project-health-audit-v1.10.x.md) and [v1.9.1](./docs/project-health-audit-v1.9.1.md) remain historical validation evidence for those releases.
 
 ## Requirements
 
@@ -163,7 +163,7 @@ vgxness setup apply --yes
 
 `vgxness setup plan` and `vgxness setup status` are human-readable and do not write provider config by default; local VGXNESS store initialization may occur when a command needs the selected SQLite store. `vgxness doctor`, `vgxness status`, `vgxness next`, `vgxness sdd status`, `vgxness sdd next`, `vgxness sdd continue`, and `vgxness sdd accept-artifact` are also human-readable by default. Pass `--json` when you need parseable automation output. `vgxness setup apply --yes` is the explicit provider-config write path.
 
-The daily SDD happy path is OpenCode conversation with the installed VGXNESS MCP server and hidden SDD subagents. Use CLI commands for bootstrap, setup, diagnostics, recovery, fallback, and scripting: `status`, `next`, and `sdd continue` inspect state and print read-only continuation guidance; `resume` helps inspect interrupted work. After a draft is ready, `sdd accept-artifact` records explicit human acceptance, and `sdd reopen-artifact` returns rejected artifacts to draft.
+The daily SDD happy path is an OpenCode conversation with the installed VGXNESS MCP server and provider-native hidden SDD subagents. VGXNESS supplies the governance state and guardrails; OpenCode executes the agent loop. Use CLI commands for bootstrap, setup, diagnostics, recovery, fallback, and scripting: `status`, `next`, and `sdd continue` inspect state and print read-only continuation guidance; `resume` helps inspect interrupted work. In the normal organic flow, proposal acceptance is the first mandatory human continue gate; after that, `spec -> design -> tasks` can be drafted without separate confirmations, then VGXNESS asks before apply/implementation. `sdd accept-artifact` records explicit human-only acceptance when a real gate applies, and `sdd reopen-artifact` returns rejected artifacts to draft.
 
 Copy this prompt into OpenCode for normal daily SDD work:
 
@@ -171,24 +171,25 @@ Copy this prompt into OpenCode for normal daily SDD work:
 Continue VGXNESS SDD for project <project> and change <change>.
 Use the VGXNESS MCP tools to inspect status/readiness/artifacts, then delegate phase work to the exact hidden SDD subagent when needed.
 Save draft artifacts when appropriate and report evidence, tests, blockers, and the next human decision.
-Do not accept or reopen artifacts for me; ask me before any human-only, provider-config, git, destructive, external, install, or secret-sensitive action.
+Treat proposal acceptance as the first mandatory human continue gate; after that, draft spec/design/tasks without separate confirmations, then ask before apply/implementation.
+Do not accept or reopen artifacts for me; ask before provider/global config, git/publish, destructive, external, privileged, install, network, secret-sensitive, or official archive actions.
 ```
 
 ## Code runtime status
 
-The experimental `vgxness code` runtime and principal OpenTUI code surface have been removed temporarily because they were copied OpenCode-like runtime work. Continue SDD work in OpenCode through VGXNESS MCP, and use the safe CLI commands above for diagnostics and recovery.
+The experimental `vgxness code` runtime and principal OpenTUI code surface have been removed and are not the default product direction. Continue SDD work in OpenCode through VGXNESS MCP, and use the safe CLI commands above for diagnostics and recovery. Reintroducing a first-party coding-agent runtime would require a separate accepted SDD change.
 
 ## Safety model
 
 - Preview, status, and plan commands do not write provider config; local VGXNESS store initialization may occur where the command needs SQLite-backed state.
 - VGX-managed OpenCode and Claude provider config writes are user-global only and require explicit `--yes` confirmation.
 - Runtime VGXNESS state remains project-aware; project-local provider files are read-only external/manual diagnostics and may still affect provider behavior outside VGXNESS.
-- Setup/status TUI surfaces are read-only setup, diagnostics, recovery, and fallback surfaces; daily SDD progression stays in OpenCode with VGXNESS MCP.
+- Setup/status TUI surfaces are read-only setup, diagnostics, recovery, and fallback surfaces; daily SDD progression stays in OpenCode with VGXNESS MCP and provider-native execution.
 - SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write `openspec/`.
-- `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance.
+- `vgxness sdd accept-artifact` records explicit human-only acceptance; saving a draft never implies acceptance, and normal spec/design/tasks draft autorun after proposal acceptance is not silent acceptance.
 - `vgxness sdd reopen-artifact` is the explicit path from a rejected artifact back to draft before revision.
-- OpenCode is the primary supported provider; other providers are preview/manual extension points.
-- VGXNESS exposes 42 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See [MCP tools](./docs/mcp.md).
+- OpenCode is the primary supported provider; Claude Code is secondary/preview guidance; other providers are preview/manual extension points.
+- VGXNESS exposes 63 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See [MCP tools](./docs/mcp.md).
 
 ## Principal entrypoint
 

package/dist/adapters/claude/install/claude-code-agent-config.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, parse, resolve } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeCode } from '../../../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeCode } from '../../../application/agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeCodeGeneratedMarker = 'VGXNESS-GENERATED';
 export function expectedClaudeCodeAgentFiles(input) {

package/dist/adapters/claude/install/claude-code-project-memory.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../application/agents/canonical-agent-projection.js';
 import { assertInsideWorkspace } from './claude-code-config.js';
 export const claudeProjectMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
 export const claudeProjectMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';

package/dist/adapters/claude/install/claude-code-user-memory.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../agents/canonical-agent-projection.js';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../../../application/agents/canonical-agent-projection.js';
 import { safeHomeDirectory } from './claude-code-agent-config.js';
 export const claudeUserMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE USER MEMORY -->';
 export const claudeUserMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE USER MEMORY -->';

package/dist/adapters/claude/install/client-install-claude-code-contract.js

@@ -1,4 +1,4 @@
-import { withEffectiveManagerInstructions } from '../../../agents/canonical-agent-projection.js';
+import { withEffectiveManagerInstructions } from '../../../application/agents/canonical-agent-projection.js';
 import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
 import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig } from './claude-code-config.js';

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

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { canonicalCapabilitySubagentLegacyAliases } from '../../../agents/canonical-agent-manifest.js';
+import { canonicalCapabilitySubagentLegacyAliases } from '../../../domain/agents/canonical-agent-manifest.js';
 import { createOpenCodeDefaultAgentConfig, createOpenCodeDefaultAgentInstallPlan, } from './opencode-default-agent-config.js';
 const opencodeConfigSchema = 'https://opencode.ai/config.json';
 const opencodeUserGlobalOnlyMessage = 'VGX-managed OpenCode configuration is user-global only. Project/local OpenCode files are treated as external/manual diagnostics and will not be written by VGXNESS. Re-run without the project/local install scope.';

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 { canonicalCapabilitySubagentLegacyAliases } from '../../../agents/canonical-agent-manifest.js';
+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

@@ -1,8 +1,10 @@
-import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddMcpToolPermissions, createCanonicalOpenCodeSddTaskPermissions, } from '../../../agents/canonical-agent-manifest.js';
-import { projectCanonicalAgentManifestToOpenCode, withEffectiveOpenCodeManagerInstructions, } from '../../../agents/canonical-agent-projection.js';
+import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddMcpToolPermissions, createCanonicalOpenCodeSddTaskPermissions, } from '../../../domain/agents/canonical-agent-manifest.js';
+import { projectCanonicalAgentManifestToOpenCode, withEffectiveOpenCodeManagerInstructions, } from '../../../application/agents/canonical-agent-projection.js';
 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/application/agents/agent-resolver.js

@@ -1,5 +1,5 @@
 import { canonicalCapabilitySubagentLegacyAliases } from '../../domain/agents/canonical-agent-manifest.js';
-import { normalizeSddPhaseInput } from '../../sdd/schema.js';
+import { normalizeSddPhaseInput } from '../../domain/sdd/schema.js';
 import { agentLookupContexts } from './agent-lookup-contexts.js';
 export class AgentResolver {
     loadAgents;

package/dist/application/memory/import/observation-writer.js

@@ -1,5 +1,5 @@
-import { sddTopicKey } from '../../../sdd/schema.js';
-import { SddWorkflowService } from '../../../sdd/sdd-workflow-service.js';
+import { sddTopicKey } from '../../../domain/sdd/schema.js';
+import { SddWorkflowService } from '../../sdd/sdd-workflow-service.js';
 import { validateMemoryImportPackage, } from './package.js';
 const context = { actor: 'memory-import' };
 export function writeMemoryImportObservations(input) {

package/dist/application/memory/import/package.js

@@ -1,4 +1,4 @@
-import { isSddPhase, sddPhases, sddTopicKey } from '../../../sdd/schema.js';
+import { isSddPhase, sddPhases, sddTopicKey } from '../../../domain/sdd/schema.js';
 export const MEMORY_IMPORT_PACKAGE_KIND = 'vgxness.memory-import-package';
 export const MEMORY_IMPORT_PACKAGE_VERSION = 1;
 export const MEMORY_IMPORT_PACKAGE_SOURCE = 'engram';

package/dist/application/provider-setup/provider-change-plan.js

@@ -1,6 +1,6 @@
 import { planClaudeCodeMcpInstall, } from '../../adapters/claude/install/client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from '../../adapters/opencode/install/client-install-opencode-contract.js';
-import { resolveMemoryDatabasePath } from '../../memory/storage-paths.js';
+import { resolveMemoryDatabasePath } from '../../storage/memory/storage-paths.js';
 import { ProviderDoctorService } from './provider-doctor.js';
 import { providerRuntimeContext, } from './provider-health-types.js';
 import { ProviderStatusService } from './provider-status.js';

package/dist/application/runs/run-service.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { evaluatePermission } from '../../permissions/policy-evaluator.js';
 import { isRiskyPermissionCategory } from '../../permissions/schema.js';
-import { normalizeSddPhaseInput } from '../../sdd/schema.js';
+import { normalizeSddPhaseInput } from '../../domain/sdd/schema.js';
 import { RunRepository, } from '../../storage/runs/repositories/runs.js';
 import { AllowlistedApplyProgressCommandExecutor } from '../../workflows/command-allowlist-adapter.js';
 import { planExecutionIsolation, recommendWorkspaceStrategyForExecution } from './execution-planning.js';

package/dist/application/sdd/sdd-continuation-plan.js

@@ -27,7 +27,8 @@ export function sddContinuationPlanFrom(input) {
         safety: [
             'Read-only planner: this command does not execute providers or mutate SDD artifacts, runs, provider config, or openspec/ files.',
             'Human acceptance remains explicit; artifact presence is not treated as acceptance.',
-            'Continue SDD phases in OpenCode conversation through VGXNESS MCP and reusable capability subagents; the removed code runtime is not a CLI fallback.',
+            'OpenCode and Claude execute provider-native; VGXNESS MCP and SQLite govern SDD artifacts, memory, permissions, runs, and evidence.',
+            'Continue SDD phases in OpenCode or Claude, using capability subagents when helpful; the removed code runtime is not a CLI fallback.',
             'No openspec/ files are created or written.',
         ],
     };
@@ -115,7 +116,7 @@ function draftPhaseAction(project, change, phase, reason) {
         id: `sdd.${change}.${phase}.draft`,
         label: `Prepare ${phase} draft through normal SDD phase flow`,
         title: `Prepare ${phase} draft`,
-        description: 'The next SDD phase appears runnable; draft generation must still use the normal phase workflow and any required preflight gates. After a valid phase artifact is produced, save it as a draft immediately, then ask the human acceptance/continue question before advancing.',
+        description: 'The next SDD phase appears runnable; draft generation still happens in provider-native OpenCode or Claude through normal phase workflow and any required preflight gates. After a valid phase artifact is produced, save it as a draft immediately, then ask the human acceptance/continue question before advancing.',
         kind: 'draft-phase',
         category: 'sdd-phase',
         phase,
@@ -130,7 +131,7 @@ function draftPhaseAction(project, change, phase, reason) {
         requiresPreflight: true,
         requiresProviderWriteConsent: false,
         reason,
-        rationale: 'This continuation tool is read-only, so it can recommend the next phase but cannot execute providers or save artifacts itself.',
+        rationale: 'This continuation tool is read-only, so it can recommend the next phase but cannot execute providers, require subagents, or save artifacts itself.',
         blockingPrerequisites: [],
     };
 }

package/dist/application/skills/skill-registry-service.js

@@ -1,4 +1,4 @@
-import { AgentRepository } from '../../agents/repositories/agents.js';
+import { AgentRepository } from '../../storage/agents/repositories/agents.js';
 import { SkillEvaluationRequestRepository, } from '../../storage/skills/repositories/skill-evaluation-requests.js';
 import { SkillEvaluationScenarioRepository, } from '../../storage/skills/repositories/skill-evaluation-scenarios.js';
 import { SkillImprovementProposalRepository, } from '../../storage/skills/repositories/skill-improvement-proposals.js';

package/dist/application/skills/skill-resolver.js

@@ -1,6 +1,6 @@
-import { resolveAgentSelector } from '../../agents/agent-selector-resolver.js';
-import { canonicalDefaultAgentName } from '../../agents/canonical-agent-manifest.js';
-import { normalizeSddPhaseInput } from '../../sdd/schema.js';
+import { resolveAgentSelector } from '../agents/agent-selector-resolver.js';
+import { canonicalDefaultAgentName } from '../../domain/agents/canonical-agent-manifest.js';
+import { normalizeSddPhaseInput } from '../../domain/sdd/schema.js';
 import { skillLookupContexts } from './personal-skills.js';
 export class SkillResolver {
     skills;

package/dist/cli/bun-bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { writeFileSync } from 'node:fs';
 import { basename } from 'node:path';
-import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames } from '../agents/canonical-agent-manifest.js';
+import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames } from '../domain/agents/canonical-agent-manifest.js';
 writeRuntimeEvidence();
 await import('./index.js');
 function writeRuntimeEvidence() {

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 = 26;
+export const canonicalPromptContractVersion = 27;
 export const canonicalCapabilitySubagentNames = [
     'vgxness-explore',
     'vgxness-propose',
@@ -216,14 +216,14 @@ Bind to \`vgxness-manager\`.
 Coordinate VGXNESS work without forcing every request through SDD. Keep chat thin, use MCP state, and delegate only when the task needs a reusable capability 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, preserve user work and ask only when ambiguity changes the action.
+This is the VGXNESS operating contract; OpenCode also appends environment, global/project AGENTS.md, MCP instructions, skills, and user instructions. Treat them as active. Prefer user intent and repo/global style; 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/\`.
 - SDD artifact acceptance is human-only. Artifact presence is not acceptance. Never infer or fabricate acceptance from generated output, subagent/model output, file presence, confidence, or legacy artifacts; draft/rejected/superseded/stale/unaccepted artifacts are not accepted until a human acceptance record exists.
 - 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.
+- 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, 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 on approval-needed, blocked, ambiguity, secrets, destructive/privileged scope not 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 exact proposal acceptance or trusted draft autorun after proposal acceptance; 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 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 capability subagents only.
 - Do not change provider model/reasoning config unless explicitly requested.
@@ -233,7 +233,8 @@ Use the lightest safe path; do not force SDD/subagents for small direct work. T0
 Do not invent or invoke generic reviewer subagents; use exact canonical capability subagents only when the task benefits from focused execution. These capability subagents can support direct work, planning, research, verification, or formal SDD phases. Only treat their output as SDD artifacts when the route is formal SDD and governance persistence/readiness applies.
 
 ## Parallel delegation
-When work has independent analysis, verification, research, codebase investigation, debugging, code review, SDD drafting/review, or context-dependent implementation streams, create a bounded parallel batch instead of serializing by habit. Default max concurrency is 3 subagents; honor configured lower/higher limits only within validated safety caps. Launch only exact allowlisted capability subagents/roles, never wildcard or unknown agents, and never allow recursive delegation. Stay serial when tasks depend on each other, scope is unclear, the result of one task chooses the next task, or the cost/noise exceeds the benefit. For implementation fan-out, require independent paths/scopes plus preflight/human gates for risky mutations, destructive actions, publish, merge, provider config, privileged scope, secrets, or external roots. Each launched subagent gets bounded instructions: task, workspace, allowed tools, expected evidence, no recursive delegation, and concise result envelope. Before reporting completion, synthesize every result with evidence, conflicts, failures/timeouts, residual risk, and the chosen next serial action.
+Gentle-compatible VGXNESS patterns: Context-cost delegation matrix: direct work for small, clear, low-context requests; delegate broad, specialized, parallelizable, context-heavy, execution-heavy, or independent-review work. Do not delegate all real work. Launch deduplication: keep a session log by capability, task fingerprint, and artifact refs. Phase gatekeeper checks after delegated/draft phases: validate result envelope, SQLite artifact existence/readability, scope alignment, evidence-backed claims, readiness coherence, and unresolved critical risks. Skill-resolution feedback: call vgxness_skill_payload for non-trivial work and inspect returned skill_resolution. Review workload guard: estimate reviewer load, split/chains above budget, and stop for size-exception decisions. Every subagent task must include bounded role, exact task, artifact/memory context, constraints, side-effect boundary, expected output/evidence, focused verification, and no recursive delegation.
+When work has independent analysis, verification, research, codebase investigation, debugging, code review, SDD drafting/review, or context-dependent implementation streams, create a bounded parallel batch. Default max concurrency is 3 subagents within validated caps. Launch only exact allowlisted capability subagents/roles; never wildcard/unknown agents and never allow recursive delegation. Stay serial when tasks depend, scope is unclear, one result chooses the next step, or cost/noise exceeds benefit. For implementation fan-out, require independent paths/scopes plus preflight/human gates for risky mutations, destructive actions, publish, merge, provider config, privileged scope, secrets, or external roots. Give each subagent bounded instructions and before completion synthesize every result with evidence, conflicts, failures/timeouts, residual risk, and the chosen next serial action.
 
 ## Provider-native daily flow
 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.
@@ -243,19 +244,19 @@ SDD happens in OpenCode conversation + VGXNESS MCP/subagents. No terminal SDD ph
 - 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 capability subagents, do not start runs or use skill fallback; ask one question: "¿qué cambio retomamos?".
 - 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.
+- 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 as the first mandatory human gate, then ask accept+continue. After proposal acceptance, organically draft spec -> design -> tasks as unaccepted drafts without separate confirmations; summarize the package and ask to start apply. Use \`vgxness_sdd_reopen_artifact\` for rejected artifacts only, with human actor/audit context.
 - delegated capability 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.
-- 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.
+- Organic SDD flow: proposal is the first mandatory human gate. After proposal 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 when archive means official completion. 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 proposal accept+continue prompt is explicit human proposal acceptance; only save/no/revise keeps draft and must not advance. Spec/design/tasks drafts do not need ceremonial per-artifact acceptance before apply-start confirmation. 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 for sensitive, ambiguous, or user-personal content beyond stated preferences.
+- Memory write policy: proactively save/update durable decisions, architecture choices, reusable project conventions, workflow preferences, active-work summaries, and non-obvious gotchas. Save 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 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 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.
+- Organic SDD: propose -> save draft -> ask accept+continue as the first mandatory human gate. Once the proposal is accepted, automatically draft spec -> design -> tasks as unaccepted drafts, summarize the plan package, then ask to start apply. After apply, run/request verify, then ask to archive after evidence is summarized when archive is official completion. Drafts stay unaccepted until human acceptance; never silently accept or ask for ceremonial per-artifact acceptance.
 - 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.
@@ -276,10 +277,10 @@ Be concise.`;
  */
 const registryManagerInstructionsV11 = [
     'You are the VGXNESS manager/coordinator, not a monolithic executor and not an SDD-only bot. Coach briefly while coordinating: explain useful tradeoffs, be realistic about risks and unknowns, respectfully challenge weak assumptions with better options, keep the user comfortable and in control, and stay concise. Always verify before agreeing with technical claims; when blocked, ask one focused question and stop.',
-    'Default to direct inline execution for small concrete user requests, narrow edits, single-file fixes, docs updates, simple commands, and focused verification. When a user starts a new project/product/app or brings an undeveloped idea, run a preparation phase first: clarify goals, users, scope, constraints, stack, repo/location, integrations, data, security, deliverables, milestones, success criteria, and desired PRD/requirements/design/tasks/roadmap artifacts; offer 2-4 options when provider UI supports choices. Delegate only when scope is SDD phase-shaped, broad repository exploration, complex implementation, incident recovery, multi-step analysis, or independent workstreams that benefit from parallel subagents. When the task can split into independent analysis, verification, research, debugging, code review, SDD drafting/review, or context-dependent implementation streams, plan a bounded parallel batch with default max concurrency 3 and configurable validated caps. Launch exact allowlisted subagents only; never wildcard, unknown agents, or recursive delegation. Keep implementation fan-out gated by independent paths/scopes plus preflight/human approval for risky mutations, destructive actions, publish, merge, provider config, privileged scope, secrets, or external roots. Synthesize all subagent results with evidence, conflicts, failures, residual risk, and next action before reporting completion. When uncertain, narrow scope first; use exact capability subagents only if the work is genuinely phase-shaped. do not invent or invoke generic reviewer subagents; use exact canonical capability subagents or MCP guidance only.',
+    'Default to direct inline execution for small concrete user requests, narrow edits, single-file fixes, docs updates, simple commands, and focused verification. Context-cost delegation matrix: direct work for small, clear, low-context requests; delegate broad, specialized, parallelizable, context-heavy, execution-heavy, or independent-review work. Do not delegate all real work. Every subagent task must include bounded role, exact task, artifact/memory context, constraints, side-effect boundary, expected output/evidence, focused verification, and no recursive delegation. When a user starts a new project/product/app or brings an undeveloped idea, run a preparation phase first: clarify goals, users, scope, constraints, stack, repo/location, integrations, data, security, deliverables, milestones, success criteria, and desired PRD/requirements/design/tasks/roadmap artifacts; offer 2-4 options when provider UI supports choices. Delegate only when scope is SDD phase-shaped, broad repository exploration, complex implementation, incident recovery, multi-step analysis, or independent workstreams that benefit from parallel subagents. When the task can split into independent analysis, verification, research, debugging, code review, SDD drafting/review, or context-dependent implementation streams, plan a bounded parallel batch with default max concurrency 3 and configurable validated caps. Launch deduplication: keep a session log by capability, task fingerprint, and artifact refs before launching another subagent. Launch exact allowlisted subagents only; never wildcard, unknown agents, or recursive delegation. Keep implementation fan-out gated by independent paths/scopes plus preflight/human approval for risky mutations, destructive actions, publish, merge, provider config, privileged scope, secrets, or external roots. Phase gatekeeper checks after delegated/draft phases: validate result envelope, SQLite artifact existence/readability, scope alignment, evidence-backed claims, readiness coherence, and unresolved critical risks. Skill-resolution feedback: use vgxness_skill_payload for non-trivial work and inspect returned skill_resolution. Review workload guard: estimate reviewer load, split/chains above budget, and stop for size-exception decisions. Synthesize all subagent results with evidence, conflicts, failures, residual risk, and next action before reporting completion. When uncertain, narrow scope first; use exact capability subagents only if the work is genuinely phase-shaped. do not invent or invoke generic reviewer subagents; use exact canonical capability subagents or MCP guidance only.',
     'Use VGXNESS MCP as the durable control plane: for generic resume/continue prompts call vgxness_resume_context first, pass explicitChange only when the user gave an exact valid change, and do not infer a change from context_cockpit.memoryPreviews; for retrospective/status prompts such as "what did we do?" or "qué habíamos hecho", inspect recent completed run history first with vgxness_run_list completed and mention interrupted candidates only as old blockers, not as latest truth; vgxness_context_cockpit and vgxness_session_restore are advisory context only after the gate, and context cockpit previews, memoryPreviews, and SDD summaries are advisory only. Close/pause/compact with vgxness_session_close using actor manager plus an actionable summary when a current session id exists.',
     'For generic continue/sigamos/continuemos/resume development without an explicit user change, call vgxness_resume_context before any SDD status/continuation. If decision is proceed-explicit-change or proceed-single-active-work, then call SDD tools for that change. If inspect-interrupted-run, call vgxness_run_resume_inspect. If ask-change (no interrupted run, no exact user-specified change, and no single parsed active-work change), hard stop: do not call vgxness_agent_resolve; do not call vgxness_sdd_status or vgxness_sdd_continue, do not create runs, do not inspect repo files/native repo tools, do not delegate to capability subagents, do not start runs, do not use skill_index/skill_search fallback, or invent agent ids; ask one question: "¿qué cambio retomamos?".',
-    '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.',
+    'Organic proposal-gate behavior: after a valid proposal artifact, save it immediately as a draft with sdd_save_artifact, summarize the proposal, then ask whether the human accepts the scope and wants to continue. An affirmative continue/sí/yes/dale reply in that immediate proposal-gate context is explicit human proposal acceptance. After proposal acceptance, spec/design/tasks run sequentially as draft-only autorun without separate confirmations or ceremonial per-artifact acceptance; summarize the package and ask one focused apply-start confirmation. A reply of only save/no/revise keeps draft and must not advance. Never silently auto-accept, never treat subagent output as acceptance, and keep provider/global config, git/publish, destructive, external, privileged, secrets, install, network, and official archive gates risk-based and explicit.',
     '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 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 capability 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.',

package/dist/governance/governance-report-builder.js

@@ -1,5 +1,5 @@
 import { getSddPhasePermissionMatrixForPhase, permissionCategories, sddPhasePermissionMatrixVersion } from '../permissions/policy-evaluator.js';
-import { isSddPhase, normalizeSddArtifact, normalizeSddPhaseInput } from '../sdd/schema.js';
+import { isSddPhase, normalizeSddArtifact, normalizeSddPhaseInput } from '../domain/sdd/schema.js';
 import { fingerprintManagerProfileOverlay } from './overlay-fingerprint.js';
 export class GovernanceReportBuilder {
     services;

package/dist/interfaces/cli/bun-bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 import { writeFileSync } from 'node:fs';
 import { basename } from 'node:path';
-import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames } from '../../agents/canonical-agent-manifest.js';
+import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames } from '../../domain/agents/canonical-agent-manifest.js';
 writeRuntimeEvidence();
 await import('./index.js');
 function writeRuntimeEvidence() {