vgxness 1.9.0 → 1.9.2

package/README.md

@@ -8,6 +8,8 @@ This package is proprietary software. The npm package ships inspectable JavaScri
 
 OpenCode is the primary supported provider. Other providers remain preview/manual only. Provider config writes require explicit CLI confirmation.
 
+VGXNESS v1.9.1 has a canonical project health audit with validated evidence: 38 MCP tools, 106 test files, and the official Bun validation path passing, including package evidence with `releaseReadiness: pass`. See [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md) for the versioned matrix and safety taxonomy.
+
 ## Requirements
 
 - Bun >= 1.3.14 for the installed `vgxness`/`vgx` CLI/MCP runtime and repository verification
@@ -25,6 +27,7 @@ bun install --frozen-lockfile
 bun run check:bun-lock
 bun run verify:typecheck
 bun run verify:test
+bun run verify:test:bun-storage
 bun run verify:bun-sqlite
 bun run verify:package
 bun run package:bun:evidence -- --require-pass
@@ -86,7 +89,7 @@ Release-candidate checklist, still non-publishing:
 
 1. `bun install --frozen-lockfile` completes on a clean checkout.
 2. `bun run check:bun-lock` passes.
-3. `bun run verify:typecheck`, `bun run verify:test`, and `bun run verify:bun-sqlite` pass.
+3. `bun run verify:typecheck`, `bun run verify:test`, `bun run verify:test:bun-storage`, and `bun run verify:bun-sqlite` pass.
 4. `bun run package:bun:evidence -- --require-pass` passes on supported CI OSes.
 5. JSON evidence shows `status: pass`, artifact/install smoke pass, no retired bridge scripts, no `package-lock.json`, `publicationAttempted: false`, and `releaseReadiness.status: pass`.
 6. Version, release notes, proprietary license boundary, and rollback criteria are reviewed.
@@ -156,7 +159,7 @@ Apply only after reviewing the plan:
 vgxness setup apply --yes
 ```
 
-`vgxness setup plan` and `vgxness setup status` are human-readable and read-only by default. `vgxness doctor`, `vgxness sdd status`, `vgxness sdd next`, 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.
+`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 sdd status`, `vgxness sdd next`, 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.
 
 ## Code runtime (`vgxness code`)
 
@@ -173,7 +176,7 @@ Edits, shell, network, git mutations, SDD persistence, and memory saves route th
 
 ## Safety model
 
-- Preview, status, and plan commands are read-only.
+- Preview, status, and plan commands do not write provider config; local VGXNESS store initialization may occur where the command needs SQLite-backed state.
 - Provider config writes require explicit `--yes` confirmation.
 - Setup/status TUI surfaces are preview-oriented; run copied commands explicitly when you choose to act.
 - SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write `openspec/`.
@@ -236,6 +239,7 @@ bun install --frozen-lockfile
 bun run check:bun-lock
 bun run verify:typecheck
 bun run verify:test
+bun run verify:test:bun-storage
 bun run verify:bun-sqlite
 bun run package:bun:evidence -- --require-pass
 ```
@@ -255,6 +259,7 @@ Remove any OpenCode config entries and local/global VGXNESS data manually if you
 ## More docs
 
 - [CLI reference](./docs/cli.md)
+- [Project health audit v1.9.1](./docs/project-health-audit-v1.9.1.md)
 - [Architecture](./docs/architecture.md)
 - [Code runtime](./docs/code-runtime.md)
 - [MCP tools](./docs/mcp.md)

package/dist/agents/agent-activation-service.js

@@ -98,14 +98,23 @@ export class AgentActivationService {
         return this.dependencies.agents.getAgentByName(input.project, input.scope, defaultAgentName);
     }
     failAfterRun(runId, code, message) {
-        this.dependencies.runs.appendEvent({
+        const nestedFailures = [];
+        const eventResult = this.dependencies.runs.appendEvent({
             runId,
             kind: 'timeline',
             title: 'Agent activation failed',
-            payload: { error: { code: String(code), message }, nextSafeActionReturned: false },
+            payload: toJson({ error: { code: String(code), message }, nextSafeActionReturned: false }),
         });
-        this.dependencies.runs.updateFinalStatus({ runId, status: 'failed', outcome: 'failure', outcomeReason: message });
-        return { ok: false, error: { code, message } };
+        if (!eventResult.ok) {
+            nestedFailures.push({ step: 'append-event', code: String(eventResult.error.code), message: eventResult.error.message });
+        }
+        const finalStatusResult = this.dependencies.runs.updateFinalStatus({ runId, status: 'failed', outcome: 'failure', outcomeReason: message });
+        if (!finalStatusResult.ok) {
+            nestedFailures.push({ step: 'update-final-status', code: String(finalStatusResult.error.code), message: finalStatusResult.error.message });
+        }
+        return nestedFailures.length === 0
+            ? { ok: false, error: { code, message } }
+            : { ok: false, error: { code, message, cause: { nestedFailures } } };
     }
 }
 function validateActivationInput(input) {

package/dist/agents/agent-registry-service.js

@@ -32,8 +32,14 @@ export class AgentRegistryService {
         this.database.close();
     }
     listAgentDefinitions(input) {
-        void input;
-        const summaries = this.agents.list();
+        const filters = {};
+        if (input.project !== undefined)
+            filters.project = input.project;
+        if (input.scope !== undefined)
+            filters.scope = input.scope;
+        if (input.mode !== undefined)
+            filters.mode = input.mode;
+        const summaries = this.agents.list(filters);
         if (!summaries.ok)
             return summaries;
         const definitions = [];

package/dist/agents/agent-seed-upgrade-service.js

@@ -0,0 +1,231 @@
+import { canonicalAgentManifest, canonicalPromptContractVersion, canonicalSddSubagentNames } from './canonical-agent-manifest.js';
+import { projectCanonicalAgentManifestToSeed } from './canonical-agent-projection.js';
+export class AgentSeedUpgradeService {
+    agents;
+    history;
+    database;
+    constructor(dependencies) {
+        this.agents = dependencies.agents;
+        this.history = dependencies.history;
+        this.database = dependencies.database;
+    }
+    upgrade(input) {
+        if (!input.project.trim())
+            return validationFailure('Agent seed upgrade project is required');
+        if (input.scope !== 'project' && input.scope !== 'personal')
+            return validationFailure('Agent seed upgrade scope is invalid');
+        const seed = projectCanonicalAgentManifestToSeed();
+        const canonicalByName = new Map();
+        for (const agent of seed.agents)
+            canonicalByName.set(agent.name, agent);
+        for (const subagent of seed.subagents)
+            canonicalByName.set(subagent.name, subagent);
+        const source = input.source ?? 'boot-upgrade';
+        const summary = {
+            created: [],
+            upgraded: [],
+            noop: [],
+            overwritten: [],
+            errors: [],
+            skipped: false,
+        };
+        const expected = canonicalPromptContractVersion;
+        const transaction = this.database.transaction(() => {
+            for (const [name, definition] of canonicalByName) {
+                const outcome = this.upgradeOne(input.project, input.scope, name, definition, source, expected);
+                if (outcome.ok) {
+                    switch (outcome.value.outcome) {
+                        case 'created':
+                            summary.created.push(name);
+                            break;
+                        case 'upgraded':
+                            summary.upgraded.push(name);
+                            break;
+                        case 'overwrote-custom-instructions':
+                            summary.overwritten.push(name);
+                            break;
+                        case 'noop':
+                            summary.noop.push(name);
+                            break;
+                    }
+                }
+                else {
+                    const failureOutcome = outcome.error.code === 'validation_failed' ? 'validation_failed' : 'db_error';
+                    summary.errors.push({ agentName: name, outcome: failureOutcome, reason: outcome.error.message });
+                }
+            }
+            return summary;
+        });
+        if (!transaction.ok) {
+            return { ok: false, error: transaction.error };
+        }
+        return transaction;
+    }
+    hasDrift(input) {
+        const expected = input.expectedVersion ?? canonicalPromptContractVersion;
+        try {
+            const canonicalNames = [canonicalAgentManifest.defaultAgentName, ...canonicalSddSubagentNames];
+            const placeholders = canonicalNames.map(() => '?').join(', ');
+            const row = this.database.connection
+                .prepare(`
+        SELECT COUNT(*) AS stale_count
+        FROM agents
+        WHERE project = ? AND scope = ? AND name IN (${placeholders})
+          AND json_extract(adapters_json, '$.opencode.config.options.vgxnessPromptContractVersion') <> ?
+      `)
+                .get(input.project, input.scope, ...canonicalNames, expected);
+            return ok((row?.stale_count ?? 0) > 0);
+        }
+        catch (cause) {
+            return fail('Failed to detect agent seed drift', cause);
+        }
+    }
+    upgradeOne(project, scope, name, definition, source, expected) {
+        const existing = this.agents.getByName(project, scope, name);
+        const fromVersion = existing.ok ? readPromptContractVersion(existing.value) : null;
+        if (existing.ok && fromVersion === expected && isByteEqualToCanonical(existing.value, definition)) {
+            return ok({ outcome: 'noop', fromVersion: expected });
+        }
+        const parentAgentId = 'parentAgentName' in definition ? this.resolveParentId(project, scope, definition.parentAgentName) : undefined;
+        if ('parentAgentName' in definition && parentAgentId === undefined) {
+            return validationFailure(`Unresolved parentAgentName: ${definition.parentAgentName}`);
+        }
+        const registerInput = toRegisterInput(project, scope, definition, parentAgentId);
+        const registered = this.agents.register(registerInput);
+        if (!registered.ok) {
+            this.appendHistory({
+                project,
+                scope,
+                agentName: name,
+                fromVersion,
+                toVersion: expected,
+                outcome: registered.error.code === 'validation_failed' ? 'validation_failed' : 'db_error',
+                reason: registered.error.message,
+                source,
+            });
+            return registered;
+        }
+        let outcome;
+        if (!existing.ok) {
+            outcome = 'created';
+        }
+        else if (fromVersion !== null && fromVersion !== expected) {
+            outcome = 'upgraded';
+        }
+        else {
+            outcome = 'overwrote-custom-instructions';
+        }
+        this.appendHistory({
+            project,
+            scope,
+            agentName: name,
+            fromVersion,
+            toVersion: expected,
+            outcome,
+            reason: outcomeReason(outcome, fromVersion, expected, existing.ok),
+            source,
+        });
+        return ok({ outcome, fromVersion });
+    }
+    resolveParentId(project, scope, parentAgentName) {
+        const parent = this.agents.getByName(project, scope, parentAgentName);
+        if (!parent.ok || parent.value.mode !== 'agent')
+            return undefined;
+        return parent.value.id;
+    }
+    appendHistory(input) {
+        this.history.append({
+            project: input.project,
+            scope: input.scope,
+            agentName: input.agentName,
+            fromVersion: input.fromVersion,
+            toVersion: input.toVersion,
+            outcome: input.outcome,
+            reason: input.reason,
+            source: input.source,
+        });
+    }
+}
+function toRegisterInput(project, scope, definition, parentAgentId) {
+    const input = {
+        project,
+        scope,
+        mode: 'parentAgentName' in definition ? 'subagent' : 'agent',
+        name: definition.name,
+        description: definition.description,
+        instructions: definition.instructions,
+    };
+    if (definition.capabilities !== undefined)
+        input.capabilities = definition.capabilities;
+    if (definition.permissions !== undefined)
+        input.permissions = definition.permissions;
+    if (definition.memory !== undefined)
+        input.memory = definition.memory;
+    if (definition.workflows !== undefined)
+        input.workflows = definition.workflows;
+    if (definition.skills !== undefined)
+        input.skills = definition.skills;
+    if (definition.adapters !== undefined)
+        input.adapters = definition.adapters;
+    if (parentAgentId !== undefined)
+        input.parentAgentId = parentAgentId;
+    return input;
+}
+function isByteEqualToCanonical(existing, definition) {
+    if (existing.description !== definition.description)
+        return false;
+    if (existing.instructions.value !== definition.instructions.value)
+        return false;
+    if (!adaptersEqual(existing.adapters, definition.adapters ?? {}))
+        return false;
+    if (!arraysEqual(existing.capabilities, definition.capabilities ?? []))
+        return false;
+    if (!arraysEqual(existing.workflows, definition.workflows ?? []))
+        return false;
+    if (!arraysEqual(existing.skills, definition.skills ?? []))
+        return false;
+    return true;
+}
+function adaptersEqual(a, b) {
+    return JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function readPromptContractVersion(agent) {
+    const opencode = agent.adapters?.opencode;
+    if (opencode === undefined)
+        return null;
+    const options = opencode.config?.options;
+    const value = options?.vgxnessPromptContractVersion;
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return null;
+    return value;
+}
+function outcomeReason(outcome, fromVersion, toVersion, existed) {
+    if (outcome === 'created')
+        return `created canonical row at v${toVersion}`;
+    if (outcome === 'upgraded')
+        return `upgraded v${fromVersion ?? 'unknown'} -> v${toVersion}`;
+    if (outcome === 'overwrote-custom-instructions')
+        return `overwrote customized row (was v${fromVersion ?? 'unknown'}) with v${toVersion} canonical`;
+    return existed ? `noop at v${toVersion}` : `noop at v${toVersion}`;
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}
+function fail(message, cause) {
+    const error = { code: 'validation_failed', message };
+    if (cause !== undefined)
+        error.cause = cause;
+    return { ok: false, error };
+}

package/dist/agents/boot-upgrade.js

@@ -0,0 +1,59 @@
+import { AgentSeedUpgradeService } from './agent-seed-upgrade-service.js';
+import { AgentRepository } from './repositories/agents.js';
+import { AgentSeedHistoryRepository } from './repositories/agent-seed-history.js';
+import { canonicalAgentManifest } from './canonical-agent-manifest.js';
+const skipEnvVar = 'VGXNESS_SKIP_AGENT_SEED_AUTO_UPGRADE';
+export function runBootAgentSeedUpgrade(database, env = process.env, project = canonicalAgentManifest.project, scope = canonicalAgentManifest.scope) {
+    if (isOptOut(env)) {
+        return { ok: true, skipped: true, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 0 };
+    }
+    try {
+        const service = new AgentSeedUpgradeService({
+            agents: new AgentRepository(database),
+            history: new AgentSeedHistoryRepository(database),
+            database,
+        });
+        const result = service.upgrade({ project, scope, source: 'boot-upgrade' });
+        if (!result.ok) {
+            const message = `boot-upgrade failed: ${result.error.message} (code=${result.error.code})`;
+            process.stderr.write(`[vgxness] ${message}\n`);
+            return { ok: false, skipped: false, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 1, message };
+        }
+        const value = result.value;
+        const touched = value.created.length + value.upgraded.length + value.overwritten.length + value.errors.length;
+        if (touched > 0) {
+            const parts = [];
+            if (value.created.length > 0)
+                parts.push(`created ${value.created.length}`);
+            if (value.upgraded.length > 0)
+                parts.push(`upgraded ${value.upgraded.length}`);
+            if (value.overwritten.length > 0)
+                parts.push(`overwrote ${value.overwritten.length}`);
+            if (value.errors.length > 0)
+                parts.push(`errors ${value.errors.length}`);
+            process.stderr.write(`[vgxness] boot-upgrade: ${parts.join(', ')}\n`);
+            for (const error of value.errors) {
+                process.stderr.write(`[vgxness] boot-upgrade: ${error.agentName} ${error.outcome}: ${error.reason}\n`);
+            }
+        }
+        return {
+            ok: true,
+            skipped: false,
+            created: value.created.length,
+            upgraded: value.upgraded.length,
+            overwritten: value.overwritten.length,
+            noop: value.noop.length,
+            errors: value.errors.length,
+        };
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+        const message = `boot-upgrade threw: ${detail}`;
+        process.stderr.write(`[vgxness] ${message}\n`);
+        return { ok: false, skipped: false, created: 0, upgraded: 0, overwritten: 0, noop: 0, errors: 1, message };
+    }
+}
+function isOptOut(env) {
+    const value = env[skipEnvVar];
+    return value === '1' || value === 'true';
+}

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

@@ -1,5 +1,6 @@
+import { canonicalBehaviorContractVersion } from '../behavior/behavior-contract-manifest.js';
 export const canonicalDefaultAgentName = 'vgxness-manager';
-export const canonicalPromptContractVersion = 6;
+export const canonicalPromptContractVersion = 7;
 export const canonicalSddSubagentNames = [
     'vgxness-sdd-explore',
     'vgxness-sdd-propose',
@@ -81,7 +82,7 @@ function managerDefinition() {
         memory: { scopes: ['project'] },
         workflows: ['explore', 'quickfix', 'plan', 'build', 'debug', 'sdd', 'agent-seeding', 'opencode-install'],
         skills: ['vgxness-sdd-manager'],
-        adapters: { opencode: { model: 'openai/gpt-5.5', config: { options: { reasoningEffort: 'high', vgxnessPromptContractVersion: canonicalPromptContractVersion }, permission: { task: createCanonicalOpenCodeSddTaskPermissions() } } } },
+        adapters: { opencode: { model: 'openai/gpt-5.5', config: { options: { reasoningEffort: 'high', vgxnessPromptContractVersion: canonicalPromptContractVersion, vgxnessBehaviorContractVersion: canonicalBehaviorContractVersion }, permission: { task: createCanonicalOpenCodeSddTaskPermissions() } } } },
         providerSupport: commonSupport(),
     };
 }
@@ -100,7 +101,7 @@ function subagentDefinition(name) {
         memory: { scopes: ['project'] },
         workflows: data.workflows,
         skills: data.skills,
-        adapters: { opencode: { model: 'openai/gpt-5.5', config: { hidden: true, options: { vgxnessPromptContractVersion: canonicalPromptContractVersion } } } },
+        adapters: { opencode: { model: 'openai/gpt-5.5', config: { hidden: true, options: { vgxnessPromptContractVersion: canonicalPromptContractVersion, vgxnessBehaviorContractVersion: canonicalBehaviorContractVersion } } } },
         providerSupport: commonSupport(),
     };
 }
@@ -118,45 +119,44 @@ export const canonicalOpenCodeManagerPrompt = `# VGXNESS Manager - compact SDD o
 Bind only to the primary \`vgxness-manager\` agent. Executor agents (for example \`vgxness-sdd-apply\`) use their own prompts.
 
 ## Role
-Coordinate SDD; do not become a monolithic executor. Keep the chat thin, use VGXNESS MCP as durable state, delegate phase work to the smallest exact hidden SDD subagent, then synthesize concise evidence for the user. Be direct, practical, repository-grounded, user-controlled, and willing to challenge unsafe or weak assumptions.
-
-Coach while coordinating: teach briefly when helpful, explain practical tradeoffs, stay realistic about risk/effort/unknowns, respectfully challenge weak assumptions, keep the user comfortable and in control, and avoid lectures or unnecessary verbosity.
+Coordinate SDD; keep chat thin, use VGXNESS MCP as durable state, delegate to the smallest exact hidden SDD subagent, then synthesize evidence. Coach while coordinating: teach briefly, explain practical tradeoffs, stay realistic about risk/effort/unknowns, respectfully challenge weak assumptions, keep the user comfortable and in control, and avoid lectures or unnecessary verbosity.
 
 ## Non-negotiable governance
-- SDD artifact acceptance is human-only. Never infer acceptance from generated output, file presence, confidence, or legacy artifacts. Treat draft/rejected/superseded/unaccepted artifacts as not accepted until a human acceptance record exists.
+- SDD artifact acceptance is human-only. Never infer or fabricate acceptance from generated output, subagent/model output, file presence, confidence, or legacy artifacts. Treat draft/rejected/superseded/stale/unaccepted artifacts as not accepted until a human acceptance record exists.
 - Before phase advancement, call readiness/status tools: \`vgxness_sdd_status\`/\`vgxness_sdd_next\` and \`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 context when available. If approval/block is required, stop; do not invent approval.
+- Direct human acceptance of an exact SDD artifact via \`vgxness_sdd_accept_artifact\` is not a generic SDD write for manager routing: do not call \`vgxness_run_preflight\` solely for that acceptance when the user explicitly accepted the exact project/change/phase artifact, \`acceptedBy.type\` is \`"human"\`, \`acceptedBy.id\` is non-empty, and status/readiness confirms the artifact is eligible. This shortcut applies only to \`vgxness_sdd_accept_artifact\`, not \`vgxness_sdd_save_artifact\`, edits, shell/tests, git, provider config, memory writes, external paths, secrets, destructive/privileged/ambiguous operations.
 - OpenCode native/provider tools are governance-v1 audit-only/non-hard-blocking. Report warnings; do not say native OpenCode tools are hard-blocked by config.
 - Do not mutate provider/global OpenCode config unless explicitly requested. Do not write to \`openspec/\`. Never revert/overwrite unrelated user work. Preserve \`permission.task\` deny-by-default with only exact known SDD subagents allowed.
 - Do not publish packages unless explicitly requested.
 - Do not change model or reasoning effort.
 
 ## Flexible governance routing
-Use the lightest safe path: Tier 0-2 direct/explore/plan/debug/quickfix/build; keywords alone do not force SDD. Tier 3 needs preflight/explicit validation but not automatic SDD. Tier 4 governance, permission model, SDD acceptance, architecture/security semantics, or cross-surface workflow behavior uses formal SDD. Provider status/doctor/preview/handoff are read-only audit-only; provider config writes stay gated.
+Use the lightest safe path: Tier 0-2 direct; Tier 3 preflight/explicit validation; Tier 4 formal SDD for governance, permission model, SDD acceptance, architecture/security, or cross-surface behavior. Provider status/doctor/preview/handoff are read-only audit-only; provider config writes stay gated.
 
 ## Provider-native daily flow
-Normal SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not tell users to run terminal SDD phase commands for daily flow. CLI is an escape hatch only for bootstrap, doctor, rollback/recovery, MCP unavailable/setup missing, provider-native repair out of scope, or explicit user request.
+Daily SDD happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not tell users to run terminal SDD phase commands for normal flow. CLI is an escape hatch for bootstrap, doctor, recovery, setup gaps, or explicit request.
 
 ## MCP playbook
-- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\` with project + workspace; treat \`vgxness_session_restore\` as one signal inside the cockpit, not authoritative truth. If cockpit is unavailable, use \`vgxness_session_restore\` with project + workspace before inferring state. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one, say so and include summary in final response.
-- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; use \`payloadMode: "compact"\` by default for manager-facing reads/lists so the primary context stays clean. Use \`payloadMode: "verbose"\` only when full content is truly required, preferably inside the delegated phase subagent rather than the manager context. Save phase output with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
-- Acceptance/readiness: confirm explicit human acceptance, use \`vgxness_sdd_accept_artifact\` only for explicit human acceptance, then \`vgxness_sdd_get_readiness\`/readiness tools before reporting state. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, and audit warnings before risky/ambiguous transitions and in apply/verify summaries.
-- Memory: call \`vgxness_memory_search\`/\`vgxness_memory_get\` when prior work or unclear project context is referenced; call \`vgxness_memory_save\` for durable discoveries, decisions, bug fixes, config, patterns, or preferences; use \`vgxness_memory_update\` only to correct/evolve a known id. Do not duplicate full SDD artifacts as memory.
-- Agents/profile/payloads: resolve exact phase with \`vgxness_agent_resolve\`. \`vgxness_agent_activate\`, \`vgxness_opencode_manager_payload\`, and \`vgxness_skill_payload\` prepare/read preview context only; agent_activate does not execute a provider or write provider config. Use \`vgxness_manager_profile_get\` before behavior changes; \`vgxness_manager_profile_set\` requires explicit human authorization.
+- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\` with project + workspace; treat \`vgxness_session_restore\` as one signal, not truth. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one and summarize.
+- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; use \`payloadMode: "compact"\` by default so the primary context stays clean. Use verbose only when required, preferably inside the delegated phase subagent. Save with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
+- Acceptance/readiness: check SDD status/readiness for the exact project/change/phase, confirm explicit human acceptance of that exact artifact, call \`vgxness_sdd_accept_artifact\` directly with audit context (\`acceptedBy.type: "human"\`, non-empty \`acceptedBy.id\`, runId, agentId, note/rationale when useful), then re-check status/readiness before reporting state. Do not add \`vgxness_run_preflight\` solely for that exact direct acceptance call. Ambiguous replies count only when tied to an immediate exact acceptance prompt. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, and audit warnings before risky/ambiguous transitions and in apply/verify summaries.
+- Memory: call \`vgxness_memory_search\`/\`vgxness_memory_get\` for prior work or unclear context; call \`vgxness_memory_save\` for durable discoveries, decisions, bug fixes, config, patterns, or preferences; use \`vgxness_memory_update\` only to correct/evolve a known id. Do not duplicate full SDD artifacts as memory.
+- Agents/profile/payloads: resolve exact phase with \`vgxness_agent_resolve\`. \`vgxness_agent_activate\`, \`vgxness_opencode_manager_payload\`, and \`vgxness_skill_payload\` are preview context only; agent_activate does not execute a provider or write provider config. Use \`vgxness_manager_profile_get\` before behavior changes; \`vgxness_manager_profile_set\` requires explicit human authorization.
 - Runs: use \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\` for significant implementation/verification or multi-step delegated work; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\`, and close with \`vgxness_run_finalize\`.
 - Provider diagnostics: \`vgxness_provider_status\` and \`vgxness_provider_doctor\` are read-only reports.
 
 ## Minimum flows
-- Simple answer: respond inline; memory only if prior context is referenced; no run by default.
-- Proposal/spec/design/tasks: status/next -> readiness -> read prerequisites -> resolve exact subagent -> delegate -> persist returned output only according to acceptance/governance.
-- Apply/verify: require tasks/apply-progress as appropriate -> read artifacts -> resolve exact subagent -> recover/start run -> preflight writes/shell/git/tests -> delegate -> checkpoint -> save apply-progress/verify -> finalize when clear.
+- Simple answer: inline; memory only for prior context; no run by default.
+- Proposal/spec/design/tasks: status/next -> readiness -> read prerequisites -> resolve exact subagent -> delegate -> persist by governance.
+- Apply/verify: require prerequisites -> read artifacts -> resolve exact subagent -> start/recover run -> preflight writes/shell/git/tests -> delegate -> checkpoint -> save output -> finalize when clear.
 - Config/provider/prompt change: inspect manager/profile or payload first; persistent changes require explicit human authorization.
 
 ## Delegation thresholds
-Inline only small decisions, 1-3 file reads, status commands, and atomic one-file mechanical edits. Delegate broad exploration (4+ files), substantial implementation, writes with analysis/new logic, and execution-heavy verification. Never delegate to unknown agents; use exact SDD phase mapping: explore/propose/spec/design/tasks/apply/verify/archive/init/onboard.
+Inline only small decisions, 1-3 file reads, status commands, and atomic one-file mechanical edits. Delegate broad exploration, substantial implementation, writes with analysis/new logic, and execution-heavy verification. Never delegate to unknown agents; use exact SDD phase mapping.
 
 ## Output
-Be concise: what was delegated, what came back, files/decisions changed, evidence/tests, risks, and next step.`;
+Be concise: delegated work, results, files/decisions, evidence/tests, risks, next step.`;
 const registryManagerInstructions = 'You are the VGXNESS SDD coordinator, not a monolithic executor. 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. Use VGXNESS MCP as the durable control plane: restore session context with vgxness_session_restore before inferring start/resume state from chat, and close/pause/compact with vgxness_session_close using actor manager plus an actionable summary when a current session id exists. Check SDD status/next/ready, read prerequisites with sdd_get_artifact or sdd_list_artifacts, save accepted phase output with sdd_save_artifact, search/get/save/update memory only for reusable knowledge, resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, and use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health. 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. 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. Delegate real SDD phase work to the smallest exact vgxness-sdd-* subagent allowed by permission.task, synthesize results, and persist artifacts/checkpoints. Do not perform substantial multi-file implementation inline. Do not mutate global/provider OpenCode config, install skills, publish packages, or write openspec/ unless explicitly authorized. Checked-in manager and subagent instructions are self-contained; external sdd-* skill files are optional registry assets, not requirements.';
 const subagentData = {
     'vgxness-sdd-explore': { seedDescription: 'Investigates codebase context and identifies options before proposals.', seedInstructions: 'You are the explore phase executor, not the orchestrator. Do not delegate. Explore repository evidence for the requested SDD change. Do not implement code changes. Return concise findings, risks, and recommended next artifacts.', capabilities: ['sdd-exploration', 'codebase-research', 'discovery'], permissions: { read: 'allow', edit: 'deny', shell: 'ask', git: 'deny', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' }, workflows: ['sdd:explore'], skills: ['vgxness-sdd-explore'], phaseContract: 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.' },

package/dist/agents/canonical-agent-projection.js

@@ -73,6 +73,13 @@ export function projectCanonicalAgentManifestToClaudeCode(manifest = canonicalAg
     }
     return { defaultAgent: canonicalDefaultAgentName, agents };
 }
+export function withEffectiveManagerInstructions(projection, instructions) {
+    const trimmed = instructions?.trim() ?? '';
+    if (trimmed === '')
+        return projection;
+    const agents = projection.agents.map((agent) => agent.canonicalName === projection.defaultAgent ? { ...agent, instructions: trimmed } : agent);
+    return { defaultAgent: projection.defaultAgent, agents };
+}
 export function projectCanonicalAgentManifestToClaudeProjectMemory(manifest = canonicalAgentManifest) {
     assertValidCanonicalManifest(manifest);
     return {

package/dist/agents/manager-profile-overlay-service.js

@@ -1,3 +1,5 @@
+import { AgentRegistryService } from './agent-registry-service.js';
+import { ManagerProfileOverlayRepository } from './repositories/manager-profile-overlays.js';
 export class ManagerProfileOverlayService {
     dependencies;
     constructor(dependencies) {
@@ -36,3 +38,15 @@ function ok(value) {
 function validationFailure(message) {
     return { ok: false, error: { code: 'validation_failed', message } };
 }
+export function computeEffectiveManagerInstructions(database, project = 'vgxness', scope = 'project', managerName = 'vgxness-manager') {
+    const registry = new AgentRegistryService(database);
+    const overlays = new ManagerProfileOverlayRepository(database);
+    const service = new ManagerProfileOverlayService({ agents: registry, overlays });
+    const resolved = service.resolveEffectiveManager({ project, scope, managerName });
+    if (!resolved.ok || resolved.value.overlay === undefined)
+        return undefined;
+    const overlayInstructions = resolved.value.overlay.instructions.trim();
+    if (overlayInstructions === '')
+        return undefined;
+    return overlayInstructions;
+}

package/dist/agents/renderers/claude-renderer.js

@@ -1,3 +1,5 @@
+import { canonicalPromptContractVersion } from '../canonical-agent-manifest.js';
+import { canonicalBehaviorContractVersion } from '../../behavior/behavior-contract-manifest.js';
 import { ok, validationFailure } from './provider-adapter.js';
 const previewWarnings = [
     'Claude rendering returns installable preview artifacts only; it does not install and does not write provider configuration.',
@@ -66,7 +68,7 @@ export class ClaudeAgentRenderer {
     }
 }
 function renderClaudeAgentMarkdown(agent, key) {
-    return `---\nname: ${JSON.stringify(key)}\ndescription: ${JSON.stringify(agent.description)}\n---\n\n<!-- VGXNESS-GENERATED claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=6 safe-update=true -->\n\n${agent.instructions.value.trim()}\n`;
+    return `---\nname: ${JSON.stringify(key)}\ndescription: ${JSON.stringify(agent.description)}\n---\n\n<!-- VGXNESS-GENERATED claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=${canonicalPromptContractVersion} behaviorContractVersion=${canonicalBehaviorContractVersion} safe-update=true -->\n\n${agent.instructions.value.trim()}\n`;
 }
 function claudeAgentKey(value) {
     return pathSegment(value);

package/dist/agents/renderers/opencode-renderer.js

@@ -1,3 +1,4 @@
+import { behaviorContractProjectionMetadata } from '../../behavior/behavior-contract-manifest.js';
 import { ok, validationFailure } from './provider-adapter.js';
 const openCodeSchema = 'https://opencode.ai/config.json';
 const previewWarning = 'Rendering returns preview artifacts only; it does not install or write .opencode/, .claude/, or provider configuration.';
@@ -50,7 +51,7 @@ export class OpenCodeAgentRenderer {
         const artifact = {
             relativePath: `rendered/opencode/${pathSegment(input.agent.project)}/${input.agent.scope}/${pathSegment(input.agent.name)}/opencode.json`,
             contentType: 'application/json',
-            contents: `${JSON.stringify({ $schema: openCodeSchema, agent: renderedAgents, safety: previewSafety }, null, 2)}\n`,
+            contents: `${JSON.stringify({ $schema: openCodeSchema, behaviorContract: behaviorContractProjectionMetadata, agent: renderedAgents, safety: previewSafety }, null, 2)}\n`,
         };
         return ok({
             provider: this.provider,